Skip to main content

Repository for Covid-19 Dynamic Factor Model

Project description

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

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.

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 run DFMDash,

Prerequisites

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

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 jvivian/dfmdash

Or, build locally:

docker build -t dfmdash .
docker run dfmdash

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dfmdash-1.0.0.tar.gz (26.1 kB view details)

Uploaded Source

Built Distribution

dfmdash-1.0.0-py3-none-any.whl (30.5 kB view details)

Uploaded Python 3

File details

Details for the file dfmdash-1.0.0.tar.gz.

File metadata

  • Download URL: dfmdash-1.0.0.tar.gz
  • Upload date:
  • Size: 26.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.10.14

File hashes

Hashes for dfmdash-1.0.0.tar.gz
Algorithm Hash digest
SHA256 c904e5eb26a19f35c9ee37adc87819282e54d98703661ba7d5892d4ae46bf8af
MD5 6537dbc736e69f1358fdd5b9b2c83260
BLAKE2b-256 4a61b9aeae72251451d165fd26616b00e198ea51d067da4048ceaf4ee6c20bcc

See more details on using hashes here.

File details

Details for the file dfmdash-1.0.0-py3-none-any.whl.

File metadata

  • Download URL: dfmdash-1.0.0-py3-none-any.whl
  • Upload date:
  • Size: 30.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.10.14

File hashes

Hashes for dfmdash-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f69a076855053bc015071ee6171fc1bed2e16c7e2a32d51b2fe58bc2bb452abc
MD5 029f639be555de462b4b2c8f57a29c47
BLAKE2b-256 ea863fef21398c903e7e8fc284328769c03454ad5201d5f1e43564193c00a9db

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page