Skip to content

High-Level API

Use these functions when you want to run a complete workflow and receive the differential regulation table directly.

compare_networks 

compare_networks(
    x_data: ExpressionData,
    y_data: ExpressionData,
    x_label: str = "X",
    y_label: str = "Y",
    layer: LayerName = None,
    backend: Backend = "serial",
    n_jobs: int = 1,
    random_state: int = 42,
    qc_kws: Optional[Kwargs] = None,
    network_kws: Optional[Kwargs] = None,
    td_kws: Optional[Kwargs] = None,
    ma_kws: Optional[Kwargs] = None,
    dr_kws: Optional[Kwargs] = None,
) -> pd.DataFrame

Run the full two-sample scTenifoldNet workflow.

Builds PC networks for x_data and y_data, performs tensor decomposition and manifold alignment, then returns the differential regulation table.

Parameters:

Name Type Description Default
x_data ExpressionData

Genes-by-cells expression matrices. Each may be a pandas.DataFrame or an AnnData-like object (X/var_names/obs_names); the latter is converted via :func:anndata_to_dataframe.

 required
y_data ExpressionData

Genes-by-cells expression matrices. Each may be a pandas.DataFrame or an AnnData-like object (X/var_names/obs_names); the latter is converted via :func:anndata_to_dataframe.

 required
x_label str

Labels used internally and in the output to distinguish the two conditions.

 'X'
y_label str

Labels used internally and in the output to distinguish the two conditions.

 'X'
layer LayerName

Optional AnnData layer name. If None, adata.X is used.

 None
backend Backend

Parallel backend for PC network construction. One of "serial", "joblib-loky", "joblib-threading", "ray".

 'serial'
n_jobs int

Worker count for the chosen backend. -1 means all available cores. Ignored when backend="serial".

 1
random_state int

Seed propagated to the randomized SVD inside network construction.

 42
qc_kws Optional[Kwargs]

Per-step keyword overrides forwarded to QC, network construction, tensor decomposition, manifold alignment and differential regulation, respectively. backend/n_jobs/random_state already present in network_kws take precedence over the top-level arguments.

 None
network_kws Optional[Kwargs]

Per-step keyword overrides forwarded to QC, network construction, tensor decomposition, manifold alignment and differential regulation, respectively. backend/n_jobs/random_state already present in network_kws take precedence over the top-level arguments.

 None
td_kws Optional[Kwargs]

Per-step keyword overrides forwarded to QC, network construction, tensor decomposition, manifold alignment and differential regulation, respectively. backend/n_jobs/random_state already present in network_kws take precedence over the top-level arguments.

 None
ma_kws Optional[Kwargs]

Per-step keyword overrides forwarded to QC, network construction, tensor decomposition, manifold alignment and differential regulation, respectively. backend/n_jobs/random_state already present in network_kws take precedence over the top-level arguments.

 None
dr_kws Optional[Kwargs]

Per-step keyword overrides forwarded to QC, network construction, tensor decomposition, manifold alignment and differential regulation, respectively. backend/n_jobs/random_state already present in network_kws take precedence over the top-level arguments.

 None

Returns:

Type Description
DataFrame

Differential regulation table with one row per shared gene.
Source code in scTenifold/core/_api.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
def compare_networks(x_data: ExpressionData,
                     y_data: ExpressionData,
                     x_label: str = "X",
                     y_label: str = "Y",
                     layer: LayerName = None,
                     backend: Backend = "serial",
                     n_jobs: int = 1,
                     random_state: int = 42,
                     qc_kws: Optional[Kwargs] = None,
                     network_kws: Optional[Kwargs] = None,
                     td_kws: Optional[Kwargs] = None,
                     ma_kws: Optional[Kwargs] = None,
                     dr_kws: Optional[Kwargs] = None) -> pd.DataFrame:
    """Run the full two-sample scTenifoldNet workflow.

    Builds PC networks for ``x_data`` and ``y_data``, performs tensor
    decomposition and manifold alignment, then returns the differential
    regulation table.

    Parameters
    ----------
    x_data, y_data
        Genes-by-cells expression matrices. Each may be a ``pandas.DataFrame``
        or an AnnData-like object (``X``/``var_names``/``obs_names``); the
        latter is converted via :func:`anndata_to_dataframe`.
    x_label, y_label
        Labels used internally and in the output to distinguish the two
        conditions.
    layer
        Optional AnnData layer name. If ``None``, ``adata.X`` is used.
    backend
        Parallel backend for PC network construction. One of
        ``"serial"``, ``"joblib-loky"``, ``"joblib-threading"``, ``"ray"``.
    n_jobs
        Worker count for the chosen backend. ``-1`` means all available
        cores. Ignored when ``backend="serial"``.
    random_state
        Seed propagated to the randomized SVD inside network construction.
    qc_kws, network_kws, td_kws, ma_kws, dr_kws
        Per-step keyword overrides forwarded to QC, network construction,
        tensor decomposition, manifold alignment and differential
        regulation, respectively. ``backend``/``n_jobs``/``random_state``
        already present in ``network_kws`` take precedence over the
        top-level arguments.

    Returns
    -------
    pandas.DataFrame
        Differential regulation table with one row per shared gene.
    """
    sc = scTenifoldNet(
        anndata_to_dataframe(x_data, layer=layer),
        anndata_to_dataframe(y_data, layer=layer),
        x_label=x_label,
        y_label=y_label,
        qc_kws=qc_kws,
        nc_kws=_network_kws(backend, n_jobs, random_state, network_kws),
        td_kws=td_kws,
        ma_kws=ma_kws,
        dr_kws=dr_kws,
    )
    return sc.build()

virtual_knockout 

virtual_knockout(
    data: ExpressionData,
    ko_genes: Optional[Union[str, Iterable[str]]] = None,
    layer: LayerName = None,
    backend: Backend = "serial",
    n_jobs: int = 1,
    random_state: int = 42,
    strict_lambda: float = 0,
    ko_method: KOMethod = "default",
    qc_kws: Optional[Kwargs] = None,
    network_kws: Optional[Kwargs] = None,
    td_kws: Optional[Kwargs] = None,
    ma_kws: Optional[Kwargs] = None,
    dr_kws: Optional[Kwargs] = None,
    ko_kws: Optional[Kwargs] = None,
) -> pd.DataFrame

Run the full scTenifoldKnk virtual-knockout workflow.

Constructs a wild-type PC network from data, simulates a knockout of ko_genes, performs manifold alignment between WT and KO tensors and returns the differential regulation table.

Parameters:

Name Type Description Default
data ExpressionData

Genes-by-cells expression matrix (pandas.DataFrame or AnnData-like).

 required
ko_genes Optional[Union[str, Iterable[str]]]

Gene name or iterable of gene names to knock out. None and an empty iterable both mean "no genes", which is rarely useful.

 None
layer LayerName

Optional AnnData layer name. If None, adata.X is used.

 None
backend Backend

Parallel backend for PC network construction. One of "serial", "joblib-loky", "joblib-threading", "ray".

 'serial'
n_jobs int

Worker count for the chosen backend. -1 means all available cores.

 1
random_state int

Seed propagated to the randomized SVD inside network construction.

 42
strict_lambda float

Strength of the directional pruning applied by :func:strict_direction to the decomposed WT tensor.

 0
ko_method KOMethod

How the KO tensor is produced:

  • "default" — zero out the rows of the WT tensor for ko_genes.
  • "propagation" — rebuild PC networks with the targeted genes masked using :func:reconstruct_pcnets, then re-decompose.
 'default'
qc_kws Optional[Kwargs]

Per-step keyword overrides forwarded to QC, network construction, tensor decomposition, manifold alignment, differential regulation, and the KO step. backend/n_jobs/random_state already present in network_kws take precedence over the top-level arguments.

 None
network_kws Optional[Kwargs]

Per-step keyword overrides forwarded to QC, network construction, tensor decomposition, manifold alignment, differential regulation, and the KO step. backend/n_jobs/random_state already present in network_kws take precedence over the top-level arguments.

 None
td_kws Optional[Kwargs]

Per-step keyword overrides forwarded to QC, network construction, tensor decomposition, manifold alignment, differential regulation, and the KO step. backend/n_jobs/random_state already present in network_kws take precedence over the top-level arguments.

 None
ma_kws Optional[Kwargs]

Per-step keyword overrides forwarded to QC, network construction, tensor decomposition, manifold alignment, differential regulation, and the KO step. backend/n_jobs/random_state already present in network_kws take precedence over the top-level arguments.

 None
dr_kws Optional[Kwargs]

Per-step keyword overrides forwarded to QC, network construction, tensor decomposition, manifold alignment, differential regulation, and the KO step. backend/n_jobs/random_state already present in network_kws take precedence over the top-level arguments.

 None
ko_kws Optional[Kwargs]

Per-step keyword overrides forwarded to QC, network construction, tensor decomposition, manifold alignment, differential regulation, and the KO step. backend/n_jobs/random_state already present in network_kws take precedence over the top-level arguments.

 None

Returns:

Type Description
DataFrame

Differential regulation table comparing the WT and KO tensors.
Source code in scTenifold/core/_api.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
def virtual_knockout(data: ExpressionData,
                     ko_genes: Optional[Union[str, Iterable[str]]] = None,
                     layer: LayerName = None,
                     backend: Backend = "serial",
                     n_jobs: int = 1,
                     random_state: int = 42,
                     strict_lambda: float = 0,
                     ko_method: KOMethod = "default",
                     qc_kws: Optional[Kwargs] = None,
                     network_kws: Optional[Kwargs] = None,
                     td_kws: Optional[Kwargs] = None,
                     ma_kws: Optional[Kwargs] = None,
                     dr_kws: Optional[Kwargs] = None,
                     ko_kws: Optional[Kwargs] = None) -> pd.DataFrame:
    """Run the full scTenifoldKnk virtual-knockout workflow.

    Constructs a wild-type PC network from ``data``, simulates a knockout
    of ``ko_genes``, performs manifold alignment between WT and KO tensors
    and returns the differential regulation table.

    Parameters
    ----------
    data
        Genes-by-cells expression matrix (``pandas.DataFrame`` or
        AnnData-like).
    ko_genes
        Gene name or iterable of gene names to knock out. ``None`` and an
        empty iterable both mean "no genes", which is rarely useful.
    layer
        Optional AnnData layer name. If ``None``, ``adata.X`` is used.
    backend
        Parallel backend for PC network construction. One of
        ``"serial"``, ``"joblib-loky"``, ``"joblib-threading"``, ``"ray"``.
    n_jobs
        Worker count for the chosen backend. ``-1`` means all available
        cores.
    random_state
        Seed propagated to the randomized SVD inside network construction.
    strict_lambda
        Strength of the directional pruning applied by
        :func:`strict_direction` to the decomposed WT tensor.
    ko_method
        How the KO tensor is produced:

        - ``"default"`` — zero out the rows of the WT tensor for
          ``ko_genes``.
        - ``"propagation"`` — rebuild PC networks with the targeted genes
          masked using :func:`reconstruct_pcnets`, then re-decompose.
    qc_kws, network_kws, td_kws, ma_kws, dr_kws, ko_kws
        Per-step keyword overrides forwarded to QC, network construction,
        tensor decomposition, manifold alignment, differential regulation,
        and the KO step. ``backend``/``n_jobs``/``random_state`` already
        present in ``network_kws`` take precedence over the top-level
        arguments.

    Returns
    -------
    pandas.DataFrame
        Differential regulation table comparing the WT and KO tensors.
    """
    sc = scTenifoldKnk(
        anndata_to_dataframe(data, layer=layer),
        strict_lambda=strict_lambda,
        ko_method=ko_method,
        ko_genes=ko_genes,
        qc_kws=qc_kws,
        nc_kws=_network_kws(backend, n_jobs, random_state, network_kws),
        td_kws=td_kws,
        ma_kws=ma_kws,
        dr_kws=dr_kws,
        ko_kws=ko_kws,
    )
    return sc.build()