Initial setup of repo

.editorconfig

@@ -0,0 +1,21 @@
+root = true
+
+[*]
+charset = utf-8
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+max_line_length = 88
+
+[*.md]
+indent_size = 2
+
+[*.yaml]
+indent_size = 2
+
+[*.yml]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+# Description
+
+_Please include a summary of the change and which issue is fixed (if any). Please also
+include relevant motivation and context. List any dependencies that are required for
+this change._
+
+Close # (issue)
+
+## Type of change
+
+- [ ] Documentation (non-breaking change that adds or improves the documentation)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Optimization (non-breaking, back-end change that speeds up the code)
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] Breaking change (whatever its nature)
+
+## Key checklist
+
+- [ ] All tests pass (eg. `python -m pytest`)
+- [ ] Pre-commit hooks run successfully (eg. `pre-commit run --all-files`)
+
+## Further checks
+
+- [ ] Code is commented, particularly in hard-to-understand areas
+- [ ] Tests added or an issue has been opened to tackle that in the future.
+  (Indicate issue here: # (issue))

.github/dependabot.yml

@@ -0,0 +1,15 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

.github/workflows/auto-merge.yml

@@ -0,0 +1,23 @@
+name: Dependabot and Pre-commit auto-merge
+
+on:
+  pull_request:
+
+permissions:
+  contents: write
+  pull-requests: write # Needed if in a private repository
+
+jobs:
+  auto-merge:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.pull_request.user.login == 'dependabot[bot]' || github.event.pull_request.user.login == 'pre-commit-ci[bot]' }}
+    steps:
+      - name: Enable auto-merge for bot PRs
+        run: |
+          gh pr review --approve "$PR_URL"
+          gh pr merge --auto --merge "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          # GitHub provides this variable in the CI env. You don't
+          # need to add anything to the secrets vault.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/check-links.yml

@@ -0,0 +1,17 @@
+name: Check links in Markdown files
+on:
+  schedule:
+    - cron: 0 0 * * 1   # midnight every Monday
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  check-links:
+    name: Lychee link checker
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - id: lychee
+        uses: lycheeverse/lychee-action@v2

.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: Test and build
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+  workflow_call:
+
+jobs:
+  test:
+    runs-on: ${{matrix.os}}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+          - macos-latest
+        python-version: ['3.14']
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          prune-cache: false
+          activate-environment: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run mypy
+        run: mypy .
+
+      - name: Run tests
+        run: pytest

.gitignore

@@ -182,9 +182,9 @@ cython_debug/
 .abstra/
 
 # Visual Studio Code
-#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
 #  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
 #  you could uncomment the following to ignore the entire vscode folder
 # .vscode/
 

.markdownlint.yaml

@@ -0,0 +1,4 @@
+# Disable checks here
+MD013: false
+MD007:
+  indent: 4

.pre-commit-config.yaml

@@ -0,0 +1,49 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-merge-conflict
+      - id: debug-statements
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: pretty-format-json
+        args: [--autofix, --indent, '4', --no-sort]
+        exclude: \.ipynb$
+  - repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks
+    rev: v2.14.0
+    hooks:
+      - id: pretty-format-yaml
+        args: [--autofix, --indent, '2', --offset, '2']
+  - repo: https://github.com/python-jsonschema/check-jsonschema
+    rev: 0.33.1
+    hooks:
+      - id: check-dependabot
+      - id: check-github-actions
+      - id: check-github-workflows
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.0
+    hooks:
+      - id: ruff-check
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+  - repo: https://github.com/kynan/nbstripout
+    rev: 0.8.1
+    hooks:
+      - id: nbstripout
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.16.1
+    hooks:
+      - id: mypy
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.45.0
+    hooks:
+      - id: markdownlint-fix
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+      - id: codespell
+        args: [-I, .codespell_ignore.txt]
+  - repo: https://github.com/ComPWA/taplo-pre-commit
+    rev: v0.9.3
+    hooks:
+      - id: taplo-format # Format TOML files

.taplo.toml

@@ -0,0 +1,4 @@
+[formatting]
+compact_inline_tables = true
+column_width = 88
+indent_string = "    "

.vscode/extensions.json

@@ -0,0 +1,10 @@
+{
+    "recommendations": [
+        "ms-python.python",
+        "ms-python.mypy-type-checker",
+        "ms-toolsai.jupyter",
+        "editorconfig.editorconfig",
+        "davidanson.vscode-markdownlint",
+        "charliermarsh.ruff"
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+    "[python]": {
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "charliermarsh.ruff"
+    },
+    "editor.rulers": [
+        88
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

README.md

@@ -1 +1,89 @@
 # MUSE2 data analysis
+
+> :warning: **Note that this repository is currently a work in progress.** :warning:
+
+This repository contains Python scripts and Jupyter notebooks for analysing and
+visualising [MUSE2] data files.
+
+We recommend using [uv] for installing dependencies and managing your virtual
+environment.
+
+## Usage
+
+To get started:
+
+1. [Download and install uv] following the instructions for your OS.
+
+1. Install the package and dependencies and set up the virtual environment:
+
+    ```bash
+    uv sync
+    ```
+
+1. Activate the virtual environment, or just preface your commands with `uv run` to use
+the virtual environment (see [uv docs] for more info).
+
+    To activate on Linux/macOS:
+
+    ```bash
+    source .venv/bin/activate
+    <command>
+    ```
+
+    To activate on Windows:
+
+    ```powershell
+    .venv\Scripts\activate
+    ```
+
+    Or run the command directly:
+
+    ```bash
+    uv run <command>
+    ```
+
+1. Make sure the Python code can find your MUSE2 installation. (If you have not yet
+installed MUSE2, [follow the instructions here][install-muse2].)
+
+    There are two ways you can do this:
+
+    1. Make sure the `muse2` executable is on your [`PATH`]:
+
+        - [Instructions for Windows][windows-path]
+        - [Instructions for Linux][linux-path]
+        - [Instructions for macOS][macos-path]
+
+        (If you installed MUSE2 with `cargo`, it should already be on your `PATH`.)
+
+    1. Set the `MUSE2_PATH` environment variable to the full path of the `muse2`
+       executable file.
+
+       You can either do this by [setting the environment variable from within
+       Jupyter][jupyter-envvar] or from your shell before you launch Jupyter notebook.
+
+There are some example notebooks in the [`notebooks`] folder to get you started. You can
+view these with Jupyter notebook, like so:
+
+```bash
+uv run jupyter notebook
+```
+
+If you are using Visual Studio Code, you can also view them directly in your IDE with
+[the Jupyter extension].
+
+[MUSE2]: https://github.com/EnergySystemsModellingLab/MUSE2
+[uv]: https://docs.astral.sh/uv
+[Download and install uv]: https://docs.astral.sh/uv/getting-started/installation/
+[uv docs]: https://docs.astral.sh/uv/pip/environments/#creating-a-virtual-environment
+[install-muse2]: https://energysystemsmodellinglab.github.io/MUSE2/#getting-started
+[`PATH`]: https://en.wikipedia.org/wiki/PATH_(variable)
+[windows-path]: https://stackoverflow.com/a/41895179
+[linux-path]: https://unix.stackexchange.com/questions/3809/how-can-i-make-a-program-executable-from-everywhere
+[macos-path]: https://apple.stackexchange.com/a/41586
+[jupyter-envvar]: https://stackoverflow.com/a/44251637
+[`notebooks`]: ./notebooks
+[the Jupyter extension]: https://code.visualstudio.com/docs/datascience/jupyter-notebooks
+
+## Copyright
+
+Copyright © 2026 Imperial College London

data/.gitignore

@@ -0,0 +1,3 @@
+*
+!README.txt
+!.gitignore

data/README.txt

@@ -0,0 +1 @@
+This is a placeholder directory for input/output data for example analyses.

muse2_data_analysis/__init__.py

@@ -0,0 +1,9 @@
+"""The main module for MUSE2 data analysis."""
+
+from contextlib import suppress
+from importlib.metadata import PackageNotFoundError, version
+
+from .muse2 import find_muse2, run_muse2  # noqa: F401
+
+with suppress(PackageNotFoundError):
+    __version__ = version(__name__)

muse2_data_analysis/helpers.py

@@ -0,0 +1,38 @@
+"""Helper functions for notebooks."""
+
+from pathlib import Path
+
+from . import run_muse2
+
+DATA_DIR = Path(__file__).parent.parent.absolute() / "data"
+EXAMPLE_NAME = "muse1_default"
+_INPUT_DIR = DATA_DIR / f"{EXAMPLE_NAME}_input"
+_OUTPUT_DIR = DATA_DIR / f"{EXAMPLE_NAME}_output"
+
+
+def get_example_input_dir() -> Path:
+    """Get the directory for example input data.
+
+    If the folder does not exist, we create it by extracting an example from muse2.
+    """
+    if _INPUT_DIR.exists():
+        return _INPUT_DIR
+
+    run_muse2("example", "extract", EXAMPLE_NAME, str(_INPUT_DIR))
+    return _INPUT_DIR
+
+
+def get_example_output_dir() -> Path:
+    """Get the directory for example output data.
+
+    If the folder does not exist, we create it by running an example model with muse2.
+    """
+    if _OUTPUT_DIR.exists():
+        return _OUTPUT_DIR
+
+    # Ensure INPUT_DIR exists
+    get_example_input_dir()
+
+    # Run the example model
+    run_muse2("run", str(_INPUT_DIR), "--output-dir", str(_OUTPUT_DIR))
+    return _OUTPUT_DIR