Revisions

.github/workflows/tests.yml

@@ -0,0 +1,28 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  smoke-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: pip
+
+      - name: Install package and test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Run smoke test
+        run: python -m pytest tests/test_smoke.py

.gitignore

@@ -52,9 +52,6 @@ coverage.xml
 *.mo
 *.pot
 
-# Sphinx documentation
-docs/_build/
-
 # PyBuilder
 .pybuilder/
 target/

README.md

@@ -9,11 +9,16 @@
 
 Notebooks for reproducing manuscript figures and analyses are available at [csglab/sclsd-manuscript](https://github.com/csglab/sclsd-manuscript).
 
+This README is the maintained documentation for the `sclsd` package. It covers
+installation, input data, configuration, training, inference, reproducibility,
+and citation information.
+
 ## Overview
 
 LSD reinterprets Waddington's epigenetic landscape as an energy landscape in a learned latent cell state space. Cell differentiation is modeled as a stochastic dynamical system governed by a gradient flow down this potential surface, combined with noise representing gene expression variability.
 
 The model jointly infers:
+
 - **Cell state**: A latent representation of each cell's gene expression profile
 - **Differentiation state**: A 2D embedding capturing developmental progression
 - **Waddington potential**: An energy function whose gradient defines differentiation dynamics
@@ -32,17 +37,13 @@ git clone https://github.com/csglab/sclsd.git
 cd sclsd
 pip install -e .
 ```
-> [!NOTE]
-> As a lightweight Python package, installation time varies depending on pre-existing dependencies in your environment, starting from scratch, expect it to take less than 10 minutes.
 
 ### Dependencies
 
-- Python ≥3.9
-- PyTorch ≥2.0.0
-- Pyro-PPL ≥1.8.0
-- torchdiffeq ≥0.2.0
-- scanpy ≥1.9.0
-- cellrank ≥2.0.0
+The package requires Python 3.9 or later. Runtime dependencies, including
+PyTorch, Pyro, torchdiffeq, Scanpy, AnnData, and CellRank, are installed by
+`pip`. The complete dependency specification is maintained in
+[`pyproject.toml`](https://github.com/csglab/sclsd/blob/main/pyproject.toml).
 
 ## Quick Start
 
@@ -138,7 +139,7 @@ cfg = LSDConfig()
 
 # Model architecture
 cfg.model.z_dim = 10              # Cell state dimensions
-cfg.model.B_dim = 2               # Differentiation state dimensions (fixed at 2)
+cfg.model.B_dim = 2               # Differentiation state dimensions (default: 2)
 cfg.model.V_coeff = 0.01          # Potential regularization
 
 # Training trajectories
@@ -153,11 +154,12 @@ cfg.optimizer.adam.lr = 1e-3      # Learning rate
 ## Data Requirements
 
 Input AnnData should contain:
+
 - Log-normalized expression in `adata.X`
 - Raw counts in `adata.layers["raw"]`
 - Library sizes in `adata.obs["librarysize"]`
 - Precomputed neighbor graph in `adata.obsp["connectivities"]`
-- Pseudotime values (e.g., from diffusion pseudotime) for prior initialization
+- Pseudotime values in `adata.obs` when initializing transitions from a pseudotime key; alternatively, users may supply a transition matrix directly
 
 ## Method
 
@@ -169,11 +171,47 @@ where $V(z)$ is the Waddington potential parameterized by a neural network, and
 
 Training trajectories are generated by random walks on a k-nearest neighbor graph, biased by pseudotime to follow developmental progression.
 
+## Reproducibility
+
+Dataset-specific training and postprocessing notebooks are available in the
+[`sclsd-manuscript`](https://github.com/csglab/sclsd-manuscript) repository.
+The preprocessed datasets used by those notebooks are available from
+[Zenodo record 18331587](https://zenodo.org/records/18331587).
+
 ## Citation
 
-If you use sclsd, please cite:
+If you use `sclsd` or the accompanying analyses, please cite:
+
+> Poursina, A., Hajhashemi, S., Mikaeili Namini, A., Saberi, A., Emad, A., &
+> Najafabadi, H. S. (2026). A Latent Space Thermodynamic Model of Cell
+> Differentiation. *bioRxiv*, 2026.03.04.709512.
+> https://doi.org/10.64898/2026.03.04.709512
+
+[View version 1 on bioRxiv](https://www.biorxiv.org/content/10.64898/2026.03.04.709512v1)
+
+### BibTeX
+
+```bibtex
+@article{poursina2026latent,
+  title     = {A Latent Space Thermodynamic Model of Cell Differentiation},
+  author    = {Poursina, Ali and Hajhashemi, Shayan and
+               {Mikaeili Namini}, Arsham and Saberi, Ali and
+               Emad, Amin and Najafabadi, Hamed S.},
+  journal   = {bioRxiv},
+  pages     = {2026.03.04.709512},
+  year      = {2026},
+  publisher = {Cold Spring Harbor Laboratory},
+  doi       = {10.64898/2026.03.04.709512},
+  url       = {https://www.biorxiv.org/content/10.64898/2026.03.04.709512v1}
+}
+```
+
+## Contact
 
-> Poursina A, Hajhashemi S, Mikaeili Namini A, Saberi A, Emad A, Najafabadi HS. A Latent Space Thermodynamic Model of Cell Differentiation. 2026.
+For questions about the sclsd software, contact Ali Poursina at
+[ali.poursina@mail.mcgill.ca](mailto:ali.poursina@mail.mcgill.ca). Bug reports and
+feature requests can also be submitted through the
+[GitHub issue tracker](https://github.com/csglab/sclsd/issues).
 
 ## License
 

benchmarks/__init__.py

@@ -0,0 +1 @@
+"""Benchmark helpers that are not part of the public sclsd package."""