Contributing: Application Development

Table of Contents

Developer Requirements

The application is built with Streamlit, Streamlit requires:

  • Python 3.6.x or later
  • PIP

See Streamlit's Getting Started guide for detailed information on prerequisites and setup

Running CHIME Locally

With venv

python3 -m venv ~.venv
. ~.venv/bin/activate
pip install -e .

With pipenv

pipenv shell
pipenv sync --dev

With conda

conda env create -f environment.yml
source activate chime
pip install streamlit

Run the Streamlit Web App

ASSETS=./defaults/assets \
PARAMETERS=-./defaults/webapp.cfg streamlit run st_app.py

Run the Command Line Interface

ASSETS=./defaults/assets \
PARAMETERS=./defaults/cli.cfg penn_chime

Help with the Command Line Interface

penn_chime --help

Choosing a Different Set of Parameters

If you want a different set of default parameters, you may use your own configuration file.

ASSETS=./defaults/assets \
PARAMETERS=./defaults/yours.cfg streamlit run st_app.py

Be sure to include --current-date in the file, if your --current-hospitalized is not today's value. Be sure to include --mitigation-date in the file if social distancing was implemented before today.

Choosing a Different Port

If you need to run the application on a different port than the default (8000), you can set an environment variable.

ASSETS=./defaults/assets \
STREAMLIT_SERVER_PORT=1234 \
PARAMETERS=./defaults/webapp.cfg streamlit run st_app.py

Choosing a Different Language

If you want to run the application in another language, do the following. You can select Japanese as the language other than English.

ASSETS=./defaults/assets \
LANG=ja \
PARAMETERS=./defaults/webapp.cfg streamlit run st_app.py

Project Layout

Application files

  • st_app.py: Startup script for the streamlit web application.
  • src: Source code for the penn_chime module.
  • tests/: pytest tests for the penn_chime module.
  • script/: Developer workflow scripts following GitHub's Scripts To Rule Them All pattern.
  • .streamlit/: Streamlit config options
  • .env: Local environment variables to use when running application, this file is copied from .env.example to start you out and then ignored by git
  • environment.yml
  • Pipfile
  • Pipfile.lock
  • setup.py
  • setup.cfg: Configuration for flake8, mypy, pytest

Documentation

Operations support

  • .github/workflows/: GitHub Actions workflows implementing automations driven by GitHub events
  • .holo/: Hologit projection configuration, used to generate gh-pages branch from content changes in docs/ tree
  • k8s/: Kubernetes manifests for the chime-live cluster
  • .env.example: A starter .env file distributed with the project
  • docker-compose.yml: Runtime container configuration for running the application locally via Docker
  • Dockerfile: Recipe for building Docker container that runs the application
  • Procfile: Supports running the application on Heroku

Testing

The project is set up for testing with pytest, and the GitHub repository is configured to execute pytest against all pull requests automatically.

To run tests locally, enter an environment first with pipenv or conda as indicated above in Running CHIME Locally, and then run:

pip install pytest
pytest

The test code runs from the local tests directory. Updating code in tests modifies the tests. Use pip install -e . so that your local changes to src are also the module under test. For CI, use pip install . to test the module installed in site-packages to ensure that the installed module is packaged correctly with all of its dependencies. Do not import from src in your tests or your python code as this will appear to work locally, but break the python module.

Validating CHIME

No validation routine is available yet. If you have thoughts on how to add one, please contribute!

results matching ""

    No results matching ""