API Reference
=============

This page documents all public classes and functions in scCS.
Full source-linked documentation is also available in the **autoapi** section
in the sidebar.

SingleScorer
------------

Single-condition analysis. Wraps an AnnData object and exposes all scoring
and plotting methods.

.. autoclass:: scCS.SingleScorer
   :members:
   :undoc-members:
   :show-inheritance:

PairScorer
----------

Pairwise comparison (exactly 2 conditions). Builds a shared star embedding
on pooled data, then scores each condition separately. Provides statistical
comparison, mixed-effects modeling, and trajectory shift analysis.

.. autoclass:: scCS.PairScorer
   :members:
   :undoc-members:
   :show-inheritance:

MultiScorer
-----------

Multi-condition comparison (3+ conditions). Same shared-embedding approach
as PairScorer, plus tiered statistical testing: omnibus tests followed by
post-hoc pairwise comparisons, all-pairs delta-CS, and mixed-model contrasts.

.. autoclass:: scCS.MultiScorer
   :members:
   :undoc-members:
   :show-inheritance:

CommitmentScoreResult
---------------------

Dataclass returned by ``scorer.score()``. Contains all computed scores,
matrices, and metadata.

.. autoclass:: scCS.CommitmentScoreResult
   :members:
   :undoc-members:
   :show-inheritance:

FateMap
-------

Stores the fate topology: which cells belong to which arm, centroids,
and arm angles.

.. autoclass:: scCS.FateMap
   :members:
   :undoc-members:
   :show-inheritance:

Plotting Functions
------------------

All plotting functions accept a ``color_map`` dict (fate name → hex color)
to preserve your original scanpy/Seurat cluster colors.

Single-condition plots:

.. autofunction:: scCS.plot_star_embedding
.. autofunction:: scCS.plot_star_panels
.. autofunction:: scCS.plot_commitment_bar
.. autofunction:: scCS.plot_expression_trends
.. autofunction:: scCS.plot_rose
.. autofunction:: scCS.plot_pairwise_cs
.. autofunction:: scCS.plot_commitment_heatmap
.. autofunction:: scCS.plot_subset_comparison
.. autofunction:: scCS.plot_nn_entropy_elbow

Multi-condition plots (PairScorer + MultiScorer):

.. autofunction:: scCS.plot_rose_grid
.. autofunction:: scCS.plot_delta_cs_heatmap
.. autofunction:: scCS.plot_compare_conditions_bar
.. autofunction:: scCS.plot_commitment_vector_radar

MultiScorer-specific plots:

.. autofunction:: scCS.plot_omnibus_summary
.. autofunction:: scCS.plot_posthoc_heatmap
.. autofunction:: scCS.plot_pairwise_delta_grid

Embedding
---------

.. autofunction:: scCS.build_star_embedding
.. autofunction:: scCS.compute_local_pseudotime
.. autofunction:: scCS.scale_metric_01

Fate Detection
--------------

.. autofunction:: scCS.build_fate_map

Driver Genes
------------

Three complementary approaches to identify fate-driving genes:

.. autofunction:: scCS.get_velocity_drivers
.. autofunction:: scCS.get_deg_drivers
.. autofunction:: scCS.get_velocity_fate_drivers

Pathway Enrichment
------------------

.. autofunction:: scCS.run_enrichment_per_fate
.. autofunction:: scCS.export_enrichment_tables

Core Math — Entropy
-------------------

.. autofunction:: scCS.compute_population_entropy
.. autofunction:: scCS.compute_mean_cell_entropy
.. autofunction:: scCS.compute_per_fate_cell_entropy
.. autofunction:: scCS.compute_nn_cell_entropy

Core Math — Scores
------------------

.. autofunction:: scCS.compute_unCS
.. autofunction:: scCS.compute_nCS
.. autofunction:: scCS.compute_commitment_vector
.. autofunction:: scCS.compute_pairwise_cs_matrix
.. autofunction:: scCS.compute_cell_scores
.. autofunction:: scCS.compute_magnitudes
.. autofunction:: scCS.compute_angles
.. autofunction:: scCS.bin_angles
.. autofunction:: scCS.equal_sectors
.. autofunction:: scCS.centroid_sectors
.. autofunction:: scCS.compute_sector_magnitudes
.. autofunction:: scCS.bootstrap_cs