### Install CytoBridge via pip

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/readme.md

Recommended installation method for end users. Installs the latest release from PyPI.

```bash
pip install CytoBridge
```

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

### Install CytoBridge dependencies

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/readme.md

Installs all required dependencies listed in requirements.txt.

```bash
pip install -r requirements.txt
```

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

### Importing Required Libraries

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Mouse Blood Hematopoiesis + Basic Plot.ipynb

Initial setup importing pandas, scanpy, numpy, anndata, os, and the CytoBridge package.

```python
import pandas as pd
import scanpy as sc
import numpy as np
from anndata import AnnData
import os
import CytoBridge as cb
```

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

### Clone CytoBridge repository

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/readme.md

Developer approach to get the source code for modification or contribution.

```bash
git clone https://github.com/zhenyiizhang/CytoBridge.git
```

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

### Model Training Output Logs

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Preprocess and Training.ipynb

Console output showing the progression of Pretrain, Train_FM, and Finetune stages, including loss tracking and model saving paths.

```text
Output:
Loading built-in config: 'ruot_weinreb2'

--- Starting Stage: Pretrain ---
  Mode: neural_ode, Epochs: 10, Use Score: False

====  Pretrain  ====
--------------------------------------------------
--------------------------------------------------
  No scheduler parameters configured - keeping learning rate constant
  velocity_net     grad=True
  growth_net       grad=True
  score_net        grad=False
  Optimizer parameters (shapes): [torch.Size([400, 51]), torch.Size([400]), torch.Size([400, 400]), torch.Size([400]), torch.Size([50, 400]), torch.Size([50]), torch.Size([400, 51]), torch.Size([400]), torch.Size([400, 400]), torch.Size([400]), torch.Size([1, 400]), torch.Size([1])]
  Stage 'Pretrain', Epoch 1/10, Loss: 523.3851
[INFO] Epoch   0 has a lower loss| all_loss 523.3851
[INFO] Epoch   1 has a lower loss| all_loss 428.3913
[INFO] Epoch   2 has a lower loss| all_loss 378.7752
[INFO] Epoch   7 has a lower loss| all_loss 346.4558
  Best model (loss=346.4558) saved → /home/sjt/workspace2/CytoBridge_test-main_crufm/results/experiment_weinreb1/Pretrain/best.pth

--- Starting Stage: Train_FM ---
  Mode: flow_matching, Epochs: 30, Use Score: False

====  Train_FM  ====
--------------------------------------------------
  velocity_net     grad=False
  growth_net       grad=False
  score_net        grad=True
  Optimizer parameters (shapes): [torch.Size([128, 51]), torch.Size([128]), torch.Size([128, 128]), torch.Size([128]), torch.Size([128, 128]), torch.Size([128]), torch.Size([128, 128]), torch.Size([128]), torch.Size([1, 128]), torch.Size([1])]
alpha_regm : 1.0
```

```text
Output:
Computing UOT plans...:   0%|          | 0/2 [00:00<?, ?it/s]
```

```text
Output:
[Round-1 eps=5.000e-02] Failed: UserWarning: Numerical errors at iteration 901
Final entropic reg selected: 0.07100000000000001
Elbow rule selected reg_m: 1.125336
Time step 0 chunk 0 (per_time): reg=0.07100000000000001, reg_m=1.1253355826007645
Time step 0 chunk: scaled reg_m = 1.1253355826007645
Time step 0 chunk: scaled reg_m = 1.1253355826007645
```

```text
Output:
Computing UOT plans...:  50%|█████     | 1/2 [00:49<00:49, 49.21s/it]
```

```text
Output:
Time step 0 chunk: scaled reg_m = 1.1253355826007645
Final entropic reg selected: 0.051000000000000004
Elbow rule selected reg_m: 1.359356
Time step 1 chunk 0 (per_time): reg=0.051000000000000004, reg_m=1.3593563908785256
Time step 1 chunk: scaled reg_m = 1.3593563908785256
Time step 1 chunk: scaled reg_m = 1.3593563908785256
Time step 1 chunk: scaled reg_m = 1.3593563908785256
Time step 1 chunk: scaled reg_m = 1.3593563908785256
Time step 1 chunk: scaled reg_m = 1.3593563908785256
Time step 1 chunk: scaled reg_m = 1.3593563908785256
Time step 1 chunk: scaled reg_m = 1.3593563908785256
Time step 1 chunk: scaled reg_m = 1.3593563908785256
```

```text
Output:
Computing UOT plans...: 100%|██████████| 2/2 [01:33<00:00, 46.72s/it]
Flow matching: 100%|██████████| 30/30 [00:03<00:00,  9.77it/s]
```

```text
Output:
  Best model (loss=0.6366) saved → /home/sjt/workspace2/CytoBridge_test-main_crufm/results/experiment_weinreb1/Train_FM/best_model.pth

--- Starting Stage: Finetune ---
  Mode: neural_ode, Epochs: 5, Use Score: False

====  Finetune  ====
--------------------------------------------------
--------------------------------------------------
  No scheduler parameters configured - keeping learning rate constant
  velocity_net     grad=True
  growth_net       grad=True
  score_net        grad=False
  Optimizer parameters (shapes): [torch.Size([400, 51]), torch.Size([400]), torch.Size([400, 400]), torch.Size([400]), torch.Size([50, 400]), torch.Size([50]), torch.Size([400, 51]), torch.Size([400]), torch.Size([400, 400]), torch.Size([400]), torch.Size([1, 400]), torch.Size([1])]
  Stage 'Finetune', Epoch 1/5, Loss: 411.4681
[INFO] Epoch   0 has a lower loss| all_loss 411.4681
[INFO] Epoch   1 has a lower loss| all_loss 408.1792
[INFO] Epoch   2 has a lower loss| all_loss 375.0804
[INFO] Epoch   4 has a lower loss| all_loss 354.1136
  Best model (loss=354.1136) saved → /home/sjt/workspace2/CytoBridge_test-main_crufm/results/experiment_weinreb1/Finetune/best.pth
['velocity', 'growth', 'score']
Model & data saved -> /home/sjt/workspace2/CytoBridge_test-main_crufm/results/experiment_weinreb1

--- Starting Evaluation ---
  Time Point 1.0: Wasserstein-1 Distance = 7.2566
  Time Point 1.0: TMV = 36.7032
  Time Point 2.0: Wasserstein-1 Distance = 8.7752
  Time Point 2.0: TMV = 113.5138
```

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

### Load trained data and model from H5AD file

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Simulation Dataset + Basic Plot.ipynb

Sets the path to the H5AD file, derives the experiment name from its parent directory, creates an output figure directory, reads the AnnData object, and loads the CytoBridge model. The model loading prints 'Reconstructing model...' and 'Model loaded successfully.' when successful.

```python
save_path = "/home/sjt/workspace2/CytoBridge_test-main_crufm/results/cyexperiment_simulation/adata.h5ad"      
exp_name      = os.path.basename(os.path.dirname(save_path))      # -> results_unscore
base_fig_dir  = "/home/sjt/workspace2/CytoBridge_test-main_crufm/figures"
output_path   = os.path.join(base_fig_dir, exp_name)
os.makedirs(output_path, exist_ok=True)


adata  = sc.read_h5ad(save_path)
model  = cb.utils.load_model_from_adata(adata)
device = "cuda"

```

```text
Output:
Reconstructing model...
Model loaded successfully.

```

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

### Import libraries for CytoBridge simulation analysis

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Simulation Dataset + Basic Plot.ipynb

Imports pandas, scanpy, numpy, anndata, CytoBridge, and os. Required for data handling, single-cell analysis, and model loading.

```python
import pandas as pd
import scanpy as sc
import numpy as np
from anndata import AnnData
import CytoBridge as cb
import os

```

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

### Navigate to CytoBridge repository root

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/readme.md

Changes the current directory to the root of the cloned CytoBridge repository.

```bash
cd path_to_CytoBridge
```

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

### Train CytoBridge from CSV file

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/readme.md

Shows the workflow for CSV input: load a gene-expression table, separate metadata and expression, build an AnnData, preprocess with dim_reduction='none' and normalization=False (since data are already transformed), train with config='ruot', and save.

```python
import pandas as pd
from anndata import AnnData
import cytobridge as cb

# 1. Load table: rows = cells, columns = gene counts + one "samples" (time) column
df = pd.read_csv('simulation_gene.csv')

# 2. Separate metadata and expression
obs = pd.DataFrame(index=df.index)
obs['samples'] = df['samples'].astype(str)          # time information
X = df.drop(columns=['samples']).values             # expression matrix

# 3. Build AnnData
adata = AnnData(X=X, obs=obs)

# 4. Pre-process (skip built-in PCA/norm here because data are already transformed)
cb.pp.preprocess(adata,
                 time_key='samples',
                 dim_reduction='none',
                 normalization=False,
                 log1p=False,
                 select_hvg=False)

# 5. Train
cb.tl.fit(adata, config='ruot', device='cuda')

# 6. Save
adata.write_h5ad("results_with_model.h5ad")
```

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

### Create and activate Conda environment for CytoBridge

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/readme.md

Creates an isolated Conda environment with Python 3.10 and ipykernel, then activates it.

```bash
conda create -n CytoBridge python=3.10 ipykernel -y
conda activate CytoBridge
```

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

### Train CytoBridge from AnnData object (h5ad)

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/readme.md

Shows the full workflow for h5ad input: preprocess with PCA, normalization, log1p, and HVG selection; train with config 'dynamical_ot' (velocity only) or other modes; save the AnnData with the model.

```python
import scanpy as sc
import cytobridge as cb
import anndata as ad

# 1. Pre-process
#    time_key: column in adata.obs that stores time-points
cb.pp.preprocess(adata,
                 time_key='Time point',
                 dim_reduction='PCA',
                 normalization=True,
                 log1p=True,
                 select_hvg=True)

# 2. Train
#    dynamical_ot : velocity only
#    unbalanced_ot: velocity + growth
#    ruot         : velocity + growth + score (stochasticity) (RUOT mode)
cb.tl.fit(adata, config='dynamical_ot', device='cuda')   # or 'cpu'

# 3. Save
adata.write_h5ad("results_with_model.h5ad")
```

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

### Preprocess and train CytoBridge model

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Preprocess and Training.ipynb

Performs data preprocessing and model training using the specified configuration and device.

```python
import CytoBridge

# Preprocess the data with specified parameters.
adata = CytoBridge.pp.preprocess(adata, time_key='samples', dim_reduction='none', normalization=False, log1p=False, select_hvg=False)

# Train the model using the specified configuration and device.
adata = CytoBridge.tl.fit(adata, config='ruot_simulation_gene', device='cuda')
```

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

### Train model with CytoBridge.tl.fit

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Preprocess and Training.ipynb

Trains the model using the 'ruot_weinreb2' configuration on the specified device (cuda).

```python
adata = CytoBridge.tl.fit(adata, config = 'ruot_weinreb2', device = 'cuda')
```

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

### Display AnnData object

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Preprocess and Training.ipynb

Shows the AnnData object with its dimensions and annotations. The output indicates 49116 observations and 50 variables, with various metadata fields.

```python
adata
```

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

### Load and convert CSV to AnnData

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Preprocess and Training.ipynb

Loads a gene expression CSV file, extracts sample information, and saves the resulting AnnData object as an H5AD file.

```python
# %%
import pandas as pd
import scanpy as sc
import numpy as np
from anndata import AnnData

# Load the gene expression matrix and sample time information from a CSV file.
df = pd.read_csv('/lustre/home/2501111653/DeepRUOTv2_test_data/data/simulation_gene.csv')

# Create an observation DataFrame to store sample information.
obs = pd.DataFrame(index=df.index)
obs['samples'] = df['samples'].values

# Extract the gene expression matrix by dropping the 'samples' column.
X = df.drop(columns=['samples']).values

# Create an AnnData object from the gene expression matrix and observation DataFrame.
adata = AnnData(X=X, obs=obs)

# Save the AnnData object to an H5AD file for further analysis.
adata.write_h5ad('data/simulation_gene.h5ad')
```

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

### Load h5ad file with scanpy

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Preprocess and Training.ipynb

Loads a gene expression matrix from an h5ad file using scanpy. The resulting AnnData object contains 49116 observations and 25289 variables with various metadata fields.

```python
import scanpy as sc
adata = sc.read_h5ad('/home/sjt/workspace2/CytoBridge_test-main_crufm/data/weinreb_unpropocessed.h5ad')
adata
```

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

### Plot Growth Rates

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Simulation Dataset + Basic Plot.ipynb

Visualizes growth rates of the data if the model includes growth and score components. Calls CytoBridge.pl.plot_growth with dim_reduction='none' and output_path set to a PNG file. Output shows the saved file path.

```python
CytoBridge.pl.plot_growth(
    adata,
    dim_reduction='none',
    output_path=os.path.join(output_path, "g_values_plot.png")
)
```

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

### Plot Interaction Velocity and Potential

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Simulation Dataset + Basic Plot.ipynb

Plots the interaction force stream and interaction potential if the model includes interaction components. Checks for 'interaction' in adata.uns['all_model']['model_config']['components'] and calls cb.pl.plot_interaction_stream and cb.pl.plot_interaction_potential. Output shows saved SVG and PNG file paths.

```python
if "interaction" in adata.uns['all_model']['model_config']['components']:
    cb.pl.plot_interaction_stream(adata, output_path, dim_reduction='none', device='cuda')   
    cb.pl.plot_interaction_potential(model, d=2, num_points=2000,output_path=os.path.join(output_path, "interaction_plot.png"))
```

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

### Preprocess data with CytoBridge.pp.preprocess

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Preprocess and Training.ipynb

Preprocesses the AnnData object using the specified time key, PCA dimensionality reduction, normalization, log1p transformation, and selection of top 2000 highly variable genes. The output shows the automatic time mapping and the resulting reduced dataset.

```python
import CytoBridge
adata = CytoBridge.pp.preprocess(adata, time_key = 'time_info', dim_reduction = 'PCA', normalization = True, log1p = True, select_hvg = True)
```

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

### Plot ODE trajectories with CytoBridge.pl.plot_ode_trajectories

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Simulation Dataset + Basic Plot.ipynb

Generates deterministic trajectories using an ODE model. The function takes an AnnData object, a model, output path, and parameters for number of trajectories, bins, and dimensionality reduction. The output includes a PDF file saved to the specified output path.

```python
CytoBridge.pl.plot_ode_trajectories(
    adata=adata,
    model=model,
    output_path=output_path,
    n_trajectories=20,
    n_bins=20,
    dim_reduction='none',
    device=device
)
```

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

### Plot Potential Landscape

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Simulation Dataset + Basic Plot.ipynb

Visualizes the potential landscape of the data if the model includes velocity. Calls CytoBridge.pl.plot_landscape with dim_reduction='none' and device='cuda'. Output shows training loss over epochs and a figure.

```python
CytoBridge.pl.plot_landscape(adata,model,output_path=output_path,dim_reduction="none",device="cuda")
```

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

### Generate SDE trajectories and classify cells with CytoBridge.pl.process_sde_classification

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Mouse Blood Hematopoiesis + Basic Plot.ipynb

Generates stochastic trajectories using an SDE model that incorporates velocity components and classifies cells according to the specified 'classifyed_type' (e.g., 'cluster'). Requires an AnnData object and a trained model. Saves results to the specified output paths and visualizes them.

```python
CytoBridge.pl.process_sde_classification(
    adata,
    model,
    classifyed_type= 'cluster',
    sde_data_path=output_path+'/sde_results',
    output_path = output_path+'/sde_results',
    n_time_steps = 10,
    sample_traj_num = 100,
    dim_reduction="umap",
    hidden_size=128, 
    train_mlp_classifier_epoches=400
    )
```

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

### Plot SDE trajectories with CytoBridge.pl.plot_sde_trajectories

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Simulation Dataset + Basic Plot.ipynb

Generates stochastic trajectories using an SDE model that incorporates velocity and score-based components. The function returns an AnnData object and saves the trajectory plot to a PDF file. The output log shows model loading and reconstruction steps.

```python
adata = CytoBridge.pl.plot_sde_trajectories(
    adata=adata,
    output_path=os.path.join(output_path, "sde_results"),  
    device=device,
    sigma=0.05,
    dim_reduction='none',
    n_trajectories=20,
    n_bins=50,
)
```

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

### Display processed time coordinates

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Preprocess and Training.ipynb

Displays the processed time coordinates stored in the 'time_point_processed' column of the AnnData object's obs. The output shows a series of float values.

```python
adata.obs['time_point_processed']
```

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

### Plot growth rate with UMAP

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Preprocess and Training.ipynb

Generates a growth rate plot using UMAP dimensionality reduction and saves it to 'g_values_plot.svg'. The output is a figure with size 1200x800.

```python
CytoBridge.pl.plot_growth(adata, dim_reduction = 'umap', output_path = 'g_values_plot.svg')
```

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

### Access Latent Space Representation

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Preprocess and Training.ipynb

Command to retrieve the latent space representation from the AnnData object.

```python
adata.obsm['X_latent']
```

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

### Plot Velocity Stream with UMAP

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Mouse Blood Hematopoiesis + Basic Plot.ipynb

Plots the intrinsic velocity stream using UMAP dimensionality reduction.

```python
if 'velocity_latent' in adata.obsm:
    adata = cb.pl.plot_velocity_stream(adata, model,output_path, dim_reduction='umap', device='cuda',color_key="cluster")
```

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

### Plot growth values with CytoBridge.pl.plot_growth

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Preprocess and Training.ipynb

Plots growth values for an AnnData object without dimensionality reduction and saves the figure to the specified output path. The output confirms the file was saved and shows the figure size.

```python
CytoBridge.pl.plot_growth(adata, dim_reduction = 'none', output_path= '/home/sjt/workspace2/CytoBridge_test-main_crufm/figures/g_values_plot.svg')
```

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

### Plot Combined Velocity Stream

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Mouse Blood Hematopoiesis + Basic Plot.ipynb

Plots the combined velocity and score stream when both components are present in the model.

```python
if 'score_latent' in adata.obsm and 'velocity_latent' in adata.obsm:
    CytoBridge.pl.plot_combined_velocity_stream(adata,model,output_path,dim_reduction='none',device='cuda')
```

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

### Analyze terminal states of unterminal cells with CytoBridge.pl.analyze_terminal_states

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Mouse Blood Hematopoiesis + Basic Plot.ipynb

Analyzes terminal states for cells that are not yet terminal, using the specified terminal states list. Requires 'velocity_latent' in adata.obsm. Prints the AnnData object and saves the analysis results to the output path.

```python
if 'velocity_latent' in adata.obsm:

    print(adata)
    CytoBridge.pl.analyze_terminal_states(adata, classified_type="cluster", terminal_states=["Neutrophil", "Monocyte","Mast","Erythroid","Baso","Meg"], output_path=output_path)
```

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

### Plot Combined Velocity Stream

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Simulation Dataset + Basic Plot.ipynb

Plots the combined velocity stream if the model includes both velocity and score components. Checks for 'score_latent' and 'velocity_latent' in adata.obsm and calls cb.pl.plot_combined_velocity_stream with dim_reduction='none' and device='cuda'. Output shows a CUDA warning and saved SVG file path.

```python
if 'score_latent' in adata.obsm and 'velocity_latent' in adata.obsm:
    cb.pl.plot_combined_velocity_stream(adata,model,output_path,dim_reduction='none',device='cuda')
```

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

### Plot Velocity Stream

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Simulation Dataset + Basic Plot.ipynb

Plots the intrinsic velocity stream if the model includes velocity components. Checks for 'velocity_latent' in adata.obsm and calls cb.pl.plot_velocity_stream with dim_reduction='none' and device='cuda'. Output shows the saved SVG file path.

```python
if 'velocity_latent' in adata.obsm:
    cb.pl.plot_velocity_stream(adata, model,output_path, dim_reduction='none', device='cuda')
```

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

### Plot Score Velocity Stream

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Simulation Dataset + Basic Plot.ipynb

Plots the score velocity stream (diffusion velocity, stochasticity) if the model includes score components. Checks for 'score_latent' in adata.obsm and calls cb.pl.plot_score_stream with dim_reduction='none' and device='cuda'. Output shows the saved SVG file path.

```python
if 'score_latent' in adata.obsm :
    cb.pl.plot_score_stream(adata,model, output_path, dim_reduction='none', device='cuda')
```

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

### Plot Velocity Stream without Dimensionality Reduction

Source: https://github.com/zhenyiizhang/cytobridge/blob/main/Mouse Blood Hematopoiesis + Basic Plot.ipynb

Plots the intrinsic velocity stream without applying dimensionality reduction.

```python
if 'velocity_latent' in adata.obsm:
    adata = cb.pl.plot_velocity_stream(adata, model,output_path, dim_reduction='none', device='cuda',color_key="cluster")
```