scatrans 0.9.9.dev1__tar.gz → 0.9.10.dev0__tar.gz

{scatrans-0.9.9.dev1 → scatrans-0.9.10.dev0}/.gitignore

@@ -69,6 +69,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/api/generated/
 
 # PyBuilder
 .pybuilder/

scatrans-0.9.10.dev0/.readthedocs.yaml

@@ -0,0 +1,20 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .

{scatrans-0.9.9.dev1 → scatrans-0.9.10.dev0}/CHANGELOG.md

@@ -2,10 +2,29 @@
 
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
-## [0.9.9] - 2026-07-04
+## 2026-07-05
+
+### Fixed
+- **`run_gsea` made downstream `DataFrame` operations pathologically slow**: the
+  per-term running-enrichment-score curves stored in `res_df.attrs["gsea_details"]`
+  (tens of millions of floats for a genome-wide ranked list against thousands of
+  gene sets) were deep-copied by pandas' `NDFrame.__finalize__` on essentially
+  every subsequent `DataFrame` operation (`.head()`, `.copy()`, slicing, column
+  assignment), including inside `scat.pl.enrich_dotplot` and `scat.pl.gseaplot`.
+  This made those two plotting functions appear to hang indefinitely (in practice:
+  several minutes) on real GSEA results, and made even a plain `gsea_res.head()`
+  slow. `gsea_details` and `ranking` are now wrapped in a small dict subclass
+  whose `__deepcopy__` is an O(1) identity return (safe: these payloads are
+  write-once/read-only after `run_gsea` returns). `enrich_dotplot`/`gseaplot`
+  on a real ~3700-term result went from indefinite/minutes to <0.1s / ~6s.
+- **`run_gsea` returned several numeric columns (`ES`, `NES`, `pvalue`, `p.adjust`,
+  `FWER_pval`, `Tag_percent`, `Gene_percent`) as `object` dtype** instead of
+  `float`, inherited as-is from `gseapy`'s `res2d`. Now coerced explicitly via
+  `pd.to_numeric`. Contributed to (but was not the root cause of) the hang above.
+
+## 2026-07-04
 
 ### Added
 - **`scat.pl.volcano_plot(style=...)`**: ggVolcano-inspired styles from
@@ -29,10 +48,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **MixedLM**: NaN neutral-fill on degenerate fits; composite ``condition::sample``
   random-effect groups when replicate labels are reused across conditions (``paired_replicates=True``
   for paired designs).
-
-## [0.9.8 bugfix 2026-07-04]
-
-### Fixed
 - **CI pytest failure on matrix legs without `pydeseq2`**: two new pseudobulk regression tests
   (`test_strict_pydeseq2_counts_rejects_log_normalized_*`) now use the same
   `@pytest.mark.skipif(importlib.util.find_spec("pydeseq2") is None, ...)` guard as
@@ -60,20 +75,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - README: noted that `anndata.concat()` drops `uns['log1p']` and recommends re-setting the marker
   or passing `de_preprocess="none"` explicitly after combining pre-normalized samples.
 
-## [0.9.8] - 2026-07-03
+## 2026-07-03
 
 ### Changed (user-visible default behavior)
 - **`active_score()` built-in `significant` list** now uses the same default thresholds as
   `filter_active_genes(preset="heuristic")`: `logFC > 0.35`, `unspliced_excess_residual > 1.0`,
   `active_score >= 55`, `active_score_fdr < 0.25`, plus `p_adj` / `unspliced_excess_fdr` cutoffs.
-  Re-running analyses with defaults may return a **different** significant gene set than 0.9.2
-  (typically more genes when signal is present; aligns with the documented post-hoc workflow).
+  Re-running analyses with defaults may return a **different** significant gene set than the
+  2026-06-20 release (typically more genes when signal is present; aligns with the documented
+  post-hoc workflow).
 - **`active_score(logfc_cutoff=...)` default** lowered from `0.5` to `0.35` to match the heuristic
   preset (only affects the built-in significant mask and metadata; ranking in `all_results` unchanged).
 - **`gamma_method="empirical_bayes"` + `prior_weight`**: fixed a numeric floor so `prior_weight` in
   the usual tuning range (0.5–5.0, including the default 5.0) now changes `count_pseudocount` and
-  shrinkage weights instead of being pinned at 1.0. EB gamma values may differ from 0.9.2 at the
-  same `prior_weight`.
+  shrinkage weights instead of being pinned at 1.0. EB gamma values may differ from the 2026-06-20
+  release at the same `prior_weight`.
 
 ### Fixed
 - **`scat.pl.gseaplot`**: RES curve / hit ticks and the bottom ranked-metric bar now share the same
@@ -104,7 +120,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Documentation
 - README built-in `significant` section updated to match `HEURISTIC_FILTER_DEFAULTS`.
 
-## [0.9.2 bugfix 2026-07-02]
+## 2026-07-02
 
 ### Fixed
 - **compare_enrichment / concat_compare_results metadata**: `attrs["clusters"]` now lists only clusters that contributed rows to the combined table (skipped, failed, and empty per-cluster runs remain in `per_cluster` diagnostics only). Fixes ghost cluster names in both the main compare API and the concat wrapper.
@@ -122,7 +138,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Regression test `test_filter_active_genes_permissive_keeps_padj_one`.
 
-## [Unreleased / Review 2026-06-27]
+## 2026-06-27
+
 ### Added / Improved
 - Clarified and documented the `gamma_method="empirical_bayes"` implementation as **hierarchical (分层) gamma estimation** for the reference U/S ratio (README keeps the CN term; source now English-only).
 - Stronger emphasis on "always pass explicit target_group/reference_group".
@@ -142,7 +159,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Reduced anndata category storage log noise during internal DE/perm (narrow logger level bump).
 - All tests + targeted EB/perm/explicit-norm cases pass after fixes.
 
-### Additional fixes (2026-06-27 round 2)
+### Additional fixes (round 2)
 - **Scientific Error 3**: `generate_gene_features_from_gtf()` now computes **true exon union length per gene** (merge overlapping intervals) instead of naively summing all exons across all transcripts. Prevents ~N_transcript-fold overestimation of gene_length for multi-isoform genes (affects only users who generate their own tables; bundled .parquet files are unaffected).
 - **Scientific Error 4**: `logFC` is now normalized toward consistent **log2 scale** across backends inside `_run_de_wrapper`:
   - wilcoxon, mixedlm, memento: divided by ln(2)
@@ -155,7 +172,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Design 8**: Made the "max > 50" heuristic in `_prepare_log_normalized_expression` (mixed model prep) more robust: checks for negatives, uses lower threshold (20), better warning message.
 - **Design 9**: `valid_expr` is now **explicitly passed** from `tl.py` into `run_permutation_test` (no more hidden reliance on adata.var after the fact).
 
-### Post-review hardening (2026-06-27)
+### Post-review hardening
 - **Fragility fix (high)**: Added explicit schema validation + safe column access + clear warning in `_run_memento_de` for expected 'de_coef'/'de_pval' from memento.binary_test_1d. Prevents silent fallback (or crash) if upstream memento-de changes column names/structure. Updated optional dep pin to "memento-de>=0.1.0,<0.3.0".
 - **Cleanup + consistency (high)**: `run_permutation_test` now owns the small-space FDR decision (use_fdr=False + disabled_reason="small_permutation_space" when n_perm < 100). Removed vestigial dead `if not perm_use_fdr` and useless max_perm check/assign in tl.py. `disabled_reason` (and `perm_disabled_reason`) now properly returned and stored in adata.uns["scatrans"] metadata.
 - **Diagnostics improvement**: MixedLM per-gene fits now count genes hitting the neutral-except fallback (`n_genes_failed_fit`). Recorded in diagnostics["mixed_model"] (active_score) and DE metadata (differential_expression). Warning emitted when >0 so users are not unaware of silent neutral (delta_var=0, p=1) genes.
@@ -163,7 +180,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 All new issues addressed. Full test suite green.
 
-## [0.9.2] - 2026-06-20
+## 2026-06-20
 
 ### Added / Changed
 - `filter_active_genes` now accepts `logfc_direction="up"|"down"|"both"` (default remains `"up"` for backward compatibility and "active" semantics).
@@ -174,7 +191,7 @@ All new issues addressed. Full test suite green.
   - This directly supports the common request for downregulated candidates in standalone DE workflows.
 - Updated docstrings, tests, and examples.
 
-## [0.9.0] - 2026-06-19
+## 2026-06-19
 
 ### Added
 - `run_gsea(ranked_genes, gene_sets=..., nperm=..., ...)` — pre-ranked GSEA (via gseapy.prerank wrapper).
@@ -190,32 +207,7 @@ All new issues addressed. Full test suite green.
 - Minor internal cleanups and test coverage for the new GSEA path.
 - All new functions follow the existing consistent signatures (`ax=`, `use_style=`, `save_path=`, etc.).
 
-## [0.8.0] - 2026-06-14
-
-### Added (enrichment module — major paper-readiness upgrade)
-- `run_go(ontology="BP"|"CC"|"MF"|"ALL", ...)` — direct wrapper analogous to clusterProfiler `enrichGO`. Supports `adjust_across_all=True` for a single BH correction across all GO terms when using "ALL".
-- `save_enrichment_report(res, prefix=..., save_excel=True, save_csv=True, save_tsv=True, save_metadata=True, save_term_gene_table=True)` — one-call export of main table, term-gene long table (via `expand_enrichment_genes`), and rich `metadata.json` + xlsx sheet. Auto-creates parent directories. List columns (e.g. `Genes_list`) are sanitized to `;` strings for clean export.
-- `expand_enrichment_genes(res)` — expands the `Genes` (semicolon) column into a long-format Term–Gene table (one row per gene). Preserves `Ontology` column when input came from `run_go(..., "ALL")`.
-- Rich provenance in every result `.attrs` (success and empty):
-  - `analysis_info`: package, version, timestamp, module
-  - `gene_set_info`: `requested`/`resolved`, `requested_source` vs `actual_source` ("bundled", "gseapy", "gmt", "dict"), `library_name`, `n_terms`, `n_unique_genes`
-  - `universe_info`: full details of background handling (provided size, restricted, dropped_by_annotation, force_universe, mapping counts)
-  - Empty results now carry `reason` ("gene_list_empty", "universe_empty", "no_term_overlap_after_filters", ...) + the above fields so users can diagnose why nothing came back.
-- New `run_enrichment` / `run_kegg` / `run_go` parameters: `padj_cutoff` (preferred modern name), `include_gene_list` (adds `Genes_list` python-list column), `adjust_across_all`.
-- `list_bundled_gene_sets()` now clearly documents the 2026 organism-specific defaults.
-- Improved low-mapping-rate warning (includes input examples + gene-set examples).
-- `background` is now a documented deprecated alias of `universe`; passing both raises immediately.
-- All empty-result DataFrames preserve consistent columns (including optional `Genes_list` when requested) and full diagnostic attrs.
-
-### Changed / Improved
-- `_load_gene_sets` now returns `(term_to_genes, term_to_desc, load_info)` so `actual_source` is always recorded accurately (even on gseapy fallback after bundled attempt).
-- `run_kegg` fully synchronized with new parameters (`padj_cutoff`, `include_gene_list`, etc.).
-- `enrich_dotplot` (pl.py) and various tl.py flows updated for new columns/attrs.
-- Version unified to 0.8.0 for this release.
-- README and docstrings extensively updated with manuscript-export examples, `run_go`, provenance details, and `adjust_across_all` guidance.
-- Full test coverage for new paths (per-ontology attrs, within_ontology p.adjust, save+tsv+dir creation, expand with Ontology, dual-cutoff warning, etc.). All tests pass.
-
-## [0.9.0] - 2026-06-18
+## 2026-06-18
 
 ### Added
 - **Independent permutation statistics for unspliced excess**: `unspliced_excess_pval` and `unspliced_excess_fdr` (one-sided test on bias-corrected `unspliced_excess_residual`). Computed alongside existing `active_score_pval` / `active_score_fdr` when `use_permutation=True`.
@@ -239,33 +231,52 @@ All new issues addressed. Full test suite green.
 - `active_fdr_cutoff` (no longer used for built-in significance; use `unspliced_excess_fdr_cutoff`).
 - `velocity_residual_cutoff` in `filter_active_genes` (use `unspliced_excess_residual_cutoff`).
 
-## [Unreleased]
+## 2026-06-14
+
+### Added (enrichment module — major paper-readiness upgrade)
+- `run_go(ontology="BP"|"CC"|"MF"|"ALL", ...)` — direct wrapper analogous to clusterProfiler `enrichGO`. Supports `adjust_across_all=True` for a single BH correction across all GO terms when using "ALL".
+- `save_enrichment_report(res, prefix=..., save_excel=True, save_csv=True, save_tsv=True, save_metadata=True, save_term_gene_table=True)` — one-call export of main table, term-gene long table (via `expand_enrichment_genes`), and rich `metadata.json` + xlsx sheet. Auto-creates parent directories. List columns (e.g. `Genes_list`) are sanitized to `;` strings for clean export.
+- `expand_enrichment_genes(res)` — expands the `Genes` (semicolon) column into a long-format Term–Gene table (one row per gene). Preserves `Ontology` column when input came from `run_go(..., "ALL")`.
+- Rich provenance in every result `.attrs` (success and empty):
+  - `analysis_info`: package, version, timestamp, module
+  - `gene_set_info`: `requested`/`resolved`, `requested_source` vs `actual_source` ("bundled", "gseapy", "gmt", "dict"), `library_name`, `n_terms`, `n_unique_genes`
+  - `universe_info`: full details of background handling (provided size, restricted, dropped_by_annotation, force_universe, mapping counts)
+  - Empty results now carry `reason` ("gene_list_empty", "universe_empty", "no_term_overlap_after_filters", ...) + the above fields so users can diagnose why nothing came back.
+- New `run_enrichment` / `run_kegg` / `run_go` parameters: `padj_cutoff` (preferred modern name), `include_gene_list` (adds `Genes_list` python-list column), `adjust_across_all`.
+- `list_bundled_gene_sets()` now clearly documents the 2026 organism-specific defaults.
+- Improved low-mapping-rate warning (includes input examples + gene-set examples).
+- `background` is now a documented deprecated alias of `universe`; passing both raises immediately.
+- All empty-result DataFrames preserve consistent columns (including optional `Genes_list` when requested) and full diagnostic attrs.
+
+### Changed / Improved
+- `_load_gene_sets` now returns `(term_to_genes, term_to_desc, load_info)` so `actual_source` is always recorded accurately (even on gseapy fallback after bundled attempt).
+- `run_kegg` fully synchronized with new parameters (`padj_cutoff`, `include_gene_list`, etc.).
+- `enrich_dotplot` (pl.py) and various tl.py flows updated for new columns/attrs.
+- README and docstrings extensively updated with manuscript-export examples, `run_go`, provenance details, and `adjust_across_all` guidance.
+- Full test coverage for new paths (per-ontology attrs, within_ontology p.adjust, save+tsv+dir creation, expand with Ontology, dual-cutoff warning, etc.). All tests pass.
+
+## 2026-06-09
 
 ### Added
-- **Rich runtime diagnostics** (high priority improvement): `active_score` now automatically computes global unspliced fraction (via integrated `qc.unspliced_global`), captures detailed bias-correction fit results (coefficients, n_genes_used, fallback status), stores per-gene `effective_gamma`, and records everything under `adata.uns["scatrans"]["diagnostics"]`. A concise run summary is logged at completion.
-- New public helper `scat.pl.velocity_phase_portraits(adata, genes, groupby=...)` for quick visual inspection of U vs S relationships on top hits (lower-priority diagnostic aid).
+- **Rich runtime diagnostics**: `active_score` now automatically computes global unspliced fraction (via integrated `qc.unspliced_global`), captures detailed bias-correction fit results (coefficients, n_genes_used, fallback status), stores per-gene `effective_gamma`, and records everything under `adata.uns["scatrans"]["diagnostics"]`. A concise run summary is logged at completion.
+- New public helper `scat.pl.velocity_phase_portraits(adata, genes, groupby=...)` for quick visual inspection of U vs S relationships on top hits.
 - `examples/real_data_template.py` — heavily commented, non-runnable but copy-adaptable template demonstrating the full recommended real-data workflow, QC, diagnostics inspection, and publication plotting.
 - Explicit documentation of the permutation approximation (velocity layers fixed from original data; only labels shuffled) in code metadata, logs, and the new "Choosing mode" section of the README.
 - `effective_gamma` column is now added to `adata.var` (and included in result tables when present) for transparency of the gamma used in the delta calculation.
-
-### Changed / Improved
-- Major usability & paper-readiness upgrade to diagnostics, metadata, and user guidance.
-- `qc.unspliced_global` is now called automatically inside `active_score` (result stored); the function remains directly usable as a pre-flight check (`scat.qc.unspliced_global(adata)`).
-- Added prominent "Choosing `mode`: heuristic vs advanced (and common pitfalls)" section + decision guide to README.
-
-### Added (0609 refactor)
 - Mixed model support (`use_mixed_model=True` + `sample_col`): statsmodels LMM (~ condition + (1 | sample)) as cell-level replicate-aware DE backend (lightweight Python analogue to dreamlet/variancePartition/dreampy LMM + Libra mixed options). Replaces scanpy/pydeseq2 p/logFC when enabled.
 - Delta Variance: `delta_variance` (condition-attributable variance fraction, 0-1, variancePartition-style) and `delta_var_pval` (LRT) computed during mixed fit; always surfaced in `all_results` / adata.var / diagnostics when mixed used.
 - New `active_score` options: `use_delta_variance_pval` (bool) + `delta_var_pval_cutoff` to optionally include the delta LRT pval as supplementary filter in significant gene selection.
 - Full backward compat; mixed path documented vs. pseudobulk; guidance + references to Libra, dreampy, NEBULA, dreamlet in README.
-- Existing package backed up to `backup/backup0609/`.
 - Tests + direct verification cover mixed, delta col, filter option, incompatibility with pseudobulk, and no regression on legacy paths. All tests pass.
 - Enhanced `README.md` with real-data workflow pointers and stronger emphasis on inspecting diagnostics.
 - `scat.pl` now documents the new phase-portrait helper; all existing `ax=` support preserved.
 - Internal: `_fit_huber_bias_correction` and velocity helpers now return extra fit/quality information (used for the new diagnostics) while preserving full backward compatibility of public results.
 
-### Changed
-- **Major internal refactor** (2025): Core logic in `tl.py` (`active_score`) was extracted into private supporting modules (`_utils.py`, `_de.py`, `_velocity.py`, `_bias.py`, `_permutation.py`). The public `active_score` function is now a thin, readable orchestrator while preserving 100% identical behavior, return values, and side effects on `adata`.
+### Changed / Improved
+- Major usability & paper-readiness upgrade to diagnostics, metadata, and user guidance.
+- `qc.unspliced_global` is now called automatically inside `active_score` (result stored); the function remains directly usable as a pre-flight check (`scat.qc.unspliced_global(adata)`).
+- Added prominent "Choosing `mode`: heuristic vs advanced (and common pitfalls)" section + decision guide to README.
+- **Major internal refactor** (2026-06-09): Core logic in `tl.py` (`active_score`) was extracted into private supporting modules (`_utils.py`, `_de.py`, `_velocity.py`, `_permutation.py`, plus bias correction in `pp_bias.py`). The public `active_score` function is now a thin, readable orchestrator while preserving 100% identical behavior, return values, and side effects on `adata`.
 - Logging discipline: Library code in `pp_bias.py` and the gene-features generator now uses the `scatrans` logger instead of direct `print()` calls with emojis. CLI entrypoint configures basic logging for user-friendly output.
 - Package data access (`add_gene_features`, etc.) now uses `importlib.resources` (with backport for Python < 3.9) for robustness across wheel, sdist, and editable installs.
 - Plotting module docstrings and a few source comments cleaned of exaggerated language.
@@ -280,11 +291,7 @@ All new issues addressed. Full test suite green.
 
 ### Deprecated / Notes
 - The previous "review fixes applied" comment in `tl.py` was removed as part of the refactor.
-- Old code is preserved in the `backup/` directory for reference.
-
-## [0.7.0] - Previous release (pre-refactor baseline)
 
-See git history and the original README for prior changes. The 0.7 series introduced the dual-track (heuristic/advanced) engine, kb_python layer support, permutation testing, and the current public API surface.
+## Earlier
 
-[Unreleased]: https://github.com/scATrans/scatrans/compare/v0.7.0...HEAD
-[0.7.0]: https://github.com/scATrans/scatrans/releases/tag/v0.7.0
+Pre-refactor baseline introduced the dual-track (heuristic/advanced) engine, kb_python layer support, permutation testing, and the current public API surface. See git history and the original README for prior changes.

{scatrans-0.9.9.dev1 → scatrans-0.9.10.dev0}/CITATION.cff

@@ -5,8 +5,8 @@ message: >-
 type: software
 authors:
   - name: "scATrans Developers"
-repository-code: "https://github.com/scATrans/scatrans"
-url: "https://github.com/scATrans/scatrans"
+repository-code: "https://github.com/leelieber2025/scATrans"
+url: "https://github.com/leelieber2025/scATrans"
 license: Apache-2.0
 version: 0.9.9
 keywords:

scatrans-0.9.10.dev0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: scatrans
+Version: 0.9.10.dev0
+Summary: Single-cell Active Transcription Analysis
+Author: scATrans Developers
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/leelieber2025/scATrans
+Project-URL: Documentation, https://scatrans.readthedocs.io
+Project-URL: Changelog, https://scatrans.readthedocs.io/en/latest/changelog.html
+Keywords: single-cell,RNA-seq,unspliced,nascent RNA,active transcription,bioinformatics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scanpy>=1.9
+Requires-Dist: anndata>=0.8
+Requires-Dist: numpy>=1.21
+Requires-Dist: pandas>=1.3
+Requires-Dist: pyarrow>=10.0
+Requires-Dist: scipy>=1.7
+Requires-Dist: scikit-learn>=1.0
+Requires-Dist: joblib>=1.2
+Requires-Dist: statsmodels>=0.13
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: seaborn>=0.12
+Requires-Dist: adjustText>=0.7
+Requires-Dist: importlib_resources>=5.0; python_version < "3.10"
+Provides-Extra: advanced
+Requires-Dist: scvelo>=0.3.0; extra == "advanced"
+Provides-Extra: pseudobulk
+Requires-Dist: pydeseq2>=0.4.0; extra == "pseudobulk"
+Provides-Extra: gene-features
+Requires-Dist: gtfparse>=1.3.0; extra == "gene-features"
+Provides-Extra: memento
+Requires-Dist: memento-de<0.3.0,>=0.1.0; extra == "memento"
+Provides-Extra: gsea
+Requires-Dist: gseapy>=1.1; extra == "gsea"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: pre-commit>=3.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# scATrans
+
+[![PyPI version](https://img.shields.io/pypi/v/scatrans.svg)](https://pypi.org/project/scatrans/)
+[![Python versions](https://img.shields.io/pypi/pyversions/scatrans.svg)](https://pypi.org/project/scatrans/)
+[![Documentation Status](https://readthedocs.org/projects/scatrans/badge/?version=latest)](https://scatrans.readthedocs.io/en/latest/?badge=latest)
+[![CI](https://github.com/leelieber2025/scATrans/actions/workflows/ci.yml/badge.svg)](https://github.com/leelieber2025/scATrans/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
+scATrans is a Python toolkit for single-cell differential analysis. It is
+primarily designed for datasets that contain spliced/unspliced (or
+mature/nascent) RNA layers. In this setting it computes a composite active
+transcription score that integrates differential expression with
+reference-based excess unspliced RNA to rank genes.
+
+It also supports conventional differential expression workflows (no
+velocity data required) using scanpy, PyDESeq2 pseudobulk, linear mixed
+models, or optional Memento. Functional enrichment (ORA, GSEA, GO, KEGG)
+uses bundled gene sets with consistent universe handling, and a set of
+visualization functions is provided.
+
+**📚 Full documentation, tutorials, and the complete API reference are on
+Read the Docs: https://scatrans.readthedocs.io**
+
+## Installation
+
+```bash
+pip install scatrans
+
+# Optional extras: advanced (scVelo) mode, pseudobulk DE (PyDESeq2), Memento, GSEA
+pip install "scatrans[advanced,gene_features,pseudobulk]" gseapy
+```
+
+See [Installation](https://scatrans.readthedocs.io/en/latest/installation.html)
+for extras, source installs, and logging setup.
+
+## Quickstart
+
+```python
+import scatrans as scat
+
+# One-liner pipeline: score → filter → GO enrichment
+result = scat.run_default_pipeline(
+    adata,
+    groupby="condition",
+    target_group="Disease",
+    reference_group="Control",
+    sample_col="sample",   # optional; auto-selects pseudobulk when >=3 replicates/group
+    organism="mouse",
+)
+print(result["candidates"].head())
+print(result["enrichment"].head())
+```
+
+See the [Quickstart](https://scatrans.readthedocs.io/en/latest/quickstart.html)
+for a complete end-to-end walkthrough, the
+[Tutorials](https://scatrans.readthedocs.io/en/latest/tutorials/index.html)
+for fully worked, real-data notebooks (with and without RNA-velocity
+layers), and the
+[User Guide](https://scatrans.readthedocs.io/en/latest/user_guide/index.html)
+for DE backends, enrichment, plotting, and advanced options.
+
+## Before reporting results in a paper
+
+`active_score` is a **composite heuristic rank**, not a p-value or FDR on
+its own. See
+[Statistical Guidance](https://scatrans.readthedocs.io/en/latest/statistical_guidance.html)
+for what each output column means, safe vs. unsafe uses, and a reporting
+checklist before you cite scATrans results in a manuscript or supplement.
+
+## License
+
+Software (Python source) is licensed under [Apache License 2.0](LICENSE).
+Bundled gene-set data (GO, KEGG) carries its own licensing terms — see
+[License](https://scatrans.readthedocs.io/en/latest/license.html) before
+commercial use.

scatrans-0.9.10.dev0/README.md

@@ -0,0 +1,75 @@
+# scATrans
+
+[![PyPI version](https://img.shields.io/pypi/v/scatrans.svg)](https://pypi.org/project/scatrans/)
+[![Python versions](https://img.shields.io/pypi/pyversions/scatrans.svg)](https://pypi.org/project/scatrans/)
+[![Documentation Status](https://readthedocs.org/projects/scatrans/badge/?version=latest)](https://scatrans.readthedocs.io/en/latest/?badge=latest)
+[![CI](https://github.com/leelieber2025/scATrans/actions/workflows/ci.yml/badge.svg)](https://github.com/leelieber2025/scATrans/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
+scATrans is a Python toolkit for single-cell differential analysis. It is
+primarily designed for datasets that contain spliced/unspliced (or
+mature/nascent) RNA layers. In this setting it computes a composite active
+transcription score that integrates differential expression with
+reference-based excess unspliced RNA to rank genes.
+
+It also supports conventional differential expression workflows (no
+velocity data required) using scanpy, PyDESeq2 pseudobulk, linear mixed
+models, or optional Memento. Functional enrichment (ORA, GSEA, GO, KEGG)
+uses bundled gene sets with consistent universe handling, and a set of
+visualization functions is provided.
+
+**📚 Full documentation, tutorials, and the complete API reference are on
+Read the Docs: https://scatrans.readthedocs.io**
+
+## Installation
+
+```bash
+pip install scatrans
+
+# Optional extras: advanced (scVelo) mode, pseudobulk DE (PyDESeq2), Memento, GSEA
+pip install "scatrans[advanced,gene_features,pseudobulk]" gseapy
+```
+
+See [Installation](https://scatrans.readthedocs.io/en/latest/installation.html)
+for extras, source installs, and logging setup.
+
+## Quickstart
+
+```python
+import scatrans as scat
+
+# One-liner pipeline: score → filter → GO enrichment
+result = scat.run_default_pipeline(
+    adata,
+    groupby="condition",
+    target_group="Disease",
+    reference_group="Control",
+    sample_col="sample",   # optional; auto-selects pseudobulk when >=3 replicates/group
+    organism="mouse",
+)
+print(result["candidates"].head())
+print(result["enrichment"].head())
+```
+
+See the [Quickstart](https://scatrans.readthedocs.io/en/latest/quickstart.html)
+for a complete end-to-end walkthrough, the
+[Tutorials](https://scatrans.readthedocs.io/en/latest/tutorials/index.html)
+for fully worked, real-data notebooks (with and without RNA-velocity
+layers), and the
+[User Guide](https://scatrans.readthedocs.io/en/latest/user_guide/index.html)
+for DE backends, enrichment, plotting, and advanced options.
+
+## Before reporting results in a paper
+
+`active_score` is a **composite heuristic rank**, not a p-value or FDR on
+its own. See
+[Statistical Guidance](https://scatrans.readthedocs.io/en/latest/statistical_guidance.html)
+for what each output column means, safe vs. unsafe uses, and a reporting
+checklist before you cite scATrans results in a manuscript or supplement.
+
+## License
+
+Software (Python source) is licensed under [Apache License 2.0](LICENSE).
+Bundled gene-set data (GO, KEGG) carries its own licensing terms — see
+[License](https://scatrans.readthedocs.io/en/latest/license.html) before
+commercial use.

scatrans-0.9.10.dev0/SECURITY.md

@@ -0,0 +1,34 @@
+# Security Policy
+
+## Supported Versions
+
+scATrans is under active development. Security fixes are applied to the
+latest released version on [PyPI](https://pypi.org/project/scatrans/); we do
+not maintain long-term security support for older releases.
+
+| Version | Supported |
+| ------- | --------- |
+| Latest release | :white_check_mark: |
+| Older releases | :x: |
+
+## Reporting a Vulnerability
+
+Please **do not** open a public GitHub issue for security vulnerabilities.
+
+Instead, use GitHub's private vulnerability reporting:
+[Report a vulnerability](https://github.com/leelieber2025/scATrans/security/advisories/new)
+(repository → **Security** tab → **Report a vulnerability**).
+
+Include a description of the issue, steps to reproduce, and the affected
+version. We will acknowledge reports and follow up with a timeline for a fix
+once the report is triaged.
+
+## Scope
+
+scATrans is a local single-cell analysis library (no network services, no
+telemetry, no remote code execution by design). Relevant concerns include:
+unsafe deserialization of untrusted input files, path traversal in file I/O
+helpers (e.g. `save_enrichment_report`, gene-feature generation), and
+dependency vulnerabilities in the packages it relies on (scanpy, anndata,
+PyDESeq2, gseapy, etc.) — for the latter, please also check whether the
+issue originates upstream.

scatrans-0.9.10.dev0/docs/_static/css/custom.css

@@ -0,0 +1,8 @@
+/* Minor spacing tweaks on top of sphinx_book_theme defaults. */
+.bd-main .bd-content {
+  max-width: 88rem;
+}
+
+.bd-article {
+  font-size: 15px;
+}