diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml new file mode 100644 index 0000000..45327e1 --- /dev/null +++ b/.github/workflows/deploy-docs.yaml @@ -0,0 +1,28 @@ +name: Deploy MkDocs to GitHub Pages + +on: + push: + branches: + - main # Trigger on changes to main (or your default branch) + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Set up Python + uses: actions/setup-python@v2 + with: + python-version: '3.x' + + - name: Install dependencies + run: | + pip install mkdocs mkdocs-material + + - name: Deploy to GitHub Pages + run: mkdocs gh-deploy --force + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/Dockerfile b/Dockerfile index 0318d9d..593c923 100644 --- a/Dockerfile +++ b/Dockerfile @@ -20,5 +20,4 @@ COPY . /code/ # Project initialization: RUN poetry install --no-interaction -ENTRYPOINT ["poetry", "run", "c19dfm"] -CMD ["--help"] +CMD ["poetry", "run", "dfmdash", "launch"] diff --git a/Makefile b/Makefile index 52dadcb..ce7d803 100644 --- a/Makefile +++ b/Makefile @@ -16,6 +16,16 @@ check: ## Run code quality tools. # @echo "🚀 Checking for obsolete dependencies: Running deptry" # @poetry run deptry . +.PHONY: docker-build +docker-build: ## Build the docker image + @echo "🚀 Building the docker image" + @docker build -t jvivian/dfmdash:latest . + +.PHONY: docker-push +docker-push: ## Push the docker image to the registry + @echo "🚀 Pushing the docker image" + @docker push jvivian/dfmdash:latest + .PHONY: test test: ## Test the code with pytest @echo "🚀 Testing code: Running pytest" diff --git a/README.md b/README.md index 59e5d75..87f8d07 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # DFMDash + > Easily drag-and-drop to build, run, and explore Dynamic Factor models in a browser-based GUI [![Release](https://img.shields.io/github/v/release/jvivian/DFMDash)](https://img.shields.io/github/v/release/jvivian/DFMDash) @@ -25,8 +26,8 @@ See our [Documentation](https://jvivian.github.io/DFMDash/) 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. - ## 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. @@ -37,6 +38,7 @@ There are multiple ways to install and run `DFMDash`. - 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: @@ -49,12 +51,14 @@ There are multiple ways to install and run `DFMDash`. 0. [Install Poetry](https://python-poetry.org/) 1. Clone the repository and move into the directory: + ```bash git clone https://github.com/jvivian/DFMDash/ cd DFMDash ``` 2. Install dependencies: + ```bash poetry install ``` @@ -69,23 +73,27 @@ There are multiple ways to install and run `DFMDash`. ``` ### Option 2: Using Anaconda / Mamba + > Convenient if Anaconda/Miniconda/Mamba already installed 0. [Install Anaconda](https://docs.anaconda.com/anaconda/install/) 1. Clone the repository: + ```bash git clone https://github.com/jvivian/DFMDash/ cd DFMDash ``` 2. Create and activate the environment: + ```bash conda env update -f environment.yml conda activate py3.10 ``` 3. Install dependencies: + ```bash poetry install ``` @@ -98,19 +106,24 @@ There are multiple ways to install and run `DFMDash`. ### Option 3: Using Docker (recommended if you have permissions) Run the pre-built image: + ```bash -docker run jvivian/dfmdash +docker run -p 8501:8501 jvivian/dfmdash ``` Or, build locally: + ```bash docker build -t dfmdash . -docker run dfmdash +docker run -p 8501:8501 jvivian/dfmdash ``` +Then, open your browser to `localhost:8501`. + ## Usage After installation, launch the tool by typing: + ```bash dfmdash launch ``` @@ -118,16 +131,16 @@ 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](imgs/DFM.png) + ![Dynamic Factor Model Runner](imgs/DFM.png) - **Factor Analysis Page**: Review and visualize latent factor estimates based on the selected inputs. -![Analyze factors directly after generation](imgs/factor.png) + ![Analyze factors directly after generation](imgs/factor.png) - **Comparative Run Analysis**: Compare different model runs to evaluate fit and consistency. -![Quantitatively compare models using different metrics](imgs/CA.png) + ![Quantitatively compare models using different metrics](imgs/CA.png) - **Synthetic Control Model Page** (Experimental): Test SCMs with user-defined counterfactuals. -> Work in progress + > Work in progress ## Troubleshooting @@ -139,6 +152,7 @@ This will open the Streamlit dashboard in your default browser. From the dashboa To contribute to `DFMDash`, follow these steps: 1. Clone the repository: + ```bash git clone https://github.com/jvivian/DFMDash/ cd DFMDash @@ -150,10 +164,12 @@ To contribute to `DFMDash`, follow these steps: ``` This will: + - Install the virtual environment at `.venv/bin/python`. - Set up pre-commit hooks for linting and formatting checks. 3. To run tests: + ```bash pytest ``` @@ -171,6 +187,7 @@ This will: ## Documentation Documentation is built using **MkDocs**. To generate the documentation locally, run: + ```bash mkdocs serve ``` @@ -180,6 +197,7 @@ 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. @@ -189,8 +207,8 @@ For larger changes, please open an issue for discussion before submitting a PR. `DFMDash` is distributed under the MIT License. See [LICENSE](./LICENSE) for details. - # Citation + > If you use this tool in your research, please cite the following paper ```