Update project setup (#72)

WeilerP · web-flow · commit dacfd8f2248f · 2026-04-24T22:01:14.000-04:00
* Update `.pre-commit-config.yaml`
* Add `.lintr`
* Update `pyproject.toml`
* Add `.gitattributes`
* Add `.envrc`
* Update README
* Update index page for Jupyter book
* Update linting CI
* Update Jupyter book CI
diff --git a/.envrc b/.envrc
@@ -0,0 +1 @@
+export UV_PROJECT_ENVIRONMENT="$(pwd)/.fancypackage-pyXY"
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1,2 @@
+# SCM syntax highlighting & preventing 3-way merges
+pixi.lock merge=binary linguist-language=YAML linguist-generated=true -diff
diff --git a/.github/workflows/book.yml b/.github/workflows/book.yml
@@ -1,33 +1,33 @@
 name: deploy-jupyter-book
 
 on:
-    push:
-        branches:
-            - main
+  push:
+    branches:
+      - main
 
 # This job installs dependencies, build the book, and pushes it to `gh-pages`
 jobs:
-    deploy-book:
-        runs-on: ubuntu-latest
-        steps:
-            - uses: actions/checkout@v2
+  deploy-book:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
 
-            # Install dependencies
-            - name: Set up Python 3.10
-              uses: actions/setup-python@v4
-              with:
-                  python-version: "3.10"
+      # Install dependencies
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
 
-            - name: Install dependencies
-              run: |
-                  pip install jupyter-book
-            # Build the book
-            - name: Build the book
-              run: |
-                  jupyter-book build notebooks
-            # Push the book's HTML to github-pages
-            - name: GitHub Pages action
-              uses: peaceiris/actions-gh-pages@v4.0.0
-              with:
-                  github_token: ${{ secrets.GITHUB_TOKEN }}
-                  publish_dir: notebooks/_build/html
+      - name: Install dependencies
+        run: |
+          pip install jupyter-book
+
+      - name: Build the book
+        run: |
+          jupyter-book build notebooks
+
+      - name: GitHub Pages action
+        uses: peaceiris/actions-gh-pages@v4.0.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: notebooks/_build/html
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -1,23 +1,28 @@
 name: Lint
 
 on:
-    push:
-        branches: main
-    pull_request:
-        branches: main
+  push:
+    branches: main
+  pull_request:
+    branches: main
 
 jobs:
-    linting:
-        runs-on: ubuntu-latest
-        steps:
-            - uses: actions/checkout@v3
-            - name: Setup Python 3.10
-              uses: actions/setup-python@v4
-              with:
-                  python-version: "3.10"
-            - name: Install dependencies
-              run: |
-                  python -m pip install --upgrade pip
-                  pip install pre-commit
-            - name: Check pre-commit compatibility
-              run: pre-commit run --all-files --show-diff-on-failure
+  linting:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout repo
+      uses: actions/checkout@v6
+
+    - name: Setup Python 3.14
+      uses: actions/setup-python@v6
+      with:
+          python-version: "3.14"
+
+    - name: Setup R
+      uses: r-lib/actions/setup-r@v2
+      with:
+        r-version: "4.5.3"
+        use-public-rspm: true
+
+    - name: Run pre-commit hooks
+      uses: pre-commit/action@v3.0.1
diff --git a/.gitignore b/.gitignore
@@ -160,3 +160,7 @@ jobs/
 *.Rhistory
 
 .vscode/*
+
+# pixi environments
+.pixi/*
+!.pixi/config.toml
diff --git a/.lintr b/.lintr
@@ -0,0 +1,4 @@
+linters: linters_with_defaults(
+  line_length_linter = line_length_linter(length = 120L),
+  object_name_linter = NULL
+  )
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,62 +1,63 @@
 fail_fast: false
 default_language_version:
-    python: python3
+  python: python3
 default_stages:
-    - pre-commit
-    - pre-push
+  - pre-commit
+  - pre-push
 minimum_pre_commit_version: 2.16.0
 repos:
-    - repo: https://github.com/mwouts/jupytext
-      rev: v1.14.5
-      hooks:
-          - id: jupytext
-            args:
-                [--from, ipynb, --sync, --pipe, black, --pipe-fmt, "py:percent"]
-            additional_dependencies:
-                - black==23.1.0 # Matches hook
-    - repo: https://github.com/psf/black
-      rev: "23.1.0"
-      hooks:
-          - id: black-jupyter
-    - repo: https://github.com/asottile/blacken-docs
-      rev: 1.13.0
-      hooks:
-          - id: blacken-docs
-    - repo: https://github.com/PyCQA/isort
-      rev: 5.12.0
-      hooks:
-          - id: isort
-    - repo: https://github.com/pre-commit/mirrors-prettier
-      rev: v3.0.0-alpha.4
-      hooks:
-          - id: prettier
-            # Newer versions of node don't work on systems that have an older version of GLIBC
-            # (in particular Ubuntu 18.04 and Centos 7)
-            # EOL of Centos 7 is in 2024-06, we can probably get rid of this then.
-            # See https://github.com/scverse/cookiecutter-scverse/issues/143 and
-            # https://github.com/jupyterlab/jupyterlab/issues/12675
-            language_version: "17.9.1"
-    - repo: https://github.com/charliermarsh/ruff-pre-commit
-      rev: v0.0.253
-      hooks:
-          - id: ruff
-            args: [--fix, --exit-non-zero-on-fix]
-    - repo: https://github.com/pre-commit/pre-commit-hooks
-      rev: v4.4.0
-      hooks:
-          - id: detect-private-key
-          - id: check-ast
-          - id: end-of-file-fixer
-          - id: mixed-line-ending
-            args: [--fix=lf]
-          - id: trailing-whitespace
-          - id: check-case-conflict
-    - repo: local
-      hooks:
-          - id: forbid-to-commit
-            name: Don't commit rej files
-            entry: |
-                Cannot commit .rej files. These indicate merge conflicts that arise during automated template updates.
-                Fix the merge conflicts manually and remove the .rej files.
-            language: fail
-            files: '.*\.rej$'
+  - repo: https://github.com/biomejs/pre-commit
+    rev: v2.4.12
+    hooks:
+      - id: biome-format
+        exclude: ^\.cruft\.json$ # inconsistent indentation with cruft - file never to be modified manually.
+  - repo: https://github.com/tox-dev/pyproject-fmt
+    rev: v2.21.1
+    hooks:
+      - id: pyproject-fmt
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.11
+    hooks:
+      - id: ruff-check
+        types_or: [python, pyi, jupyter]
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+        types_or: [python, pyi, jupyter]
+  - repo: https://github.com/mwouts/jupytext
+    rev: v1.14.5
+    hooks:
+      - id: jupytext
+        args: [--from, ipynb, --sync, --pipe, "ruff format -", --pipe-fmt, "py:percent"]
+        additional_dependencies:
+            - ruff==0.15.11 # Matches hook
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: detect-private-key
+      - id: check-ast
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+        args: [--fix=lf]
+      - id: trailing-whitespace
+      - id: check-case-conflict
+      # Check that there are no merge conflicts (could be generated by template sync)
+      - id: check-merge-conflict
+        args: [--assume-in-merge]
+  - repo: https://github.com/lorenzwalthert/precommit
+    rev: v0.4.3.9021
+    hooks:
+      - id: style-files
+      - id: lintr
+      - id: parsable-R
+      - id: no-debug-statement
+      - id: no-print-statement
+      - id: no-browser-statement
+  - repo: local
+    hooks:
+      - id: forbid-to-commit
+        name: Don't commit rej files
+        entry: |
+          Cannot commit .rej files. These indicate merge conflicts that arise during automated template updates.
+          Fix the merge conflicts manually and remove the .rej files.
+        language: fail
+        files: '.*\.rej$'
diff --git a/README.md b/README.md
@@ -1,11 +1,31 @@
 # Single-cell analysis template repository
 
-This repository acts as a template notebook for the analysis of single-cell data and methods; the corresponding Jupyter
-Book is rendered [here](https://weilerp.github.io/sc_analysis_template/).
-You can check the [CellRank 2 reproducibility repository](https://github.com/theislab/cellrank2_reproducibility)
-for an example repository following the same outline as this template.
+This repository acts as a template notebook for the analysis of single-cell data and methods; the corresponding Jupyter Book is rendered [here](https://weilerp.github.io/sc_analysis_template/).
 
-## Set up
+You can check out the [CellRank 2](https://github.com/theislab/cellrank2_reproducibility) and [CellRank protocol](https://github.com/theislab/cellrank_protocol) reproducibility repositories for example repositories following the same outline as this template, built off an earlier version of this template repo.
+
+## Project structure
+
+- `data/`
+    - Directory containing data relevant to project
+    - Contains one subdirectory for each dataset
+    - Proposed structure: each dataset has its own subdirectory containing
+        - `raw/`: original, unaltered data that always exists unless the data has been loaded from an external data directory
+        - `processed/`: processed data from `raw/`
+        - `results`: analysis results
+- `figures/`
+    - Directory to collect generated figures
+    - Contains one subdirectory for each dataset
+- `jobs/`
+    - Directory to collect scripts for submitting HPC jobs, e.g., with sbatch, (in `jobs/scripts/`) and their generated output files (in `jobs/logs/`)
+- `notebooks/`
+    - Directory containing Jupyter notebooks
+    - Contains one subdirectory for each dataset
+- `scripts/`
+    - Directory containing Python or R scripts
+    - Contains one subdirectory for each dataset
+
+## Setup
 
 1. Rename `src/fancypackage/`.
 2. Update `pyproject.toml` to include the correct information
@@ -20,20 +40,64 @@ for an example repository following the same outline as this template.
 5. Ensure repository settings are set up correctly to build Jupyter Book:
     - In `Settings > Actions > General > Workflow permissions`: Allow read and write permissions.
     - In `Settings > Pages > Build and deployment`: Set the branch to `gh-pages`.
+6. If you use uv with a custom environment name: update the `UV_PROJECT_ENVIRONMENT` value in `.envrc`
 
 ## Installation
 
+### uv
+
+To install the accompanying packages with [uv](https://docs.astral.sh/uv/), you can run
+
+```bash
+uv venv
+uv sync --group jupyter
+uv run pre-commit install
+
+# Optional: Add jupyter kernel
+uv run ipython kernel install --user --env VIRTUAL_ENV .venv --name fancypackage --display-name "fancypackage"
+```
+
+If you want to specify a custom environment name and specific Python version, you may use [direnv](https://direnv.net/) and run
+
+```bash
+direnv allow
+uv venv fancypackage-pyXY -p X.Y
+uv sync --group jupyter
+uv run pre-commit install
+
+# Optional: Add jupyter kernel
+uv run ipython kernel install --user --env VIRTUAL_ENV $UV_PROJECT_ENVIRONMENT --name fancypackage-pyXY --display-name "fancypackage-pyX.Y"
+```
+
+### pixi
+
+To set up the project with [pixi](https://pixi.prefix.dev/latest/), run
+
+```bash
+pixi add --pypi --editable --no-install --frozen "fancypackage @ file://$(pwd)"
+pixi install
+pixi run setup-pre-commit
+
+# Optional: Add jupyter kernel
+pixi run ipython kernel install --user --env ~/.pixi/envs/default --name fancypackage --display-name "fancypackage"
+```
+
+and to use a specific Python version and environment name, run
+
 ```bash
-conda create -n fancyname-pyXX python=X.X --yes && conda activate fancyname-pyXX
-pip install -e ".[dev,jupyter]"
-pre-commit install
+pixi add  --frozen --feature pyXY python=X.Y
+pixi workspace environment add fancypackage-pyXY --feature pyXY --feature dev --feature jupyter
+pixi add --pypi --editable --no-install --frozen "fancypackage @ file://$(pwd)"
+pixi install -e fancypackage-pyXY
+pixi run setup-pre-commit
 
-python -m ipykernel install --user --name fancyname-pyXX --display-name "fancyname-pyXX"
+# Optional: Add jupyter kernel
+pixi run ipython kernel install --user --env VIRTUAL_ENV .pixi/envs/fancypackage-pyXY --name fancypackage-pyXY --display-name "fancypackage-pyX.Y"
 ```
 
 ## Things to keep in mind
 
-Whenever you use a new single-cell tool, add it to `known_bio` in `pyproject.toml` s.t. `isort` can work correctly.
+Whenever you use a new single-cell tool, add it to `bio` in `pyproject.toml` so `isort` can work correctly.
 
 ## Workflow
 
diff --git a/notebooks/index.md b/notebooks/index.md
diff --git a/pyproject.toml b/pyproject.toml

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+export UV_PROJECT_ENVIRONMENT="$(pwd)/.fancypackage-pyXY"`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+# SCM syntax highlighting & preventing 3-way merges`
	`2`	`+pixi.lock merge=binary linguist-language=YAML linguist-generated=true -diff`