Easily drag-and-drop to build, run, and explore Dynamic Factor models in a browser-based GUI
DFMDash
is an open-source tool for running Dynamic Factor Models (DFMs), primarily focused on pandemic intensity estimation through a combination of macroeconomic and epidemiological time-series data. DFMDash
simplifies the process of building dynamic factor models using a user-friendly Streamlit
-based dashboard, allowing researchers and policy makers to evaluate and compare pandemic dynamics across time and geography.
Designed initially for evaluating the impacts of COVID-19, DFMDash
is flexible enough to be adapted to other pandemics or scenarios requiring dynamic factor models. The tool provides capabilities for:
- Running DFMs with custom datasets or using pre-loaded COVID-19 economic data.
- Visualizing factor analysis results.
- Performing comparative run analysis.
- Implementing synthetic control models for policy impact evaluation.
See our Documentation page for API details.
- Dynamic Factor Models: Build models that combine pandemic and economic series to estimate latent variables representing pandemic intensity.
- Drag-and-Drop: Drop in files - options are then dynamically generated from the input data.
There are multiple ways to install and run DFMDash
.
Note: Due to PyPI constraints, the example data files are stored on the GitHub repository rather than in the pip-installed package. If you wish to use
DFMDash
with the provided example data, please clone the repository and follow the installation steps below.
- Python 3.10+ is required.
- Tested environments: Ubuntu, WSL2 (Windows), MacOS (M1 compatible).
Advanced: If you have a Python environment set up, prefer to install via
pip
and do not want/need the example data.
- Install the package:
pip install dfmdash
-
Clone the repository and move into the directory:
git clone https://github.com/jvivian/DFMDash/ cd DFMDash
-
Install dependencies:
poetry install
-
Launch the DFMDash dashboard:
dfmdash launch
or
poetry run dfmdash launch
Convenient if Anaconda/Miniconda/Mamba already installed
-
Clone the repository:
git clone https://github.com/jvivian/DFMDash/ cd DFMDash
-
Create and activate the environment:
conda env update -f environment.yml conda activate py3.10
-
Install dependencies:
poetry install
-
Launch DFMDash:
dfmdash launch
Run the pre-built image:
docker run -p 8501:8501 jvivian/dfmdash
Or, build locally:
docker build -t dfmdash .
docker run -p 8501:8501 dfmdash
Then, open your browser to localhost:8501
.
After installation, launch the tool by typing:
dfmdash launch
This will open the Streamlit dashboard in your default browser. From the dashboard, users can:
-
Main Page: Select data series and define the dynamic factor model specifications.
-
Factor Analysis Page: Review and visualize latent factor estimates based on the selected inputs.
-
Comparative Run Analysis: Compare different model runs to evaluate fit and consistency.
-
Synthetic Control Model Page (Experimental): Test SCMs with user-defined counterfactuals.
Work in progress
- If the dashboard does not automatically open, check the console where you typed the command. It should tell you what address the dashboard is being hosted at locally.
- If you encounter any bugs or issues while using the tool, feel free to open an issue. Please try and provide as much detail (and the data if possible) to recreate the issue.
To contribute to DFMDash
, follow these steps:
-
Clone the repository:
git clone https://github.com/jvivian/DFMDash/ cd DFMDash
-
Set up the development environment:
make install
This will:
- Install the virtual environment at
.venv/bin/python
. - Set up pre-commit hooks for linting and formatting checks.
-
To run tests:
pytest
-
Pre-commit hooks will automatically check for linting and formatting issues on each commit.
- CI pipeline is set up using GitHub Actions.
- On pull requests, merges to
main
, or releases, the pipeline will:- Run unit tests.
- Check code quality with black and ruff.
- Report code coverage via codecov.
Documentation is built using MkDocs. To generate the documentation locally, run:
mkdocs serve
We welcome contributions to DFMDash
! Please ensure that:
- All new code includes tests (if code coverage decreases, it will likely be rejected)
- Any modifications to the dashboard interface are reflected in the documentation.
For larger changes, please open an issue for discussion before submitting a PR.
DFMDash
is distributed under the MIT License. See LICENSE for details.
If you use this tool in your research, please cite the following paper
Cooke, A., & Vivian, J. (2024). Pandemic Intensity Estimation using Dynamic Factor Modelling. Statistics, Politics and Policy. Manuscript under review.