Initialization

Author: inecik

.github/workflows/docs-check.yml

@@ -0,0 +1,27 @@
+name: Docs Check
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[docs]
+
+      - name: Build Sphinx docs
+        run: sphinx-build -b html docs docs/_build/html

.github/workflows/pypi-publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install build backend
+        run: python -m pip install --upgrade pip build
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          packages_dir: dist

.github/workflows/readthedocs.yml

@@ -0,0 +1,21 @@
+name: Read the Docs Trigger
+
+on:
+  push:
+    branches: ["main"]
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  trigger:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Trigger Read the Docs build
+        uses: readthedocs/actions@v1
+        with:
+          token: ${{ secrets.READTHEDOCS_TOKEN }}
+          project: cellucid

.gitignore

@@ -0,0 +1,37 @@
+# Bytecode / cache
+__pycache__/
+*.py[cod]
+*.pyo
+.pytest_cache/
+
+# Virtual envs
+.env
+.venv
+env/
+venv/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Build / dist
+build/
+dist/
+*.egg-info/
+htmlcov/
+.coverage
+coverage.xml
+
+# Logs / dumps
+*.log
+*.tmp
+*.swp
+
+# Local data artifacts
+data/**
+!data/.gitkeep
+!data/raw/.gitkeep
+!data/experiments/.gitkeep
+exports/**
+project_context.txt

.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+        - analysis

README.md

@@ -0,0 +1,73 @@
+<p align="center">
+  <img src="cellucid-logo.svg" alt="Cellucid logo" width="180">
+</p>
+
+# cellucid (Python)
+
+Python utilities for exporting AnnData/numpy payloads into the manifest + binary format consumed by the Cellucid WebGL viewer. Everything here is independent of the website; generate data wherever you like, then copy the resulting files into the viewer’s `assets/exports/` directory when you host the site.
+
+## Layout (repo: theislab/cellucid-data)
+- `src/cellucid/prepare_data.py`: `export_data_for_web` writes points/obs/var/connectivity binaries into an `exports/` directory (configurable).
+- `src/cellucid/anndata_variations.py`: UMAP sweep helper for experimentation (uses Scanpy).
+- `src/cellucid/repo_to_text.py`: utility to dump repository contents to a single text file.
+- `notebooks/`: exploratory notebook that demonstrates exporting viewer assets.
+- `data/`: example/raw inputs (h5ad, pickles) and experiment outputs live here; this folder stays untracked by default.
+
+## Installation
+Requires Python 3.10+.
+
+From the repo root:
+
+```bash
+pip install -e python
+# or with optional extras
+pip install -e python[analysis,docs]
+```
+
+The package name is `cellucid` and imports under `cellucid`.
+
+## Usage
+```python
+import scanpy as sc
+from cellucid.prepare_data import export_data_for_web
+
+adata = sc.read_h5ad("path/to/adata.h5ad")
+export_data_for_web(
+    X_umap=adata.obsm["X_umap"],
+    latent_space=adata.X,
+    obs=adata.obs,
+    var=adata.var,
+    gene_expression=adata.X,
+    connectivities=adata.obsp.get("connectivities"),
+    out_dir="exports",  # default; change as needed
+    var_quantization=8,
+    obs_continuous_quantization=8,
+    compression=6,
+)
+```
+
+The exporter defaults to `exports/` under your current working directory. After generation, copy or sync that folder into the website’s `assets/exports/` directory so the viewer can load the files.
+
+To run the UMAP sweep helper:
+
+```bash
+python -m cellucid.anndata_variations
+```
+
+Ensure `python/data/raw` contains the expected h5ad/pickle files or override the module constants before calling. Paths in the notebook and sweep helper assume the `data/` directory inside this `python/` project; point them to your own locations as needed.
+
+## Companion web viewer (theislab/cellucid)
+The static viewer lives in a separate repository (`theislab/cellucid`). After running `export_data_for_web`, copy or sync the resulting `exports/` directory into that repo’s `assets/exports/` folder before hosting. The manifest/binary schema is shared; no build step is required on the web side.
+
+## Documentation
+- Build locally: `pip install -e python[docs] && sphinx-build -b html docs docs/_build/html`
+- Read the Docs: `python/.readthedocs.yaml` targets `docs/conf.py` with the `docs` extra.
+
+## Publishing
+Install packaging tools if needed: `pip install build twine`
+
+1. From `python/`, bump the version in `pyproject.toml`.
+2. Build: `python -m build`
+3. Upload to PyPI (or TestPyPI) with `twine upload dist/*`.
+
+Update the `license`, `authors`, and `Repository` URL in `pyproject.toml` before publishing if needed.

cellucid-logo.svg

@@ -0,0 +1,33 @@
+"""Sphinx configuration for the cellucid Python package."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+SRC_DIR = PROJECT_ROOT / "src"
+sys.path.insert(0, str(SRC_DIR))
+
+project = "cellucid"
+author = "cellucid contributors"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autosummary",
+    "myst_parser",
+]
+
+autosummary_generate = True
+templates_path = ["_templates"]
+exclude_patterns: list[str] = ["_build"]
+
+html_theme = "sphinx_rtd_theme"
+
+try:
+    from cellucid import __version__
+except Exception:  # pragma: no cover - import may fail during initial setup
+    release = version = "0.0.0"
+else:
+    release = version = __version__

data/.gitkeep

@@ -0,0 +1,26 @@
+# cellucid
+
+Utilities to export AnnData/numpy payloads for the 3D UMAP WebGL viewer.
+
+## Quickstart
+- Install: `pip install -e python[docs,analysis]`
+- Export data: `from cellucid.prepare_data import export_data_for_web`
+- Default outputs land in `exports/` under your working directory; copy them into the viewer’s `assets/exports/` folder when hosting the site, or override `out_dir` to point there directly.
+
+Companion viewer: static site in `theislab/cellucid` expects the exported `assets/exports/` folder.
+
+## API
+```{autofunction} cellucid.prepare_data.export_data_for_web
+```
+```{automodule} cellucid.anndata_variations
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## Local docs build
+```bash
+cd python
+pip install -e .[docs]
+sphinx-build -b html docs docs/_build/html
+```