Skip to content

Commit 3e1f9b6

Browse files
author
Andrew Ramirez
committed
Replace autodoc with manual function documentation to fix rendering issues
1 parent 7270d8a commit 3e1f9b6

File tree

1 file changed

+220
-13
lines changed

1 file changed

+220
-13
lines changed

‎docs/api.rst‎

Lines changed: 220 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -7,48 +7,255 @@ Core Functions
77
Factorization
88
~~~~~~~~~~~~~
99

10-
.. autofunction:: RISE.factorization.pf2
10+
.. py:function:: pf2(X: anndata.AnnData, rank: int, random_state=1, doEmbedding: bool = True, tolerance=1e-9, max_iter: int = 500)
11+
:module: RISE.factorization
1112

12-
.. autofunction:: RISE.factorization.rise_pca_r2x
13+
Perform PARAFAC2 tensor decomposition on single-cell RNA-seq data.
14+
15+
This is the main function for running RISE analysis. It decomposes the
16+
multi-condition single-cell data into condition factors, eigen-state factors,
17+
and gene factors, revealing patterns across experimental conditions.
18+
19+
:param X: Preprocessed AnnData object containing single-cell RNA-seq data. Must have X.obs["condition_unique_idxs"] indicating which condition each cell belongs to (0-indexed).
20+
:type X: anndata.AnnData
21+
:param rank: Number of components to extract. Determines the complexity of the decomposition. Typically chosen based on variance explained and Factor Match Score analysis.
22+
:type rank: int
23+
:param random_state: Random seed for reproducibility of the decomposition.
24+
:type random_state: int, optional
25+
:param doEmbedding: If True, automatically computes PaCMAP embedding of cell projections and stores in X.obsm["X_pf2_PaCMAP"].
26+
:type doEmbedding: bool, optional
27+
:param tolerance: Convergence threshold for the optimization algorithm.
28+
:type tolerance: float, optional
29+
:param max_iter: Maximum number of iterations for the optimization algorithm.
30+
:type max_iter: int, optional
31+
:returns: The input AnnData object with added RISE decomposition results in X.uns["Pf2_weights"], X.uns["Pf2_A"], X.uns["Pf2_B"], X.varm["Pf2_C"], X.obsm["projections"], X.obsm["weighted_projections"], and X.obsm["X_pf2_PaCMAP"]
32+
:rtype: anndata.AnnData
1333

14-
.. autofunction:: RISE.factorization.correct_conditions
34+
.. py:function:: rise_pca_r2x(X: anndata.AnnData, ranks)
35+
:module: RISE.factorization
36+
37+
Compute variance explained (R²X) for RISE and PCA across different ranks.
38+
39+
This function calculates how much variance is explained by RISE decomposition
40+
and PCA at different numbers of components. Used to determine the optimal rank
41+
by comparing model complexity versus explanatory power.
42+
43+
:param X: Preprocessed AnnData object containing single-cell RNA-seq data. Must have X.obs["condition_unique_idxs"] for RISE decomposition.
44+
:type X: anndata.AnnData
45+
:param ranks: Array of rank values to test (e.g., [1, 5, 10, 15, 20, 25, 30]).
46+
:type ranks: array-like of int
47+
:returns: Tuple of (rise_r2x, pca_r2x) where each is an array of variance explained values
48+
:rtype: tuple of numpy.ndarray
49+
50+
.. py:function:: correct_conditions(X: anndata.AnnData)
51+
:module: RISE.factorization
52+
53+
Correct the condition factors by normalizing for overall read depth.
54+
55+
This function adjusts condition factors (stored in X.uns["Pf2_A"]) to account for
56+
differences in sequencing depth across conditions. It uses linear regression to
57+
model the relationship between total read counts and condition factor magnitudes.
58+
59+
:param X: AnnData object containing RISE decomposition results. Must have X.obs["condition_unique_idxs"] and X.uns["Pf2_A"].
60+
:type X: anndata.AnnData
61+
:returns: Corrected condition factors normalized by sequencing depth
62+
:rtype: numpy.ndarray
1563

1664
Preprocessing
1765
~~~~~~~~~~~~~
1866

19-
.. autofunction:: parafac2.normalize.prepare_dataset
67+
.. py:function:: prepare_dataset(X: anndata.AnnData, condition_name: str, geneThreshold: float, deviance: bool = False)
68+
:module: parafac2.normalize
69+
70+
Preprocess single-cell RNA-seq data for RISE analysis.
71+
72+
This function performs gene filtering, normalization, scaling, and log transformation.
73+
It also creates the condition_unique_idxs column required for RISE decomposition.
74+
75+
:param X: AnnData object containing raw count data in sparse matrix format
76+
:type X: anndata.AnnData
77+
:param condition_name: Name of the column in X.obs that specifies experimental conditions for each cell
78+
:type condition_name: str
79+
:param geneThreshold: Minimum mean expression threshold for gene filtering
80+
:type geneThreshold: float
81+
:param deviance: If True, applies deviance transformation instead of log normalization
82+
:type deviance: bool, optional
83+
:returns: Preprocessed AnnData object with condition_unique_idxs and gene means
84+
:rtype: anndata.AnnData
2085

2186
Visualization Functions
2287
-----------------------
2388

2489
General Plotting
2590
~~~~~~~~~~~~~~~~
2691

27-
.. autofunction:: RISE.figures.commonFuncs.plotGeneral.plot_r2x
92+
.. py:function:: plot_r2x(data: anndata.AnnData, rank_vec, ax: matplotlib.axes.Axes)
93+
:module: RISE.figures.commonFuncs.plotGeneral
94+
95+
Plot variance explained (R²X) for RISE and PCA across different ranks.
96+
97+
This visualization helps determine the optimal number of components by showing
98+
how variance explained increases with rank. The elbow point where the curve
99+
flattens indicates a good balance between model complexity and explanatory power.
100+
101+
:param data: Preprocessed AnnData object containing single-cell RNA-seq data.
102+
:type data: anndata.AnnData
103+
:param rank_vec: Array of rank values to test (e.g., [1, 5, 10, 15, 20, 25, 30]).
104+
:type rank_vec: array-like of int
105+
:param ax: Matplotlib axes object to plot on.
106+
:type ax: matplotlib.axes.Axes
28107

29108
Factor Plotting
30109
~~~~~~~~~~~~~~~
31110

32-
.. autofunction:: RISE.figures.commonFuncs.plotFactors.plot_condition_factors
111+
.. py:function:: plot_condition_factors(data: anndata.AnnData, ax: matplotlib.axes.Axes, cond: str = 'Condition', log_transform: bool = True, cond_group_labels: pandas.Series = None, ThomsonNorm=False, color_key=None, group_cond=False)
112+
:module: RISE.figures.commonFuncs.plotFactors
113+
114+
Plot condition factors as a heatmap showing how conditions contribute to components.
115+
116+
This visualization shows how each experimental condition (rows) contributes to each RISE component (columns). High values indicate strong association between a condition and a component's pattern.
117+
118+
:param data: AnnData object with RISE decomposition results. Must contain data.uns["Pf2_A"] and data.obs[cond].
119+
:type data: anndata.AnnData
120+
:param ax: Matplotlib axes object to plot on.
121+
:type ax: matplotlib.axes.Axes
122+
:param cond: Name of column in data.obs containing condition labels.
123+
:type cond: str, optional
124+
:param log_transform: If True, applies log10 transformation to condition factors before plotting.
125+
:type log_transform: bool, optional
126+
:param cond_group_labels: Series mapping conditions to group labels for colored row annotations.
127+
:type cond_group_labels: pandas.Series, optional
128+
:param ThomsonNorm: If True, normalizes factors using only control conditions.
129+
:type ThomsonNorm: bool, optional
130+
:param color_key: Custom colors for condition group labels.
131+
:type color_key: list, optional
132+
:param group_cond: If True and cond_group_labels provided, sorts conditions by group.
133+
:type group_cond: bool, optional
134+
135+
.. py:function:: plot_eigenstate_factors(data: anndata.AnnData, ax: matplotlib.axes.Axes)
136+
:module: RISE.figures.commonFuncs.plotFactors
137+
138+
Plot eigen-state factors as a heatmap showing cell state patterns.
139+
140+
Eigen-state factors represent the underlying cell state patterns across components. Each row represents an eigen-state and each column represents a component.
141+
142+
:param data: AnnData object with RISE decomposition results. Must contain data.uns["Pf2_B"].
143+
:type data: anndata.AnnData
144+
:param ax: Matplotlib axes object to plot on.
145+
:type ax: matplotlib.axes.Axes
33146

34-
.. autofunction:: RISE.figures.commonFuncs.plotFactors.plot_eigenstate_factors
147+
.. py:function:: plot_gene_factors(data: anndata.AnnData, ax: matplotlib.axes.Axes, weight=0.08, trim=True)
148+
:module: RISE.figures.commonFuncs.plotFactors
35149

36-
.. autofunction:: RISE.figures.commonFuncs.plotFactors.plot_gene_factors
150+
Plot gene factors as a heatmap showing which genes contribute to each component.
151+
152+
This visualization reveals coordinated gene modules by showing which genes (rows) are highly weighted in each component (columns).
153+
154+
:param data: AnnData object with RISE decomposition results. Must contain data.varm["Pf2_C"].
155+
:type data: anndata.AnnData
156+
:param ax: Matplotlib axes object to plot on.
157+
:type ax: matplotlib.axes.Axes
158+
:param weight: Minimum absolute weight threshold for including genes.
159+
:type weight: float, optional
160+
:param trim: If True, filters genes based on the weight parameter.
161+
:type trim: bool, optional
37162

38163
PaCMAP Visualization
39164
~~~~~~~~~~~~~~~~~~~~
40165

41-
.. autofunction:: RISE.figures.commonFuncs.plotPaCMAP.plot_labels_pacmap
166+
.. py:function:: plot_labels_pacmap(X: anndata.AnnData, labelType: str, ax: matplotlib.axes.Axes, condition=None, cmap: str = 'tab20', color_key=None)
167+
:module: RISE.figures.commonFuncs.plotPaCMAP
42168

43-
.. autofunction:: RISE.figures.commonFuncs.plotPaCMAP.plot_gene_pacmap
169+
Plot PaCMAP embedding colored by categorical labels (cell type or condition).
170+
171+
This visualization shows the overall structure of the cell embedding, revealing how cells cluster by cell type or experimental condition.
172+
173+
:param X: AnnData object with RISE decomposition results. Must contain X.obsm["X_pf2_PaCMAP"] and X.obs[labelType].
174+
:type X: anndata.AnnData
175+
:param labelType: Name of column in X.obs containing categorical labels to color by.
176+
:type labelType: str
177+
:param ax: Matplotlib axes object to plot on.
178+
:type ax: matplotlib.axes.Axes
179+
:param condition: If provided, only highlights cells from these specific conditions.
180+
:type condition: list of str, optional
181+
:param cmap: Matplotlib colormap name for coloring categories.
182+
:type cmap: str, optional
183+
:param color_key: Custom list of colors for categories.
184+
:type color_key: list, optional
44185

45-
.. autofunction:: RISE.figures.commonFuncs.plotPaCMAP.plot_wp_pacmap
186+
.. py:function:: plot_gene_pacmap(gene: str, X: anndata.AnnData, ax: matplotlib.axes.Axes, clip_outliers=0.9995)
187+
:module: RISE.figures.commonFuncs.plotPaCMAP
188+
189+
Plot PaCMAP embedding colored by gene expression levels.
190+
191+
This visualization overlays gene expression onto the PaCMAP embedding of cells, revealing which cell populations express specific genes.
192+
193+
:param gene: Name of gene to visualize. Must be present in X.var_names.
194+
:type gene: str
195+
:param X: AnnData object with RISE decomposition results. Must contain X.obsm["X_pf2_PaCMAP"].
196+
:type X: anndata.AnnData
197+
:param ax: Matplotlib axes object to plot on.
198+
:type ax: matplotlib.axes.Axes
199+
:param clip_outliers: Quantile threshold for clipping extreme expression values.
200+
:type clip_outliers: float, optional
201+
202+
.. py:function:: plot_wp_pacmap(X: anndata.AnnData, cmp: int, ax: matplotlib.axes.Axes, cbarMax: float = 1.0)
203+
:module: RISE.figures.commonFuncs.plotPaCMAP
204+
205+
Plot PaCMAP embedding colored by weighted projections for a component.
206+
207+
This visualization shows which cells contribute most strongly to a specific component by coloring them according to their weighted projections.
208+
209+
:param X: AnnData object with RISE decomposition results. Must contain X.obsm["X_pf2_PaCMAP"] and X.obsm["weighted_projections"].
210+
:type X: anndata.AnnData
211+
:param cmp: Component number to visualize (1-indexed).
212+
:type cmp: int
213+
:param ax: Matplotlib axes object to plot on.
214+
:type ax: matplotlib.axes.Axes
215+
:param cbarMax: Maximum value for the color scale.
216+
:type cbarMax: float, optional
46217

47218
Factor Stability
48219
~~~~~~~~~~~~~~~~
49220

50-
.. autofunction:: RISE.figures.figureS4.plot_fms_diff_ranks
221+
.. py:function:: plot_fms_diff_ranks(X: anndata.AnnData, ax: matplotlib.axes.Axes, ranksList: list[int], runs: int)
222+
:module: RISE.figures.figureS4
223+
224+
Plot Factor Match Score (FMS) across different ranks to assess stability.
225+
226+
FMS measures the reproducibility of PARAFAC2 decomposition results across multiple runs. Values above ~0.6 indicate stable, reproducible components.
227+
228+
:param X: Preprocessed AnnData object containing single-cell RNA-seq data.
229+
:type X: anndata.AnnData
230+
:param ax: Matplotlib axes object to plot on.
231+
:type ax: matplotlib.axes.Axes
232+
:param ranksList: List of rank values to test (e.g., [1, 5, 10, 15, 20, 25, 30]).
233+
:type ranksList: list of int
234+
:param runs: Number of independent runs per rank to use for FMS calculation.
235+
:type runs: int
236+
237+
.. note::
238+
FMS > 0.9: Highly stable decomposition
239+
240+
FMS > 0.6: Acceptably stable decomposition
241+
242+
FMS < 0.6: Unstable, consider lower rank or more data
243+
244+
.. py:function:: calculateFMS(A: anndata.AnnData, B: anndata.AnnData)
245+
:module: RISE.figures.figureS4
246+
247+
Calculate Factor Match Score (FMS) between two RISE decompositions.
248+
249+
Factor Match Score measures the similarity between two tensor decompositions by comparing their factor matrices. Values range from 0 (no similarity) to 1 (identical factors).
250+
251+
:param A: First AnnData object with RISE decomposition results.
252+
:type A: anndata.AnnData
253+
:param B: Second AnnData object with RISE decomposition results.
254+
:type B: anndata.AnnData
255+
:returns: Factor Match Score between 0 and 1. Higher values indicate more similar decompositions.
256+
:rtype: float
51257

52-
.. autofunction:: RISE.figures.figureS4.calculateFMS
258+
.. note::
259+
This function uses tlviz.factor_tools.factor_match_score with weights consideration disabled and skipping the condition mode for stability assessment.
53260

54261

0 commit comments

Comments
 (0)