README.md

---

# Environmental Justice Screening Tool for Connecticut Version 2.0

## Overview

This project aims to develop an environmental justice screening tool specifically designed for Connecticut. The tool utilizes various data sources and analytical techniques to identify areas with environmental justice concerns, helping policymakers, researchers, and activists to prioritize actions and resources effectively. For more information, please visit https://connecticut-environmental-justice.circa.uconn.edu/

## Features

- **Data Integration**: Integrates diverse datasets including environmental, socio-economic, and demographic data relevant to Connecticut.
- **Analysis**: Performs spatial and statistical analyses to identify areas facing environmental justice issues.
- **Visualization**: Provides interactive maps and visualizations to present the screening results in an understandable format.
- **Scalability**: Designed to be scalable for potential expansion and adaptation to other regions or states.

## Installation

To install and run the environmental justice screening tool, follow these steps:

1. Install Git Large File Storage (Git LFS), which is required due to the various large data file sizes. [Visit git-lfs.com for installation instructions and downloads.](https://git-lfs.com/)

1. Once installed, set up Git LFS with this command:
    ```
    git lfs install
    ```

1. Clone this repository to your local machine.
    ```
    git clone https://github.uconn.edu/CIRCA/CTEJScreen_v2.0.git
    ```

2. Navigate to the project directory.
    ```
    cd your-folder
    ```

3. Open the desired files in Matlab. This project was written in and is compatible with R2023a.

CTEJScreen uses large amounts of data, so the installation may take some time and require a significant amount of disk space.

## Usage

After installing the tool, you can use it by following these instructions:

1. **Input Data**: Provide necessary input data such as environmental indicators, socio-economic indicators, and demographic data. All input data is located in the `input` folder.  
2. **Run Analysis**: Execute the analysis script to process the data and generate screening results. A script that runs all of the code in an appropriate order is located in `src/runAllLayers.m`.
3. **Validate Results**: This project has a method for validating new results against the previously confirmed results of Version 2.0. Validation runs can be set in `src/runAllLayers.m`.
4. **View Results**: Explore the generated maps and visualizations to understand the environmental justice landscape in Connecticut. You can visualize them with any GIS viewer.  

## License

This project is licensed under the license for AttributionNonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0). Parties understand and agree that for any further adaptations building upon the MATLAB code it desires to make, it is responsible for licensing the modified material under identical terms and citing the original CIRCA EJ 2.0 code as being modified.

## Contact

For questions or support regarding this project, please contact [circa@uconn.edu](mailto:circa@uconn.edu).

## References
Onat, Y., Buchanan, M., Barber, C., Massidda, C., Duskin, L., Pestana, E., Alpdogan, D., Peate, B., Torres. A., Pimenta, M., Wozniak-Brown, J., Morris, K., and Bittner, C. (2023). “Connecticut Environmental Justice Screening Tool Report version 2.0,” University of Connecticut, Connecticut Institute for Resilience and Climate Adaptation. https://doi.org/10.56576/RFGP9592

## Citation
Onat, Y., Justeson, P., Duskin, L. Massidda, C. (2024). Connecticut Environmental Justice Screening Tool: Code for CTEJScreen" (Version 2.1) MATLAB. GitHub. https://github.uconn.edu/CIRCA/CTEJScreen_v2.0.git Accessed May 20, 2024. 

## Folder Structure
### input
The `input` folder holds all input data used in the program, split into:
- `layers` - the folder holding input data for each indicator of each category
- `rawData` - the folder holding base shape data for the analyzed region.

Some of the input data is not made publicly available because CIRCA doesn't own the share privileges. To learn how to access the data, please read the report under the References.

### output
The folder where all output calculations get generated, split by categories. Each category has subfolders for each indicator.

### src
The folder holding all code. At the top level, there is the main file `runAllLayers.m`. This runs all indicator scripts. The `runType` variable can be set to run only the updated version of the script or the validation test, [as described in the validation section.](#validation-testing)

The folders are split into:
- `layers` - Folders for categories, with each category having a subfolder for its indicators. [The structure of indicators is explained in the indicators section.](#structure-indicators)
- `utils` - A folder with various functions, data, and unit tests.

<a id="structure-indicators"></a>
## Indicators
Each indicator is made up of 3 files. As an example, we'll look at `Asthma` under the `HealthSensitivity` category.

The main indicator file, `Asthma.m`, processes the data from the appropriate input files and generates the output files. This file can be run on its own, or run as a group from the `runAllLayers.m` file.

When running an indicator, there are 2 types of runs. One is called an `Updated` run, which runs with settings designed to be updated and reorganized from the previous version of the CTEJScreen project. The other type of run is called `Validation`, which runs exactly like the previous version of the CTEJScreen project and validates the newly obtained results against the previously obtained results. [Please read the Validation Testing section for more information on different types of runs.](#validation-testing)

In order to change between run types for running individual indicator scripts, it is best to run at least the first section of the `runAllLayers.m` script to set the run type.

`AsthmaRunDataUpdated.m` is the file that sets the `Updated` run data for `Asthma`. It sets the fields to be in an updated version.

`AsthmaRunDataValidation.m` is the file that sets the `Validation` run data for `Asthma`. It sets the fields to be identical to the previously obtained results so that the new results can be validated against the old results.


### Composite Indices
Composite Indices are structured the same as the other indicators. The difference is that other indicators are calculated based on various data sources, while Composite Indices are calculated by combining the results of other indicators together.

Each category has a composite index calculated by combining all `Rank` data of the indicators within its category (this mostly happens in the `/src/utils/mergeCompositeIndexData.m` function). Once those initial composite indices are calculated, `HealthSensitivity` and `Socioeconomic` composite indices are combined into the `SensitivePopulation` composite index, and `PollutionExposure` and `PollutionSources` are combined into the `PollutionBurden` composite index. These two indices are then combined into the final `EJScreen` composite index.

All indicators and composite indices can be run and rerun independently, but the composite indices require results in the corresponding `output` folder for each of its dependent indicators. The `/src/runAllLayers.m` file will run each indicator in an appropriate order to allow for each indicator to calculate in uninterrupted sequence.


## Utils Functions

The `utils` folder has various functions that do similar calculations across multiple indicators. Each function in the `utils` folder has documentation describing how to use the function. Some of these functions have unit tests, demonstrating their test cases.

<a id="validation-testing"></a>
## Validation Testing
This version of the Environmental Justice Screening Tool uses results obtained from previous versions to validate the output of the current version. To support this, the program has a system for running validation testing, which takes the new output from the run and compares each value and column name to those obtained from previous results. You can find the main code for the validation test in `src/utils/validationTest.m`.

### Setting the Run Type

At the top of `runAllLayers.m`, there is a variable named `runType` which gets set to one of three values:

1. `RUN_VALIDATION_AND_UPDATED`
2. `RUN_VALIDATION_ONLY`
3. `RUN_UPDATED_ONLY`

These are constant values that determine what type of run to perform. This value is saved in `runType.mat` and will be applied to all runs (both from `runAllLayers.m` and individual indicator files).

A **validation run** is a run that validates the run against the results of the previous version of the EJ Screening Tool. To do this, it matches field names and other relevant settings to the output of the previous version.

An **updated run** is a run that does not run the validation testing, and is therefore free to update any field names or other settings.

### Setting Data Per Run Type

Each indicator uses the function `loadRunData` to get the data specific to the current run. This is stored in the `runData` struct. The data is set by the user in the files specifying `runData` for each run (the current naming convention is `[indicator name]RunDataUpdated.m` and `[indicator name]RunDataValidation.m`).

## Additional Required Steps
Some indicators require additional steps in order to create the final output.

### Health Sensitivity
Multiple indicators in the `Health Sensitivity` category require additional analytical work after running the script to create the final output. The indicators requiring this work are:

1. `CoronaryHeartDisease`
2. `Depression`
3. `Diabetes`
4. `MentalHealth`

This data is expected to be in the indicator's output folder and have a naming convention of `[indicator name]_GEOID20.[file extension]`. These files are committed to the git repo instead of being ignored in the `.gitignore` file.

### Composite Indices - EJ Screen
The EJScreen code in `src/layers/CompositeIndex/EJScreen/EJScreen.m` will generate the final results, but will not include intermediate composite index results, such as those from `PollutionBurden` and `SensitivePopulations`. If you would like to view all of those results together, you can use ArcPro or any GIS viewer to join the relevant layer fields together.