panhumanpy 0.5.0__tar.gz

panhumanpy-0.5.0/.devcontainer/Dockerfile

@@ -0,0 +1,13 @@
+FROM mcr.microsoft.com/devcontainers/base:jammy
+
+ARG PIXI_VERSION=v0.41.4
+
+RUN curl -L -o /usr/local/bin/pixi -fsSL --compressed "https://github.com/prefix-dev/pixi/releases/download/${PIXI_VERSION}/pixi-$(uname -m)-unknown-linux-musl" \
+    && chmod +x /usr/local/bin/pixi \
+    && pixi info
+
+# set some user and workdir settings to work nicely with vscode
+USER vscode
+WORKDIR /home/vscode
+
+RUN echo 'eval "$(pixi completion -s bash)"' >> /home/vscode/.bashrc

panhumanpy-0.5.0/.devcontainer/devcontainer.json

@@ -0,0 +1,18 @@
+{
+    "name": "panhumanpy",
+    "build": {
+      "dockerfile": "Dockerfile",
+      "context": ".."
+    },
+    "customizations": {
+      "vscode": {
+        "settings": {},
+        "extensions": ["ms-python.python", "charliermarsh.ruff", "GitHub.copilot"]
+      }
+    },
+    "features": {
+      "ghcr.io/devcontainers/features/docker-in-docker:2": {}
+    },
+    "mounts": ["source=${localWorkspaceFolderBasename}-pixi,target=${containerWorkspaceFolder}/.pixi,type=volume"],
+    "postCreateCommand": "sudo chown vscode .pixi && pixi install && pixi exec pre-commit install"
+}

panhumanpy-0.5.0/.flake8

@@ -0,0 +1,16 @@
+[flake8]
+# Black and Flake8 don't always agree, see:
+
+# Black recommends that rule "E501" be tweaked to conform with it's 80 
+# character maximum line length but we'll allow up to 132 character instead. We 
+# arrive at 132 by applying Black's 10% rule to the typical maximum line length
+# for comments of 120. Since we're running `black` as a pre-commit hook, we 
+# should only ever expect `flake8` to complain about long comment lines.
+max-line-length = 132
+
+# Black also recommends that `flake8` rules "E203" and "E501" are ignored,
+# for more details, see: 
+# https://black.readthedocs.io/en/stable/guides/using_black_with_other_tools.html#minimal-configuration.
+# We will also ignore rule W503 since it's soon to be reversed, for more details, 
+# see: https://www.flake8rules.com/rules/W503.html.
+extend-ignore = E203, E701, W503

panhumanpy-0.5.0/.gitattributes

@@ -0,0 +1,2 @@
+# SCM syntax highlighting
+pixi.lock linguist-language=YAML linguist-generated=true

panhumanpy-0.5.0/.github/pull_request_template.md

@@ -0,0 +1,51 @@
+## Description
+Checklist of guidelines to go through when making a PR.
+
+## Type of Change
+- [ ] Bug fix (patch version)
+- [ ] New or updated feature (minor version)  
+- [ ] New default model (major version + new constellation for version name)
+- [ ] Documentation update
+- [ ] Internal refactoring
+
+**Does this PR introduce a breaking change to the *public API* of existing features/models?**
+- [ ] Yes (If yes, this *will* require a Major version bump. Explain in "Additional Notes")
+- [ ] No
+
+## Pre-Merge Checklist
+**Please check each item before requesting review:**
+
+### Code Quality
+- [ ] Tests pass locally: `python -m pytest tests/`
+- [ ] New functionality has tests written
+- [ ] No debugging code left behind (print statements, breakpoints)
+- [ ] Package installs cleanly: `pip install -e .`
+
+### Documentation
+- [ ] README.md updated for user-facing changes and model version updates if necessary
+- [ ] Docstrings added for new functions
+- [ ] Tutorial notebook updated if needed
+
+### Model Changes (if applicable)
+- [ ] New models tested with sample data
+- [ ] Model files added to appropriate `_tools/` subdirectory
+- [ ] Backward compatibility maintained (old models still work)
+
+### Git Hygiene
+- [ ] Branch is up to date with main
+- [ ] No `__pycache__` files committed
+- [ ] Commit messages are descriptive
+- [ ] No merge conflicts
+
+## Version Impact (Maintainer Decision)
+- [ ] No version change needed
+- [ ] Should trigger version bump:
+  - [ ] Patch (bug fix)
+  - [ ] Minor (new or updated feature)  
+  - [ ] Major (breaking change to existing API, **or a new default model** which is a "soft" breaking change) - change constellation for version name
+
+## Testing
+How was this change tested?
+
+## Additional Notes
+

panhumanpy-0.5.0/.gitignore

@@ -0,0 +1,103 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# Environment
+.env
+.venv
+env/
+venv/
+ENV/
+
+# Pixi environments
+.pixi/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Translations
+*.mo
+*.pot
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyright
+.pyrightcache/
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# macOS system files
+.DS_Store

panhumanpy-0.5.0/.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+repos:
+  # Some basic pre-commit checks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+
+  # Run `isort` to sort imports.
+  - repo: https://github.com/PyCQA/isort
+    rev: 5.12.0
+    hooks:
+      - id: isort
+
+  # Run `black` to format code.
+  - repo: https://github.com/psf/black
+    rev: 23.9.1
+    hooks:
+      - id: black
+
+  # Run `flake8` for linting
+  - repo: https://github.com/pycqa/flake8
+    rev: 6.1.0
+    hooks:
+      - id: flake8

panhumanpy-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,118 @@
+## Developer's Guide
+
+### VSCode
+
+This project uses the [Dev Containers extension](https://code.visualstudio.com/docs/devcontainers/containers) for [VSCode](https://code.visualstudio.com/docs) to create reproducible development environments, please ensure that you have the IDE and extension installed. When you open the project in VSCode, the `.devcontainer` folder should be automatically detected and you will prompted you to build the container and
+re-open the project inside it. If not, open the Command Palette (`Ctrl+Shift+P` on Windows/Linux or `Cmd+Shift+P` on macOS) and select `Remote-Containers: Reopen in Container`.
+
+### pixi
+
+This project uses [pixi](https://pixi.sh/v0.41.4/) for dependency management and workflow automation. `pixi` uses the contents of the `pyproject.toml` file to generate a cross-platform `pixi.lock` file, providing deterministic, reproducible installations, while seamlessly resolving dependencies from multiple sources (`PyPI`, `conda-forge` etc.).
+
+### pre-commit, isort, & black
+
+This project uses [pre-commit](https://pre-commit.com/) hooks to automatically enforce certain coding standards. Before every commit [isort](https://pycqa.github.io/isort/) and [black](https://black.readthedocs.io/en/stable/index.html) are executed on staged files to ensure that all committed code is formatted consistently. The command can also be invoked manually:
+
+```bash
+pixi run pre-commit
+```
+
+Similarly, both tools can be run individually:
+
+```bash
+pixi run isort
+pixi run black
+```
+
+When invoked in this way all files under the `src/` and `tests/` directories will be reformatted, not just staged changes.
+
+### pytest
+
+This project uses [pytest](https://docs.pytest.org/en/stable/) for automated testing. To execute the test suite, run:
+
+```bash
+pixi run pytest
+```
+
+### flake8, & pyright
+
+This project uses [flake8](https://flake8.pycqa.org/en/latest/) for linting and style enforcement (in addition to `black`). It also uses [pyright](https://microsoft.github.io/pyright/#/) for static type checking. To perform pre-merge checks combining these tools, run:
+
+```bash
+pixi run pre-merge
+```
+
+Alternatively, you can run them individually:
+
+```bash
+pixi run flake8
+pixi run pyright
+```
+
+### Versioning Protocol
+
+This project follows a generalised semantic versioning where major versions are associated with a constellation as a codename. 
+
+**Format:** `MAJOR.MINOR.PATCH (Constellation Name)`
+
+#### Version Types:
+- **MAJOR (X.0.0):** New default model added, and/or breaking changes to the API → New constellation name
+- **MINOR (X.Y.0):** New features/functionality 
+- **PATCH (X.Y.Z):** Bug fixes, small improvements
+
+#### Current Version:
+- 0.5.0 (Andromeda)
+
+#### Version Philosophy:
+- **New default models, and/or breaking changes to API = Major versions** because they represent ("soft") breaking changes.
+- **Version bumps are at maintainer discretion** - not every PR requires a version change.
+- When versions are updated, `pyproject.toml`, `src/panhumanpy/__init__.py`, `README.md`, and `CONTRIBUTING.md` must be kept in sync.
+- Use versioning script for version bumps executed in a consistent fashion.
+
+#### Rules:
+1. The default model version number must match the package major version
+   - Package `0.2.1` → Model `v0` as default
+   - Package `1.3.2` → Model `v1` as default
+2. Non-model artifacts are stored in `src/panhumanpy/_tools/v{i}/` and models are saved on zenodo as mentioned in the README
+3. When bumping major package version, create new `v{i}` directory with updated models and set default model version in ANNotate.py appropriately.
+
+#### Example:
+```python
+# In __init__.py
+__version__ = "0.2.1"
+
+# In ANNotate.py  
+model_version_default = 'v0'  # Must match major version (0)
+```
+
+
+### Using the Version Bump Script
+
+For consistent version updates, use the provided script:
+
+```bash
+# Check current version
+python scripts/bump_version.py current
+
+# Check version consistency across files
+python scripts/bump_version.py check
+
+# Bug fixes (patch)
+python scripts/bump_version.py patch
+
+# New features (minor)
+python scripts/bump_version.py minor
+
+# New models or breaking changes (major)
+python scripts/bump_version.py major Cassiopeia
+
+# Run tests that will ensure version consistency across scripts and docs
+pytest
+
+# Push changes and tags on git
+git diff
+git add . && git commit -m 'Bump version to 0.2.0'
+git tag v0.2.0-andromeda
+git push --follow-tags # if on branch main
+git push origin version_bump_branch --tags # if on a separate branch
+```

panhumanpy-0.5.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: panhumanpy
+Version: 0.5.0
+Summary: A Python package for automated cell type annotation in scRNA-seq using Azimuth Neural Network.
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: anndata
+Requires-Dist: jupyter>=1.0.0
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: plotly
+Requires-Dist: scikit-learn==1.6.0
+Requires-Dist: scipy
+Requires-Dist: tensorflow==2.17
+Requires-Dist: umap-learn
+Requires-Dist: xarray
+Provides-Extra: gpu
+Requires-Dist: tensorflow[and-cuda]==2.17; extra == 'gpu'
+Description-Content-Type: text/markdown
+
+# panhumanpy
+
+**Current version: 0.5.0 (Andromeda)**
+
+A package for cell annotation using Azimuth Neural Network.
+
+## Prerequisites
+
+- `python` >=3.9
+- `pip`
+- `git`
+
+## Installation
+
+To install the base version of the package (with CPU support only), run:
+
+```bash
+pip install panhumanpy
+```
+
+or to install from GitHub, run:
+
+```bash
+pip install git+https://github.com/satijalab/panhumanpy.git
+```
+
+If you require GPU acceleration for enhanced performance on compatible hardware, install the package with GPU dependencies:
+
+```bash
+pip install panhumanpy[gpu]
+```
+
+or from GitHub:
+
+
+```bash
+pip install git+https://github.com/satijalab/panhumanpy.git#egg=panhumanpy[gpu]
+```
+
+## Model Versions
+
+panhumanpy uses versioned models corresponding to major package releases. The package defaults to model 'v{i}' where i is the major package version. For example for panhumanpy 0.2.1 (Andromeda), the default model version is 'v0'. For most users, the default version is recommended. The user can also choose to use a different model version as outlined in the tutorial mentioned below. 
+
+Currently available model versions: 'v0', 'v1'
+
+## Model Weights
+
+Model weights are hosted on Zenodo and downloaded automatically on first use, cached in `~/.cache/panhumanpy/`. No manual download is required.
+
+| Field | Detail |
+|---|---|
+| DOI | https://doi.org/10.5281/zenodo.20401417 |
+| Models | v0, v1 |
+| License | CC BY 4.0 |
+
+## Cell Ontology Mapping
+
+panhumanpy includes a built-in crosswalk that maps Pan-human Azimuth cell type annotations to [Cell Ontology](https://obofoundry.org/ontology/cl.html) (CL) terms. This mapping is versioned alongside the model and can be applied to annotation outputs via the `map_to_cell_ontology` function in `ANNotate_tools` or the `map_to_cell_ontology` method on `AzimuthNN` and `AzimuthNN_base`.
+
+**Crosswalk provenance:**
+
+| Field | Detail |
+|---|---|
+| Title | Crosswalk of Pan-human Azimuth Types annotated cells to Cell Ontology |
+| Author | Aleix Puig-Barbe |
+| Author ORCID | 0000-0001-6677-8489 |
+| Reviewers | Bruce Herr II, Katy Borner, Jie Zheng |
+| Reviewer ORCIDs | 0000-0002-6703-7647, 0000-0002-3321-6137, 0000-0002-2999-0103 |
+| Data DOI | https://doi.org/10.48539/HBM727.TLKL.237 |
+| Date | December 15, 2025 |
+| Version | v1.1 |
+
+## Tutorial
+
+For an introductory tutorial, please check out this [notebook](https://github.com/satijalab/panhumanpy/blob/main/tutorial_panhumanpy.ipynb).

panhumanpy-0.5.0/README.md

@@ -0,0 +1,75 @@
+# panhumanpy
+
+**Current version: 0.5.0 (Andromeda)**
+
+A package for cell annotation using Azimuth Neural Network.
+
+## Prerequisites
+
+- `python` >=3.9
+- `pip`
+- `git`
+
+## Installation
+
+To install the base version of the package (with CPU support only), run:
+
+```bash
+pip install panhumanpy
+```
+
+or to install from GitHub, run:
+
+```bash
+pip install git+https://github.com/satijalab/panhumanpy.git
+```
+
+If you require GPU acceleration for enhanced performance on compatible hardware, install the package with GPU dependencies:
+
+```bash
+pip install panhumanpy[gpu]
+```
+
+or from GitHub:
+
+
+```bash
+pip install git+https://github.com/satijalab/panhumanpy.git#egg=panhumanpy[gpu]
+```
+
+## Model Versions
+
+panhumanpy uses versioned models corresponding to major package releases. The package defaults to model 'v{i}' where i is the major package version. For example for panhumanpy 0.2.1 (Andromeda), the default model version is 'v0'. For most users, the default version is recommended. The user can also choose to use a different model version as outlined in the tutorial mentioned below. 
+
+Currently available model versions: 'v0', 'v1'
+
+## Model Weights
+
+Model weights are hosted on Zenodo and downloaded automatically on first use, cached in `~/.cache/panhumanpy/`. No manual download is required.
+
+| Field | Detail |
+|---|---|
+| DOI | https://doi.org/10.5281/zenodo.20401417 |
+| Models | v0, v1 |
+| License | CC BY 4.0 |
+
+## Cell Ontology Mapping
+
+panhumanpy includes a built-in crosswalk that maps Pan-human Azimuth cell type annotations to [Cell Ontology](https://obofoundry.org/ontology/cl.html) (CL) terms. This mapping is versioned alongside the model and can be applied to annotation outputs via the `map_to_cell_ontology` function in `ANNotate_tools` or the `map_to_cell_ontology` method on `AzimuthNN` and `AzimuthNN_base`.
+
+**Crosswalk provenance:**
+
+| Field | Detail |
+|---|---|
+| Title | Crosswalk of Pan-human Azimuth Types annotated cells to Cell Ontology |
+| Author | Aleix Puig-Barbe |
+| Author ORCID | 0000-0001-6677-8489 |
+| Reviewers | Bruce Herr II, Katy Borner, Jie Zheng |
+| Reviewer ORCIDs | 0000-0002-6703-7647, 0000-0002-3321-6137, 0000-0002-2999-0103 |
+| Data DOI | https://doi.org/10.48539/HBM727.TLKL.237 |
+| Date | December 15, 2025 |
+| Version | v1.1 |
+
+## Tutorial
+
+For an introductory tutorial, please check out this [notebook](https://github.com/satijalab/panhumanpy/blob/main/tutorial_panhumanpy.ipynb).