### Hello World Example

Source: https://sctenifoldpy.readthedocs.io/en/latest/index.html

A basic example demonstrating the usage of the compare_networks function.

```python
from scTenifold import compare_networks
from scTenifold.data import get_test_df

x = get_test_df(n_cells=200, n_genes=300, random_state=0)
y = get_test_df(n_cells=200, n_genes=300, random_state=1)

result = compare_networks(
    x, y,
    qc_kws={"min_lib_size": 1},
    network_kws={"n_nets": 3, "n_samp_cells": 100},
)
print(result.head())

```

--------------------------------

### Install scTenifoldpy using uv

Source: https://sctenifoldpy.readthedocs.io/en/latest/index.html

Installation instructions for scTenifoldpy using uv.

```bash
uv venv
uv pip install scTenifoldpy

```

--------------------------------

### Build Docs with uv

Source: https://sctenifoldpy.readthedocs.io/en/latest/installation.html

Builds the documentation using uv.

```bash
uv run mkdocs build --strict

```

--------------------------------

### Optional Extras Install with uv

Source: https://sctenifoldpy.readthedocs.io/en/latest/installation.html

Installs scTenifoldpy with the 'scanpy' extra using uv.

```bash
uv pip install "scTenifoldpy[scanpy]"

```

--------------------------------

### Run Test Suite with uv

Source: https://sctenifoldpy.readthedocs.io/en/latest/installation.html

Runs the test suite using uv.

```bash
uv run pytest

```

--------------------------------

### Development Install with uv

Source: https://sctenifoldpy.readthedocs.io/en/latest/installation.html

Installs scTenifoldpy in development mode using uv, including test, dev, and docs groups.

```bash
git clone https://github.com/qwerty239qwe/scTenifoldpy
cd scTenifoldpy
uv sync --group test --group dev --group docs

```

--------------------------------

### Optional Extras Install with pip

Source: https://sctenifoldpy.readthedocs.io/en/latest/installation.html

Installs scTenifoldpy with the 'scanpy' extra using pip.

```bash
pip install "scTenifoldpy[scanpy]"

```

--------------------------------

### Build Docker Image with Optional Extras

Source: https://sctenifoldpy.readthedocs.io/en/latest/installation.html

Builds a Docker image with specific optional extras included.

```bash
docker build --build-arg EXTRAS=scanpy -t sctenifoldpy:scanpy .
docker build --build-arg EXTRAS=parallel-ray -t sctenifoldpy:ray .

```

--------------------------------

### Build Default Docker Image

Source: https://sctenifoldpy.readthedocs.io/en/latest/installation.html

Builds the default Docker runtime image for scTenifoldpy.

```bash
docker build -t sctenifoldpy .

```

--------------------------------

### Install scTenifoldpy using pip

Source: https://sctenifoldpy.readthedocs.io/en/latest/index.html

Alternative installation instructions for scTenifoldpy using pip.

```bash
pip install scTenifoldpy

```

--------------------------------

### Example Configuration for scTenifoldNet

Source: https://sctenifoldpy.readthedocs.io/en/latest/cli.html

An example of a YAML configuration file for scTenifoldNet, detailing parameters for data paths, quality control, network construction, tensor decomposition, matrix approximation, and dimensionality reduction.

```yaml
# net_config.yml (scTenifoldNet)
x_data_path: ./data/ctrl/        # 10x folder OR a .csv/.tsv file
y_data_path: ./data/cond/
x_label: ctrl
y_label: cond

qc_kws:
  min_lib_size: 1000
  remove_outlier_cells: true
  min_percent: 0.05
  max_mito_ratio: 0.1
  min_exp_avg: 0
  min_exp_sum: 0

nc_kws:
  n_nets: 10
  n_samp_cells: 500
  n_comp: 3
  scale_scores: true
  symmetric: false
  q: 0.95
  random_state: 42
  backend: serial
  n_jobs: 1

td_kws:
  method: parafac
  n_decimal: 1
  K: 5
  tol: 1.0e-06
  max_iter: 1000
  random_state: 42

ma_kws:
  d: 30
  tol: 1.0e-08

dr_kws:
  sorted_by: p-value
  ascending: true


```

--------------------------------

### Development Install with pip

Source: https://sctenifoldpy.readthedocs.io/en/latest/installation.html

Installs scTenifoldpy in development mode using pip, including common development dependencies.

```bash
pip install -e ".[scanpy,parallel-ray,docs]"
pip install pytest pytest-cov ruff build

```

--------------------------------

### Step-Wise: `scTenifoldNet` / `scTenifoldKnk`

Source: https://sctenifoldpy.readthedocs.io/en/latest/quickstart.html

This code snippet demonstrates the step-wise usage of the `scTenifoldNet` class API for building and running a pipeline. It initializes the class, runs through several steps ('qc', 'nc', 'td', 'ma', 'dr'), prints shapes and lengths of intermediate results, and saves the model.

```python
from scTenifold import scTenifoldNet

model = scTenifoldNet(
    x, y,
    x_label="ctrl", y_label="cond",
    qc_kws={"min_lib_size": 1},
    nc_kws={"n_nets": 3, "n_samp_cells": 100, "backend": "serial"},
)

model.run_step("qc")
model.run_step("nc")
model.run_step("td")
model.run_step("ma")
model.run_step("dr")

print(model.QC_dict["ctrl"].shape)         # genes x cells after QC
print(len(model.network_dict["ctrl"]))
print(model.tensor_dict["ctrl"].shape)     # genes x genes
print(model.manifold.shape)                # (2 * shared_genes) x d
print(model.d_regulation.head())

model.save("./run-ctrl-vs-cond")

```

--------------------------------

### AnnData Input Examples

Source: https://sctenifoldpy.readthedocs.io/en/latest/anndata.html

Examples demonstrating the use of AnnData objects with scTenifoldpy's compare_networks and virtual_knockout functions.

```python
from scTenifold import compare_networks, virtual_knockout

# compare_networks with two AnnData objects
result = compare_networks(adata_x, adata_y, layer="counts")

# virtual_knockout reads adata.X if layer is omitted
result = virtual_knockout(adata, ko_genes=["GeneA"])

```

--------------------------------

### Run CLI from Docker Container

Source: https://sctenifoldpy.readthedocs.io/en/latest/installation.html

Runs the scTenifold CLI from a Docker container, mounting the current directory.

```bash
docker run --rm -v "$PWD:/workspace" sctenifoldpy scTenifold --help

```

--------------------------------

### Reload Example

Source: https://sctenifoldpy.readthedocs.io/en/latest/workflow-output.html

Shows how to load previously saved scTenifoldNet and scTenifoldKnk objects.

```python
from scTenifold import scTenifoldNet, scTenifoldKnk

net = scTenifoldNet.load("./saved_net")
knk = scTenifoldKnk.load("./saved_knk")

```

--------------------------------

### Compare Two Conditions: `compare_networks`

Source: https://sctenifoldpy.readthedocs.io/en/latest/quickstart.html

This code snippet demonstrates how to compare two conditions using the `compare_networks` function. It generates test data, performs the comparison with specified keyword arguments for quality control and network construction, and prints the head of the resulting DataFrame.

```python
from scTenifold import compare_networks
from scTenifold.data import get_test_df

x = get_test_df(n_cells=200, n_genes=300, random_state=0)
y = get_test_df(n_cells=200, n_genes=300, random_state=1)

result = compare_networks(
    x, y,
    x_label="ctrl",
    y_label="cond",
    qc_kws={"min_lib_size": 1},
    network_kws={"n_nets": 3, "n_samp_cells": 100},
    backend="serial",
)

print(result.head())

```

--------------------------------

### Directory Layout Example

Source: https://sctenifoldpy.readthedocs.io/en/latest/workflow-output.html

Illustrates the file and directory structure when saving a scTenifoldNet object.

```text
saved_net/
|-- kws.json                 # all *_kws dicts + labels + shared_gene_names
|-- qc/
|   |-- ctrl.csv             # one CSV per label, genes x cells (post-QC)
|   `-- cond.csv
|-- nc/
|   |-- ctrl/
|   |   |-- network_0.npz    # one .npz per PC network (sparse)
|   |   |-- network_1.npz
|   |   `-- ...
|   `-- cond/
|       `-- ...
|-- td/
|   |-- ctrl.npz             # genes x genes tensor (sparse)
|   `-- cond.npz
|-- ma/
|   `-- manifold_alignment.csv
`-- dr/
    `-- d_regulation.csv


```

--------------------------------

### Virtual Knockout: `virtual_knockout`

Source: https://sctenifoldpy.readthedocs.io/en/latest/quickstart.html

This code snippet shows how to perform a virtual knockout experiment using the `virtual_knockout` function. It generates data, specifies genes to be knocked out, sets quality control and network parameters, and prints the head of the sorted results.

```python
from scTenifold import virtual_knockout
from scTenifold.data import get_test_df

data = get_test_df(n_cells=300, n_genes=300, random_state=0)

result = virtual_knockout(
    data,
    ko_genes=["NG-1"],
    qc_kws={"min_lib_size": 1, "min_exp_avg": 0, "min_exp_sum": 0},
    network_kws={"n_nets": 3, "n_samp_cells": 100},
    ko_method="default",
)

print(result.sort_values("p-value").head())

```

--------------------------------

### Run CLI from Docker Container (PowerShell)

Source: https://sctenifoldpy.readthedocs.io/en/latest/installation.html

Runs the scTenifold CLI from a Docker container on PowerShell, mounting the current directory.

```powershell
docker run --rm -v "${PWD}:/workspace" sctenifoldpy scTenifold --help

```

--------------------------------

### Selective Save Example

Source: https://sctenifoldpy.readthedocs.io/en/latest/workflow-output.html

Demonstrates how to save only specific components of the model.

```python
model.save("./saved_net", comps=["qc", "dr"])

```

--------------------------------

### run_step method example

Source: https://sctenifoldpy.readthedocs.io/en/latest/api/workflows.html

Illustrates the execution flow within the `run_step` method, including the initialization of `d_regulation` and handling of different steps.

```python
self.d_regulation = d_regulation(self.manifold, **(self.dr_kws if kwargs == {} else kwargs))
        self.step_comps["dr"] = self.d_regulation
    else:
        raise ValueError("No such step")
    print(f"process {step_name} finished in {time.perf_counter() - start_time} secs.")
```

--------------------------------

### Running a specific step with overrides

Source: https://sctenifoldpy.readthedocs.io/en/latest/pipeline-steps.html

Example of how to run a specific pipeline step ('nc') with custom parameters that override default settings for that call only.

```python
model.run_step("nc", n_nets=5, backend="joblib-loky", n_jobs=4)
```

--------------------------------

### make_networks usage

Source: https://sctenifoldpy.readthedocs.io/en/latest/parallel-backends.html

Example of using the `make_networks` function with the 'joblib-loky' backend and specifying the number of jobs.

```python
from scTenifold import make_networks

nets = make_networks(data, n_nets=10, backend="joblib-loky", n_jobs=4)

```

--------------------------------

### Inspecting state after running steps

Source: https://sctenifoldpy.readthedocs.io/en/latest/pipeline-steps.html

Examples of inspecting the state of the model after running specific pipeline steps, showing how to access populated attributes like QC_dict and network_dict.

```python
model.run_step("qc")
print(model.QC_dict["ctrl"].shape)

model.run_step("nc")
print([net.shape for net in model.network_dict["ctrl"]])
```

--------------------------------

### compare_networks usage

Source: https://sctenifoldpy.readthedocs.io/en/latest/parallel-backends.html

Example of using the `compare_networks` function with the 'joblib-loky' backend and specifying the number of jobs, including network keyword arguments.

```python
result = compare_networks(
    x, y,
    backend="joblib-loky",
    n_jobs=8,
    network_kws={"n_nets": 10},   # backend/n_jobs propagated automatically
)

```

--------------------------------

### Merging overrides by updating stored dictionaries

Source: https://sctenifoldpy.readthedocs.io/en/latest/pipeline-steps.html

Example demonstrating how to merge parameters by directly updating the step's keyword argument dictionary before calling run_step.

```python
model.nc_kws["n_jobs"] = 4
model.run_step("nc")
```

--------------------------------

### Listing and Fetching Remote Datasets

Source: https://sctenifoldpy.readthedocs.io/en/latest/source/1_data.html

This snippet shows how to list available remote datasets and fetch a specific dataset. Network access is required for these operations.

```python
from scTenifold.data import list_data

# Requires network access:
# list_data()
# datasets = fetch_data("AD")
```

--------------------------------

### Import necessary libraries and load test data

Source: https://sctenifoldpy.readthedocs.io/en/latest/source/2_build_network.html

Imports scTenifold modules and loads test expression matrices.

```python
from scTenifold import compare_networks, scTenifoldNet
from scTenifold.data import get_test_df

x = get_test_df(n_cells=80, n_genes=40, random_state=0)
y = get_test_df(n_cells=80, n_genes=40, random_state=1)
```

--------------------------------

### scTenifoldKnk Initialization and Step Execution

Source: https://sctenifoldpy.readthedocs.io/en/latest/source/3_knock_out.html

A more compact representation of the scTenifoldKnk initialization and the loop for running each step, followed by displaying the head of the d_regulation DataFrame.

```python
knk = scTenifoldKnk( data=data, ko_genes=ko_genes, qc_kws={"min_lib_size": 1, "plot": False, "max_mito_ratio": 1.0, "min_percent": 0, "min_exp_avg": 0, "min_exp_sum": 0}, nc_kws={"n_nets": 2, "n_samp_cells": 25, "q": 0, "backend": "serial"}, td_kws={"K": 2, "max_iter": 20, "init": "random"}, ma_kws={"d": 2}, ko_method="default", ) for step in ["qc", "nc", "td", "ko", "ma", "dr"]: knk.run_step(step) knk.d_regulation.head()
```

--------------------------------

### scTenifoldNet Workflow

Source: https://sctenifoldpy.readthedocs.io/en/latest/source/2_build_network.html

This code snippet demonstrates the step-wise execution of the scTenifoldNet model, including initialization and running each step (qc, nc, td, ma, dr). It also shows how to access the differential regulation results.

```python
model = scTenifoldNet(
    x,
    y,
    x_label="control",
    y_label="condition",
    qc_kws={"min_lib_size": 1, "plot": False, "max_mito_ratio": 1.0, "min_percent": 0},
    nc_kws={"n_nets": 2, "n_samp_cells": 25, "q": 0, "backend": "serial"},
    td_kws={"K": 2, "max_iter": 20, "init": "random"},
    ma_kws={"d": 2},
)

for step in ["qc", "nc", "td", "ma", "dr"]:
    model.run_step(step)

model.d_regulation.head()

```

--------------------------------

### scTenifoldKnk Step-wise Workflow

Source: https://sctenifoldpy.readthedocs.io/en/latest/source/3_knock_out.html

Initializes the scTenifoldKnk class and runs through the sequential steps of QC, NC, TD, KO, MA, and DR, finally displaying the head of the d_regulation DataFrame.

```python
knk = scTenifoldKnk(
    data=data,
    ko_genes=ko_genes,
    qc_kws={"min_lib_size": 1, "plot": False, "max_mito_ratio": 1.0, "min_percent": 0, "min_exp_avg": 0, "min_exp_sum": 0},
    nc_kws={"n_nets": 2, "n_samp_cells": 25, "q": 0, "backend": "serial"},
    td_kws={"K": 2, "max_iter": 20, "init": "random"},
    ma_kws={"d": 2},
    ko_method="default",
)

for step in ["qc", "nc", "td", "ko", "ma", "dr"]:
    knk.run_step(step)

knk.d_regulation.head()

```

--------------------------------

### Loading Test DataFrames

Source: https://sctenifoldpy.readthedocs.io/en/latest/source/1_data.html

This snippet demonstrates how to load test expression data using pandas DataFrames and checks their shapes.

```python
import pandas as pd
from scTenifold.data import get_test_df

x = get_test_df(n_cells=80, n_genes=120, random_state=0)
y = get_test_df(n_cells=80, n_genes=120, random_state=1)

x.shape, y.shape
```

--------------------------------

### AnnData Round-trip Conversion

Source: https://sctenifoldpy.readthedocs.io/en/latest/anndata.html

Example showing the conversion of an AnnData object to a pandas DataFrame using anndata_to_dataframe and asserting the index and column names.

```python
import anndata as ad
from scTenifold.core._networks import anndata_to_dataframe

adata = ad.read_h5ad("sample.h5ad")
df = anndata_to_dataframe(adata, layer="counts")
assert df.index.equals(adata.var_names)
assert df.columns.equals(adata.obs_names)

```

--------------------------------

### One-call workflow for virtual knockout

Source: https://sctenifoldpy.readthedocs.io/en/latest/source/3_knock_out.html

This snippet demonstrates the use of the `virtual_knockout` function, which is the simplest entry point for performing a virtual knockout analysis. It includes various keyword arguments for quality control, network construction, tensor decomposition, and manifold alignment.

```python
result = virtual_knockout(
    data,
    ko_genes=ko_genes,
    qc_kws={"min_lib_size": 1, "plot": False, "max_mito_ratio": 1.0, "min_percent": 0, "min_exp_avg": 0, "min_exp_sum": 0},
    network_kws={"n_nets": 2, "n_samp_cells": 25, "q": 0},
    ko_method="default",
    td_kws={"K": 2, "max_iter": 20, "init": "random"},
    ma_kws={"d": 2},
)

result.sort_values("p-value").head()
```

--------------------------------

### Import necessary libraries and load test data

Source: https://sctenifoldpy.readthedocs.io/en/latest/source/3_knock_out.html

This snippet imports the required scTenifold modules and loads a test dataset. It also defines the genes to be knocked out.

```python
from scTenifold import scTenifoldKnk, virtual_knockout
from scTenifold.data import get_test_df

data = get_test_df(n_cells=80, n_genes=40, random_state=2)
ko_genes = ["NG-1"]

```

--------------------------------

### Import necessary libraries and load test data

Source: https://sctenifoldpy.readthedocs.io/en/latest/source/4_visualization.html

This code block imports essential libraries for visualization and data handling, and then loads two test datasets, x and y, for further processing.

```python
%matplotlib inline
from scTenifold import compare_networks, scTenifoldNet
from scTenifold.data import get_test_df
from scTenifold.plotting import plot_hist, plot_network_heatmap, plot_qqplot

x = get_test_df(n_cells=80, n_genes=40, random_state=0)
y = get_test_df(n_cells=80, n_genes=40, random_state=1)

```

--------------------------------

### One-call workflow using compare_networks()

Source: https://sctenifoldpy.readthedocs.io/en/latest/source/2_build_network.html

Compares two expression matrices using the compare_networks() function with specified parameters for a quick analysis. The settings are kept small for tutorial speed; larger values are recommended for real analyses.

```python
result = compare_networks(
    x,
    y,
    x_label="control",
    y_label="condition",
    qc_kws={"min_lib_size": 1, "plot": False, "max_mito_ratio": 1.0, "min_percent": 0},
    network_kws={"n_nets": 2, "n_samp_cells": 25, "q": 0},
    backend="serial",
    td_kws={"K": 2, "max_iter": 20, "init": "random"},
    ma_kws={"d": 2},
)

result.head()
```

--------------------------------

### __post_init__ Method

Source: https://sctenifoldpy.readthedocs.io/en/latest/api/data.html

Initializes the simulated count matrix and gene/sample labels. It handles target positive and negative genes, generates the count matrix using negative binomial distribution, adds efficiency effects, and creates gene and sample lists.

```python
def __post_init__(self) -> None:
    """Build the simulated count matrix and gene/sample labels."""
    self.random_state_seed = self.random_state
    random_state = np.random.default_rng(self.random_state)
    if self.target_pos is None:
        self.target_pos = DEFAULT_POS
    if self.target_neg is None:
        self.target_neg = []
    if len(self.target_pos) + len(self.target_neg) > self.n_genes:
        raise ValueError("n_genes must be at least the number of target positive and negative genes")
    self.X = random_state.negative_binomial(20, 0.9,
                                            size=(self.n_genes, self.n_samples))
    self._add_eff(random_state)

    self.gene_list = ([f"pseudo_G{i}" for i in range(self.n_genes -
                                                     len(self.target_pos) -
                                                     len(self.target_neg))] +
                      self.target_pos + self.target_neg)
    self.samples = [f"cell{i}" for i in range(self.X.shape[1])]
    self.n_X = _normalize(self.X)
```

--------------------------------

### Building the scTenifoldNet model

Source: https://sctenifoldpy.readthedocs.io/en/latest/source/4_visualization.html

This snippet shows how to initialize and build the scTenifoldNet model for analyzing gene expression data.

```python
model = scTenifoldNet(
    x,
    y,
    "control",
    "condition",
    qc_kws={"min_lib_size": 1, "plot": False, "max_mito_ratio": 1.0, "min_percent": 0},
    nc_kws={"n_nets": 2, "n_samp_cells": 25, "q": 0, "backend": "serial"},
    td_kws={"K": 2, "max_iter": 20, "init": "random"},
    ma_kws={"d": 2},
)
model.build()
```

--------------------------------

### QC histogram

Source: https://sctenifoldpy.readthedocs.io/en/latest/source/4_visualization.html

Plots a histogram for quality control metrics.

```python
plot_hist(x, "control")

```

--------------------------------

### Inspecting DataFrame Index and Columns

Source: https://sctenifoldpy.readthedocs.io/en/latest/source/1_data.html

This snippet shows how to inspect the first few gene names (index) and cell names (columns) of a DataFrame.

```python
x.index[:5].tolist(), x.columns[:5].tolist()
```

--------------------------------

### Generate Configuration Files

Source: https://sctenifoldpy.readthedocs.io/en/latest/cli.html

Commands to generate YAML configuration files for scTenifoldNet and scTenifoldKnk.

```bash
scTenifold config --type 1 --path net_config.yml   # scTenifoldNet
scTenifold config --type 2 --path knk_config.yml   # scTenifoldKnk

```

--------------------------------

### Accessing Model Outputs

Source: https://sctenifoldpy.readthedocs.io/en/latest/source/2_build_network.html

This code snippet shows how to access and inspect the shapes of various outputs from the scTenifoldNet model after running the steps, including QC data, number of networks, tensor shape, and manifold shape.

```python
{
    "qc_shape": model.QC_dict["control"].shape,
    "n_networks": len(model.network_dict["control"]),
    "tensor_shape": model.tensor_dict["control"].shape,
    "manifold_shape": model.manifold.shape,
}

```

--------------------------------

### Run Workflows

Source: https://sctenifoldpy.readthedocs.io/en/latest/cli.html

Commands to execute the scTenifoldNet and scTenifoldKnk workflows using their respective configuration files.

```bash
scTenifold net --config net_config.yml --output ./saved_net
scTenifold knk --config knk_config.yml --output ./saved_knk

```

--------------------------------

### Converting AnnData-like Object to DataFrame

Source: https://sctenifoldpy.readthedocs.io/en/latest/source/1_data.html

This snippet demonstrates how to convert a custom AnnData-like object to a pandas DataFrame using `anndata_to_dataframe` and verifies the conversion.

```python
from scTenifold.core._networks import anndata_to_dataframe

class MiniAnnData:
    def __init__(self, matrix, obs_names, var_names):
        self.X = matrix
        self.obs_names = obs_names
        self.var_names = var_names
        self.layers = {}

adata = MiniAnnData(x.T.to_numpy(), obs_names=x.columns, var_names=x.index)
converted = anndata_to_dataframe(adata)
converted.equals(x)
```

--------------------------------

### Tensor heatmap

Source: https://sctenifoldpy.readthedocs.io/en/latest/source/4_visualization.html

Generates a heatmap visualization for model tensors.

```python
plot_network_heatmap(model.tensor_dict["control"].to_numpy())

```

--------------------------------

### scTenifoldKnk Pipeline

Source: https://sctenifoldpy.readthedocs.io/en/latest/pipeline-steps.html

The sequence of steps in the scTenifoldKnk pipeline, highlighting differences from scTenifoldNet.

```text
data_dict -> qc -> QC_dict -> nc -> network_dict["WT"] -> td -> tensor_dict["WT"] -> ko -> tensor_dict["KO"] -> ma -> manifold -> dr -> d_regulation
```

--------------------------------

### build() method implementation

Source: https://sctenifoldpy.readthedocs.io/en/latest/api/workflows.html

The full implementation of the build method, which orchestrates the scTenifoldKnk pipeline steps.

```python
def build(self) -> pd.DataFrame:
    """
    Run the whole pipeline of scTenifoldKnk

    Returns
    -------
    d_regulation_df: pd.DataFrame
        Differential regulation result dataframe
    """
    self.run_step("qc")
    self.run_step("nc")
    self.run_step("td")
    self.run_step("ko")
    self.run_step("ma")
    self.run_step("dr")
    return self.d_regulation
```