scCS.bifurcation
================

.. py:module:: scCS.bifurcation

.. autoapi-nested-parse::

   bifurcation.py — Cluster-level fate map construction for scCS.

   In scCS, the bifurcation point is explicitly defined by the user as a
   single cluster (e.g., leiden cluster '17').  There is no automatic
   fate detection — the user supplies:

       root  : the progenitor/root cluster label
       branches  : list of terminal fate cluster labels

   This module builds a standardized FateMap from those labels, computing
   centroids in the scCS star embedding space (X_sccs) and collecting
   per-fate cell indices.

   The FateMap is the single source of truth consumed by SingleScorer.score().



Classes
-------

.. autoapisummary::

   scCS.bifurcation.FateMap


Functions
---------

.. autoapisummary::

   scCS.bifurcation.build_fate_map


Module Contents
---------------

.. py:class:: FateMap

   Standardized description of k cell fates for commitment scoring.

   .. attribute:: root

      Label of the progenitor/root cluster supplied by the user.

      :type: str

   .. attribute:: fate_names

      Human-readable labels for each terminal fate (length k).

      :type: list of str

   .. attribute:: fate_centroids

      Mean 2D position of each fate's cells in the scCS embedding.

      :type: np.ndarray, shape (k, 2)

   .. attribute:: root_centroid

      Mean 2D position of the bifurcation cluster cells.
      In the scCS star embedding this is always near (0, 0).

      :type: np.ndarray, shape (2,)

   .. attribute:: root_cells

      Indices of bifurcation cluster cells in adata.

      :type: np.ndarray of int

   .. attribute:: fate_cell_indices

      Per-fate arrays of cell indices.

      :type: list of np.ndarray

   .. attribute:: arm_angles_deg

      Angle (degrees) of each fate's radial arm in the star embedding.

      :type: np.ndarray, shape (k,)

   .. attribute:: obs_key

      The obs column used for cluster labels.

      :type: str

   .. attribute:: k

      Number of fates (read-only property).

      :type: int


   .. py:attribute:: root
      :type:  str


   .. py:attribute:: fate_names
      :type:  List[str]


   .. py:attribute:: fate_centroids
      :type:  numpy.ndarray


   .. py:attribute:: root_centroid
      :type:  numpy.ndarray


   .. py:attribute:: root_cells
      :type:  numpy.ndarray


   .. py:attribute:: fate_cell_indices
      :type:  List[numpy.ndarray]


   .. py:attribute:: arm_angles_deg
      :type:  numpy.ndarray


   .. py:attribute:: obs_key
      :type:  str


   .. py:property:: k
      :type: int



   .. py:method:: summary() -> str


.. py:function:: build_fate_map(adata, root: str, branches: List[str], obs_key: str = 'leiden', verbose: bool = True) -> FateMap

   Build a FateMap from user-supplied cluster labels.

   This is the only fate-detection strategy in scCS.  The user explicitly
   names the bifurcation cluster and all terminal fate clusters.

   :param adata: Must have X_sccs in obsm (built by build_star_embedding).
   :type adata: AnnData
   :param root: Label of the progenitor cluster in adata.obs[obs_key].
                Example: '17'  (leiden cluster 17)
   :type root: str
   :param branches: Labels of the k terminal fate clusters.
                    Example: ['Monocyte', 'DC', 'Neutrophil']
   :type branches: list of str
   :param obs_key: Column in adata.obs with cluster labels.
   :type obs_key: str
   :param verbose:
   :type verbose: bool

   :rtype: FateMap