Merge pull request #103 from jvivian/jvivian/issue101

Automate MkDocs deployment to Pages, fix Docker launch bug

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

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"]

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"

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,36 +106,41 @@ 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
 ```
 
 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
 
 ```