Initial commit

Co-authored-by: DLukacevic-IDM <[email protected]>
Co-authored-by: MeWu-IDM <[email protected]>
Co-authored-by: aouedraogo <[email protected]>

.devcontainer/devcontainer.json

@@ -0,0 +1,10 @@
+{
+    "name": "Python 3.12 Development Container For DEEP",
+    "image": "python:3.12",
+    "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance"
+    ],
+    "postCreateCommand": "pip install -e . && deepfacility ux",
+    "forwardPorts": [8000]
+}

.github/workflows/unittests.yml

@@ -0,0 +1,29 @@
+name: tests
+
+on:
+  pull_request:
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  run-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      max-parallel: 1
+      matrix:
+        python-version: [ '3.12' ]
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install packages
+        run: |
+          pip install --upgrade pip  
+          pip install --upgrade build    
+          pip install -e .[test]
+          pip install -e .[i18n]
+          pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
+      - name: Run unit-tests
+        run: pytest -v -m "not network_dependent"

.gitignore

@@ -0,0 +1,39 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+
+# Sphinx documentation
+docs/_build/
+
+# pyenv
+.python-version
+
+# Environments
+.env/
+.venv/
+
+*.egg-info
+
+app-data/
+.idea/
+*venv*/
+build/
+from-research
+config.toml
+*.zip

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Bill & Melinda Gates Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,92 @@
+# Digitally Enabled Equitably Placed (DEEP) Facility  
+Tools for optimizing placement of health workers and services based on village locations.  
+
+## Prerequisites
+- [Python](https://www.python.org/downloads) 3.12 or higher.
+- [Python virtual environment](https://realpython.com/python-virtual-environments-a-primer/)
+
+## Setup
+This section describes how to set up the tool and the demo web app.
+
+1. Activate your Python virtual environment and upgrade pip and build tools.
+```bash
+# Update pip and build package.
+pip install --upgrade pip  
+pip install --upgrade build
+pip install --upgrade setuptools
+```
+
+2. [Clone this repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) or [download](https://github.com/InstituteforDiseaseModeling/deepfacility/archive/refs/heads/main.zip) and extract the source code. Then open a terminal and navigate to the root directory of the source code.
+```bash
+# Navigate to the root directory.
+cd deepfacility
+``` 
+
+3. Install the tool:  
+```bash
+# Install the tool and required packages. 
+pip install -e .
+```
+
+## Getting Started
+
+Start the demo web app:
+```bash
+# Start the demo web app using `ux` command.
+deepfacility ux
+````
+
+After you see the message `Serving on ...` the **demo** web app is running.   
+
+Follow these steps to experience the workflow end-to-end:
+- Open your web browser and navigate to [http://localhost:8000](http://localhost:8000) to access the **demo** web app.
+- Follow instructions to "upload" and configure village locations .csv file.
+  - _Note that this app is running on your local machine and all files are stored locally._ 
+- Click `Prepare Data` to download and prepare input data: households and commune shapes. 
+- Select locations (communes) and click `Run Clustering` to start the processing.
+- Visualize and explore village shapes and health facilities recommendations on a map.
+- Obtain the results file.
+
+_Notes_: 
+- _This web app is only for **demo** purposes and is **not** intended for production use._
+- _To start a fresh copy of the app, without cached data, run `deepfacility reset` command before starting the app._
+
+# Terminology
+In this repository, we use the following terms and abbreviations:
+
+- `Cluster` and `Village` refer to the same entity with small differences in context:
+  - Cluster: a group of households. 
+  - Village: spatial interpretation of a cluster.
+- `Location`: an administrative area where the clustering is performed.
+  - In this tool a location value is a colon-separated list of names of administrative levels, per [configuration](docs/design.md#locations).
+  - For example, in Burkina Faso:
+    - `Tapoa:Diapaga` represents the `Diapaga` commune from the `Tapoa` province.
+    - `Tapoa:Diapaga:Mangou` represents a village from the `Diapaga` commune. 
+
+- Abbreviations:
+  - Health Facilities (HF)
+  - Empirical Cumulative Distribution Function (eCDF)
+
+# Multi-Language Support
+By default, the demo web app supports French and English languages. To add a support for additional languages see [Add New Language](docs/design.md#adding-new-languages) section in the design document.
+
+## Documentation
+- [Components](docs/components.md)  
+- [Design](docs/design.md)  
+- [Scientific Workflow](docs/workflow.md)
+- [CLI commands](docs/commands.md)
+
+## Data Sources
+The system is using the following external data sources: 
+- <a href="https://sites.research.google/open-buildings">Open Buildings</a> (Google)   
+  <cite>W. Sirko, S. Kashubin, M. Ritter, A. Annkah, Y.S.E. Bouchareb, Y. Dauphin, D. Keysers, M. Neumann, M. Cisse, J.A. Quinn. Continental-scale building detection from high resolution satellite imagery. <a href="https://arxiv.org/abs/2107.12283">arXiv:2107.12283</a>, 2021.</cite>
+
+- [GADM shapes](https://gadm.org/data.html) for countries administrative areas 
+
+## Package Dependencies
+Packages listed in
+[pyproject.toml](pyproject.toml)
+
+## Disclaimer
+The code in this repository was developed by IDM to support our research into healthcare system capacity. We’ve made it publicly available under the MIT License to provide others with a better understanding of our research and an opportunity to build upon it for their own work. We make no representations that the code works as intended or that we will provide support, address issues that are found, or accept pull requests. You are welcome to create your own fork and modify the code to suit your own modeling needs as contemplated under the MIT License.
+

docs/commands.md

@@ -0,0 +1,79 @@
+# Command Line Tool Commands
+
+## Setup
+Follow the [setup instruction](../README.md#setup) from the README.
+
+## Configuration
+Confirm the tool has been installed and observe the help content:  
+```bash  
+# Check the tool has been installed and see the usage help.
+deepfacility
+
+> usage: deepfacility run [-h] [-l LOCATION_FILTER [LOCATION_FILTER ...]] [-c CONFIG_FILE] [-n RUN_NAME] [-r RESULT_DIR] [--sid SESSION_ID]
+                        {countries,config,prep,locations,run,viewmap,ux,reset}  
+```  
+
+See the list of supported countries:  
+```bash 
+deepfacility countries
+
+> INFO: Supported countries (you can set in config):
+> ...list of countries...
+```
+
+Create a config file:   
+```bash
+# Generate a config file at the default path: app-data/config.toml
+deepfacility config 
+```
+
+Update the config file to set paths and column names for your files:
+- `[args.village_centers]` section for the village centers file. 
+- `[args.baseline_facilities]` section for the baseline facilities file (this is optional).
+
+## Data Preparation
+
+Prepare scientific workflow input files:
+```bash  
+# Prepare input files
+deepfacility prep  
+```  
+The above command will:
+- download and preprocess Google buildings and GADM shapes
+- standardize your village centers and baseline facilities files
+
+## Scientific Workflow
+
+See the list of all available locations execute the `locations` command:
+```bash
+# Read all locations available in the input data.
+deepfacility locations
+```
+_Note: The filter can be a specific location or a location [regex](https://docs.python.org/3/howto/regex.html#regex-howto) pattern._
+
+Process specified subset of locations.   
+```bash  
+# Run the processing for a subset of locations.
+deepfacility run -l "Noumbiel:.*"  # All locations in the Noumbiel province
+```
+
+To process all locations execute the `run` command without a location filter (this may take 1-2h). 
+
+## Visualizing Results
+Generate the interactive visualization map by specifying the result directory:
+```bash
+# Create viz map for results generated with -l `Noumbiel:.*`
+deepfacility viewmap -r Noumbiel-_1_5a819a9 
+````
+_Note: Look at the `app-data/data/BFA/results` directory for the list of available results directories._ 
+
+## Testing
+Install the test dependencies:  
+```bash
+# Install test dependencies.
+pip install -e .[test]
+```
+Run available tests:   
+```bash  
+pytest -v  
+```