Code for Chicago Mapping Project Backend

This project is a set of Python scripts that generate data for an interactive map of food insecurity, food assistance program participation and demographics in Illinois. Running this project outputs JSON files that can be used by the frontend.

Getting Started

Prerequisites

1. The latest version of Python 3.9
2. The latest version of Git
3. A Census API Key, which can be obtained by filling out this form

Running for the first time

1. Ensure Python and Git are installed.
2. Create a local directory, and open a command prompt there.
3. Clone the repository with Git:

git clone https://github.com/Code-For-Chicago/greater-chicago-food-despository.git . 

4. Create a file called .env in the root directory. This file is ignored via the .gitignore file to avoid committing secrets.
5. Open .env in a text editor and add this as the contents, replacing the second part with your personal Census API key:

CENSUS_KEY=REPLACE_ME_WITH_CENSUS_API_KEY

6. Install required modules in requirements.txt
   • Mac/Linux: pip3 install -r requirements.txt
   • Windows: pip install -r requirements.txt
7. Run start script to verify your setup is correct
   • Mac/Linux:
     • Make script executable chmod 755 start.sh
     • Run start.sh via terminal or double click
   • Windows: run start.bat via command line or double click
8. If the tests do not pass, check your .env file and your installed python package versions

Running the Project

If the start script succeeds, you can run the project with:

• Mac/Linux: python3 src/main.py
• Windows: python src\main.py

Running the project generates output files in the final_jsons folder.

To run with memory profiling:

• Mac/Linux:
  1. Make sure the script is executable: chmod 755 memory_profiling/run_main.sh
  2. Run the script: ./memory_profiling/run_main.sh
  3. View the report: memory_profiling/memory_profile_report.txt
• Windows CMD/Powershell:
  1. Run the script: .\memory_profiling\run_main.bat
  2. View the report: memory_profiling\memory_profile_report.txt

Exploring the Data

After code runs, you can view the data in a Jupyter notebook at getting_started/example.ipynb

• To open the notebook with VSCode, install the Python and Jupyter extensions
• To open the notebook with JupyterLab, see here

Running the Tests

1. To run the unit tests, run pytest from the root directory.
2. Run flake8 from the root directory to check that code style rules have been followed.
3. Run mypy src --ignore-missing-imports and mypy tests --ignore-missing-imports from the root directory to check for type errors.
4. Also see the GitHub Actions for the full list of tests that run in continuous integration.

See Also

GitHub Guides for tutorials on GitHub development and workflows

Data Pipeline

For documentation of the various input data and output data, see data_pipeline.md.