Skip to content

Latest commit

 

History

History
216 lines (141 loc) · 6.62 KB

README.md

File metadata and controls

216 lines (141 loc) · 6.62 KB
Raw

DFMDash

Easily drag-and-drop to build, run, and explore Dynamic Factor models in a browser-based GUI

Release Build status codecov Commit activity License: MIT

Overview

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.

Key Features

  • 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.

Installation

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.

Prerequisites

  • Python 3.10+ is required.
  • Tested environments: Ubuntu, WSL2 (Windows), MacOS (M1 compatible).

Option 0: Using Pip

Advanced: If you have a Python environment set up, prefer to install via pip and do not want/need the example data.

  1. Install the package: 
    pip install dfmdash

Option 1: Using Poetry

  1. Install Poetry

  2. Clone the repository and move into the directory:

    git clone https://github.com/jvivian/DFMDash/
cd DFMDash

  3. Install dependencies:

    poetry install

  4. Launch the DFMDash dashboard:

    dfmdash launch

    or

    poetry run dfmdash launch

Option 2: Using Anaconda / Mamba

Convenient if Anaconda/Miniconda/Mamba already installed

  1. Install Anaconda

  2. Clone the repository:

    git clone https://github.com/jvivian/DFMDash/
cd DFMDash

  3. Create and activate the environment:

    conda env update -f environment.yml
conda activate py3.10

  4. Install dependencies:

    poetry install

  5. Launch DFMDash:

    dfmdash launch

Option 3: Using Docker (recommended if you have permissions)

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.

Usage

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. Dynamic Factor Model Runner

  • Factor Analysis Page: Review and visualize latent factor estimates based on the selected inputs. Analyze factors directly after generation

  • Comparative Run Analysis: Compare different model runs to evaluate fit and consistency. Quantitatively compare models using different metrics

  • Synthetic Control Model Page (Experimental): Test SCMs with user-defined counterfactuals.

    Work in progress

Troubleshooting

  • 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.

Development

To contribute to DFMDash, follow these steps:

  1. Clone the repository:

    git clone https://github.com/jvivian/DFMDash/
cd DFMDash

  2. 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.

  1. To run tests:

    pytest

  2. Pre-commit hooks will automatically check for linting and formatting issues on each commit.

CI/CD Pipeline

  • 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

Documentation is built using MkDocs. To generate the documentation locally, run:

mkdocs serve

Contributions

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.

License

DFMDash is distributed under the MIT License. See LICENSE for details.

Citation

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.