### Install PRESCIENT (Stable Version)

Source: https://github.com/gifford-lab/prescient/blob/master/docs/_layouts/home.html

Use pip to install the stable version of PRESCIENT. This command installs the latest released version from PyPI.

```bash
pip install prescient
```

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

### Install PRESCIENT (Latest Version)

Source: https://github.com/gifford-lab/prescient/blob/master/docs/_layouts/home.html

Install the latest development version of PRESCIENT directly from its GitHub repository using pip. This is useful for accessing the newest features or bug fixes.

```bash
pip install git+https://github.com/gifford-lab/prescient.git
```

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

### PRESCIENT CLI: simulate_trajectories

Source: https://context7.com/gifford-lab/prescient/llms.txt

Simulates cell trajectories forward in time using a trained PRESCIENT model, allowing prediction of cell fates from any starting population.

```APIDOC
## prescient simulate_trajectories

### Description
Simulates cell trajectories forward in time using a trained PRESCIENT model. This allows prediction of cell fates from any starting population.

### Method
CLI Command

### Endpoint
N/A (CLI Tool)

### Parameters
#### Path Parameters
- **-i** (string) - Required - Path to processed data file (.pt).
- **--model_path** (string) - Required - Path to the directory containing the trained model.
- **-o** (string) - Required - Path to output directory for simulation results.

#### Query Parameters
- **--seed** (integer) - Optional - Random seed for reproducibility (default: None).
- **--epoch** (string) - Required - Epoch number of the trained model to use (e.g., '002500').
- **--num_sims** (integer) - Optional - Number of simulations to run per cell (default: 10).
- **--num_cells** (integer) - Optional - Number of cells to simulate from (default: 200).
- **--num_steps** (integer) - Optional - Number of simulation steps (default: None, inferred from model).
- **--tp_subset** (integer) - Optional - Subset of timepoints to start simulations from (default: None).
- **--celltype_subset** (string) - Optional - Subset of cell types to start simulations from (default: None).
- **--gpu** (integer) - Optional - GPU device ID to use (default: None).

### Request Example
```bash
# Run simulations from all cells
prescient simulate_trajectories \
  -i /path/to/data.pt \
  --model_path /path/to/model_dir/ \
  --seed 1 \
  --epoch 002500 \
  --num_sims 10 \
  --num_cells 200 \
  -o /path/to/output/

# Run simulations from specific cell population
prescient simulate_trajectories \
  -i /path/to/data.pt \
  --model_path /path/to/model_dir/ \
  --seed 1 \
  --epoch 002500 \
  --num_sims 50 \
  --num_cells 500 \
  --num_steps 100 \
  --tp_subset 0 \
  --celltype_subset "progenitor" \
  --gpu 0 \
  -o /path/to/simulations/
```

### Response
N/A (CLI Tool output to file)
```

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

### Accessing PRESCIENT command help

Source: https://github.com/gifford-lab/prescient/blob/master/docs/documentation.html

Use this syntax to view the manual for specific commands.

```bash
prescient commands -h
```

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

### Executing PRESCIENT commands

Source: https://github.com/gifford-lab/prescient/blob/master/docs/documentation.html

Standard format for running tools within the PRESCIENT suite.

```bash
prescient command [params]
```

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

### Import Required Libraries

Source: https://github.com/gifford-lab/prescient/blob/master/notebooks/estimate-growth-rates.ipynb

Initial imports for data manipulation, machine learning, and PRESCIENT utilities.

```python
import prescient.utils
import numpy as np
import pandas as pd
import sklearn
import umap
import scipy
import annoy
import torch
import matplotlib.pyplot as plt
```

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

### Train a PRESCIENT model

Source: https://github.com/gifford-lab/prescient/blob/master/docs/quickstart.html

Trains a model using default parameters; GPU acceleration is recommended for performance.

```bash
prescient train_model -i /path/to/data.pt --out_dir /experiments/ --weight_name 'kegg-growth'
```

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

### Simulate cell trajectories

Source: https://github.com/gifford-lab/prescient/blob/master/docs/quickstart.html

Simulates forward trajectories from initial cell states using a trained model.

```bash
prescient simulate_trajectories -i /path/to/data.pt --model_path /path/to/trained/model_directory -o /path/to/output_dir --seed 2
```

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

### Run Forward Simulations

Source: https://context7.com/gifford-lab/prescient/llms.txt

Execute stochastic differential equation simulations using a trained PRESCIENT model and input data.

```python
import torch
import numpy as np
from types import SimpleNamespace
from prescient.train.model import AutoGenerator
import prescient.simulate as traj

# Load PRESCIENT data file
data_pt = torch.load('data.pt')
expr = data_pt["data"]
pca = data_pt["pca"]
xp = pca.transform(expr)

# Load trained model
device = torch.device('cuda:0' if torch.cuda.is_available() else 'cpu')
config = SimpleNamespace(**torch.load('config.pt'))
model = AutoGenerator(config)
checkpoint = torch.load('train.epoch_002500.pt', map_location=device)
model.load_state_dict(checkpoint['model_state_dict'])
model.to(device)

# Run simulations
all_sims = traj.simulate(
    xp=xp,                             # PCA coordinates of all cells
    tps=data_pt["tps"],                # Timepoint labels
    celltype_annotations=data_pt["celltype"],  # Cell type labels
    w=data_pt["w"],                    # Growth weights
    model=model,                       # Trained PRESCIENT model
    config=config,                     # Model configuration
    num_sims=10,                       # Number of independent simulations
    num_cells=200,                     # Cells per simulation
    num_steps=100,                     # Forward steps to simulate
    device=device,                     # Torch device
    tp_subset=0,                       # Start from timepoint 0 (or None for all)
    celltype_subset="progenitor"       # Start from specific cell type (or None)
)

# all_sims: list of [num_sims] arrays, each [num_steps+1, num_cells, num_pcs]
print(f"Number of simulations: {len(all_sims)}")
print(f"Simulation shape: {all_sims[0].shape}")
# Example: (101, 200, 50) for 100 steps, 200 cells, 50 PCs
```

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

### Simulate cell trajectories from all cells

Source: https://context7.com/gifford-lab/prescient/llms.txt

Simulates cell trajectories forward in time from all cells using a trained PRESCIENT model. Outputs simulation results to a specified directory.

```bash
prescient simulate_trajectories \
  -i /path/to/data.pt \
  --model_path /path/to/model_dir/ \
  --seed 1 \
  --epoch 002500 \
  --num_sims 10 \
  --num_cells 200 \
  -o /path/to/output/
```

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

### Initialize and Use AutoGenerator Model

Source: https://context7.com/gifford-lab/prescient/llms.txt

Configure, load, and utilize the AutoGenerator neural network to compute potential energy, drift, and simulate state transitions.

```python
import torch
from types import SimpleNamespace
from prescient.train.model import AutoGenerator

# Configure model
config = SimpleNamespace(
    x_dim=50,              # Input dimension (number of PCs)
    k_dim=500,             # Hidden layer dimension
    layers=2,              # Number of hidden layers
    activation='softplus'  # Activation function: 'softplus', 'relu', or 'none'
)

# Initialize model
model = AutoGenerator(config)
print(model)

# Load trained model weights
device = torch.device('cuda:0' if torch.cuda.is_available() else 'cpu')
checkpoint = torch.load('train.epoch_002500.pt', map_location=device)
model.load_state_dict(checkpoint['model_state_dict'])
model.to(device)

# Compute potential energy for cell states
x = torch.randn(100, 50).to(device)  # 100 cells, 50 PCs
potential = model._pot(x)             # Shape: (100, 1)
print(f"Potential shape: {potential.shape}")

# Compute drift (negative gradient of potential)
drift = model._drift(x)               # Shape: (100, 50)
print(f"Drift shape: {drift.shape}")

# Simulate one step forward
dt = 0.1                              # Time step
z = torch.randn_like(x) * 0.5         # Noise with std=0.5
x_next = model._step(x, dt=dt, z=z)   # Shape: (100, 50)
print(f"Next state shape: {x_next.shape}")
```

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

### Train PRESCIENT model with default parameters

Source: https://context7.com/gifford-lab/prescient/llms.txt

Trains the PRESCIENT neural network model using default hyperparameters. Requires processed data as input and specifies an output directory for experiments.

```bash
prescient train_model \
  -i /path/to/data.pt \
  --out_dir /path/to/experiments/ \
  --seed 2 \
  --gpu 0
```

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

### Train PRESCIENT model with custom hyperparameters

Source: https://context7.com/gifford-lab/prescient/llms.txt

Trains the PRESCIENT model with user-defined hyperparameters for fine-tuning. Allows customization of learning rates, epochs, dimensions, and more.

```bash
prescient train_model \
  -i /path/to/data.pt \
  --out_dir /path/to/experiments/ \
  --weight_name "kegg_growth" \
  --k_dim 500 \
  --layers 2 \
  --activation softplus \
  --pretrain_epochs 500 \
  --train_epochs 2500 \
  --train_lr 0.01 \
  --train_dt 0.1 \
  --train_sd 0.5 \
  --train_tau 1e-6 \
  --train_batch 0.1 \
  --train_clip 0.25 \
  --save 100 \
  --seed 2 \
  --gpu 0
```

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

### Process data with growth weights

Source: https://github.com/gifford-lab/prescient/blob/master/notebooks/estimate-growth-rates.ipynb

Executes the prescient process_data command to incorporate growth weights into the dataset.

```bash
prescient process_data -d data/Veres2019/Stage_5.Seurat.csv -m data/Veres2019/GSE114412_Stage_5.all.cell_metadata.csv --growth_path data/Veres2019/growth-kegg.pt -o './' --tp_col 'CellWeek' --celltype_col 'Assigned_cluster'
```

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

### Simulate cell trajectories from specific cell population

Source: https://context7.com/gifford-lab/prescient/llms.txt

Simulates cell trajectories forward in time from a specific cell population (e.g., progenitor cells) using a trained PRESCIENT model. Allows control over simulation steps and number of simulations.

```bash
prescient simulate_trajectories \
  -i /path/to/data.pt \
  --model_path /path/to/model_dir/ \
  --seed 1 \
  --epoch 002500 \
  --num_sims 50 \
  --num_cells 500 \
  --num_steps 100 \
  --tp_subset 0 \
  --celltype_subset "progenitor" \
  --gpu 0 \
  -o /path/to/simulations/
```

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

### Compute Growth Weights

Source: https://github.com/gifford-lab/prescient/blob/master/notebooks/estimate-growth-rates.ipynb

Calculates growth weights using PRESCIENT's utility function with specified birth and death gene sets.

```python
g, g_l=prescient.utils.get_growth_weights(xs, xp_, metadata, tp_col="CellWeek", genes=list(expr.columns), 
                   birth_gst="Veres2019/hs_birth_msigdb_kegg.csv",
                   death_gst="Veres2019/hs_death_msigdb_kegg.csv",
                   outfile="Veres2019/tutorial-example-growth-kegg.pt"
                  )
```

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

### Compute UMAP for growth visualization

Source: https://github.com/gifford-lab/prescient/blob/master/notebooks/estimate-growth-rates.ipynb

Initializes and fits a UMAP model to the cell data for visualization purposes.

```python
um = umap.UMAP(n_components = 2, metric = 'euclidean', n_neighbors = 30)
xu = um.fit_transform(xp_)
```

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

### Process scRNA-seq data

Source: https://github.com/gifford-lab/prescient/blob/master/docs/quickstart.html

Estimates growth rates and generates a PRESCIENT training object from input data and metadata.

```bash
prescient process_data -d /path/to/your_data.csv -o /path/for/output/ -m /path/to/metadata.csv --tp_col "timepoint colname" --celltype_col "annotation colname" --growth_path /path/to/growth_weights.pt
```

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

### PRESCIENT CLI: process_data

Source: https://context7.com/gifford-lab/prescient/llms.txt

Converts raw scRNA-seq data into a PRESCIENT-compatible torch file for training. It performs PCA dimensionality reduction, UMAP visualization, and incorporates pre-computed cell growth weights.

```APIDOC
## prescient process_data

### Description
Converts raw scRNA-seq data into a PRESCIENT-compatible torch file for training. The command performs PCA dimensionality reduction and UMAP visualization, and incorporates pre-computed cell growth weights.

### Method
CLI Command

### Endpoint
N/A (CLI Tool)

### Parameters
#### Path Parameters
- **-d** (string) - Required - Path to expression data (CSV) or AnnData file (h5ad).
- **-o** (string) - Required - Path to output directory.

#### Query Parameters
- **-m** (string) - Optional - Path to metadata CSV file (if -d is CSV).
- **--tp_col** (string) - Required - Column name for timepoint in metadata or expression data.
- **--celltype_col** (string) - Required - Column name for cell type in metadata or expression data.
- **--growth_path** (string) - Optional - Path to pre-computed growth weights file (.pt).
- **--num_pcs** (integer) - Optional - Number of principal components for PCA (default: 50).
- **--num_neighbors_umap** (integer) - Optional - Number of neighbors for UMAP visualization (default: 10).
- **--fix_non_consecutive** - Optional - Flag to fix non-consecutive timepoints.

### Request Example
```bash
# Process single-cell expression data from CSV with metadata
prescient process_data \
  -d /path/to/expression.csv \
  -m /path/to/metadata.csv \
  -o /path/to/output/ \
  --tp_col "timepoint" \
  --celltype_col "cell_type" \
  --growth_path /path/to/growth_weights.pt \
  --num_pcs 50 \
  --num_neighbors_umap 10

# Process from h5ad (AnnData) file
prescient process_data \
  -d /path/to/data.h5ad \
  -o /path/to/output/ \
  --tp_col "day" \
  --celltype_col "cluster" \
  --growth_path /path/to/growth_weights.pt \
  --fix_non_consecutive
```

### Response
N/A (CLI Tool output to file)
```

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

### Run perturbation analysis

Source: https://github.com/gifford-lab/prescient/blob/master/docs/quickstart.html

Simulates trajectories for perturbed gene expression states to compare against unperturbed cells.

```bash
prescient perturbation_analysis -i /path/to/data.pt -p 'GENE1,GENE2,GENE3' -z 5 --model_path /path/to/trained/model_directory --seed 2 -o /path/to/output_dir
```

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

### PRESCIENT CLI: perturbation_analysis

Source: https://context7.com/gifford-lab/prescient/llms.txt

Simulates the effect of gene perturbations on cell trajectories by comparing perturbed vs unperturbed simulations.

```APIDOC
## prescient perturbation_analysis

### Description
Simulates the effect of gene perturbations on cell trajectories by comparing perturbed vs unperturbed simulations.

### Method
CLI Command

### Endpoint
N/A (CLI Tool)

### Parameters
#### Path Parameters
- **-i** (string) - Required - Path to processed data file (.pt).
- **--model_path** (string) - Required - Path to the directory containing the trained model.
- **-o** (string) - Required - Path to output directory for perturbation analysis results.

#### Query Parameters
- **-p** (string) - Required - Gene(s) to perturb. Comma-separated for multiple genes (no spaces).
- **-z** (float) - Required - Magnitude of perturbation (e.g., fold change).
- **--seed** (integer) - Optional - Random seed for reproducibility (default: None).
- **--epoch** (string) - Required - Epoch number of the trained model to use (e.g., '002500').
- **--num_sims** (integer) - Optional - Number of simulations to run per cell (default: 10).
- **--num_cells** (integer) - Optional - Number of cells to simulate from (default: 200).
- **--num_steps** (integer) - Optional - Number of simulation steps (default: None, inferred from model).
- **--num_pcs** (integer) - Optional - Number of principal components to use for analysis (default: 50).
- **--tp_subset** (integer) - Optional - Subset of timepoints to start simulations from (default: None).
- **--celltype_subset** (string) - Optional - Subset of cell types to start simulations from (default: None).
- **--gpu** (integer) - Optional - GPU device ID to use (default: None).

### Request Example
```bash
# Single gene perturbation
prescient perturbation_analysis \
  -i /path/to/data.pt \
  --model_path /path/to/model_dir/ \
  -p "SOX2" \
  -z 5.0 \
  --seed 1 \
  --epoch 002500 \
  --num_sims 10 \
  --num_cells 200 \
  --num_pcs 50 \
  -o /path/to/output/

# Multiple gene perturbation (comma-separated, no spaces)
prescient perturbation_analysis \
  -i /path/to/data.pt \
  --model_path /path/to/model_dir/ \
  -p "NEUROG3,PAX4,NKX2-2" \
  -z 3.0 \
  --seed 1 \
  --epoch 002500 \
  --num_sims 20 \
  --num_cells 300 \
  --num_steps 50 \
  --num_pcs 50 \
  --tp_subset 0 \
  --celltype_subset "stem_cell" \
  --gpu 0 \
  -o /path/to/perturbations/
```

### Response
N/A (CLI Tool output to file)
```

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

### Data Input Specifications

Source: https://github.com/gifford-lab/prescient/blob/master/docs/file_formats.md

Details on the required structure for normalized expression and metadata files used by PRESCIENT.

```APIDOC
## Data Input Specifications

### Description
PRESCIENT requires normalized gene expression data and associated metadata (time-points and cell types). Inputs can be provided as .csv, .tsv, .txt, .h5ad, or .rds files.

### Normalized Expression Format
- **id** (string) - Cell identifier
- **gene_n** (float) - Normalized expression value for gene n

### Metadata Format
- **id** (string) - Cell identifier
- **timepoint** (integer) - Time point label
- **cell_type** (string) - Cell type annotation
```

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

### Compute PCA and Growth Weights

Source: https://context7.com/gifford-lab/prescient/llms.txt

Perform PCA on expression data and calculate cell growth weights using birth and death gene signatures.

```python
# Compute PCA
pca = sklearn.decomposition.PCA(n_components=30)
xp = pca.fit_transform(xs)

# Compute growth weights using birth/death gene signatures
g, g_l = prescient.utils.get_growth_weights(
    x=xs,                                          # Scaled expression DataFrame
    xp=xp,                                         # PCA-transformed expression
    metadata=metadata,                             # Cell metadata DataFrame
    tp_col="timepoint",                            # Column name for timepoints
    genes=list(expr.columns),                      # List of gene names
    birth_gst="hs_birth_msigdb_kegg.csv",          # Path to birth signature genes
    death_gst="hs_death_msigdb_kegg.csv",          # Path to death signature genes
    outfile="growth_weights.pt",                   # Output torch file path
    n_neighbors=20,                                # Neighbors for smoothing
    beta=0.1,                                      # Smoothing parameter
    L0=0.3,                                        # Growth baseline
    L=1.1,                                         # Growth scale
    k=0.001                                        # Growth rate constant
)

# g: numpy array of growth rates per cell
# g_l: list of growth rates split by timepoint
print(f"Growth rates shape: {g.shape}")
print(f"Number of timepoints: {len(g_l)}")
```

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

### Python API: prescient.utils.get_growth_weights

Source: https://context7.com/gifford-lab/prescient/llms.txt

Estimates cell proliferation/growth rates from gene expression using KEGG pathway annotations. Growth weights are required for training and account for cell division during differentiation.

```APIDOC
## prescient.utils.get_growth_weights

### Description
Estimates cell proliferation/growth rates from gene expression using KEGG pathway annotations. Growth weights are required for training and account for cell division during differentiation.

### Method
Python Function

### Endpoint
N/A (Python Function)

### Parameters
This function does not have explicit parameters listed in the provided text. It likely operates on data loaded within the script context.

### Request Example
```python
import prescient.utils
import pandas as pd
import sklearn.preprocessing
import sklearn.decomposition

# Load expression data and metadata
expr = pd.read_csv("expression.csv", index_col=0)
metadata = pd.read_csv("metadata.csv", index_col=0)

# Scale expression for PCA
scaler = sklearn.preprocessing.StandardScaler()
xs = pd.DataFrame(
    scaler.fit_transform(expr),
    index=expr.index,
    columns=expr.columns
)

# Assuming get_growth_weights is called here with appropriate arguments
# growth_weights = prescient.utils.get_growth_weights(xs, metadata, ...)
```

### Response
- **growth_weights** (object) - Estimated cell growth weights.
```

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

### Input Metadata Format

Source: https://context7.com/gifford-lab/prescient/llms.txt

Defines the required format for input metadata, which must include 'timepoint' (integer) and 'cell_type' (string) columns.

```text
# metadata.csv format
id,timepoint,cell_type
cell_1,0,undifferentiated
cell_2,1,neutrophil
cell_3,2,monocyte
```

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

### Process scRNA-seq data from h5ad

Source: https://context7.com/gifford-lab/prescient/llms.txt

Converts raw scRNA-seq data from an h5ad (AnnData) file into a PRESCIENT-compatible torch file. Handles non-consecutive timepoints if specified.

```bash
prescient process_data \
  -d /path/to/data.h5ad \
  -o /path/to/output/ \
  --tp_col "day" \
  --celltype_col "cluster" \
  --growth_path /path/to/growth_weights.pt \
  --fix_non_consecutive
```

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

### Train ANN Index for Cell Classification

Source: https://context7.com/gifford-lab/prescient/llms.txt

Builds an Approximate Nearest Neighbor (ANN) index for classifying simulated cells back to observed cell types based on their PCA coordinates. Requires 'data.pt' and 'simulation.pt' to be loaded. The index maps PCA space to cell types.

```python
import torch
import numpy as np
from annoy import AnnoyIndex
from collections import Counter
import prescient.utils

# Load data and simulations
data_pt = torch.load('data.pt')
sim_pt = torch.load('simulation.pt')

# Build ANN index from training data
ann = prescient.utils.train_ann(data_pt)
# Saves index that maps PCA space to cell types

# Manual cell classification using Annoy
xp = data_pt["xp"]
celltype = data_pt["celltype"]
n_neighbors = 10

# Get simulated cell coordinates at final timepoint
final_step_coords = sim_pt["sims"][0][-1]  # [num_cells, num_pcs]

# Classify each simulated cell
predicted_types = []
for i in range(final_step_coords.shape[0]):
    # Find nearest neighbors in reference data
    neighbor_indices = ann.get_nns_by_vector(final_step_coords[i], n_neighbors)
    neighbor_types = [celltype[idx] for idx in neighbor_indices]
    # Majority vote
    most_common = Counter(neighbor_types).most_common(1)[0][0]
    predicted_types.append(most_common)

# Count fate predictions
 fate_distribution = Counter(predicted_types)
print("Predicted fate distribution:")
for cell_type, count in fate_distribution.most_common():
    print(f"  {cell_type}: {count} ({100*count/len(predicted_types):.1f}%)")
```

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

### Multiple gene perturbation analysis

Source: https://context7.com/gifford-lab/prescient/llms.txt

Simulates the effect of multiple gene perturbations (comma-separated) on cell trajectories. Allows analysis of combinatorial effects on cell differentiation.

```bash
prescient perturbation_analysis \
  -i /path/to/data.pt \
  --model_path /path/to/model_dir/ \
  -p "NEUROG3,PAX4,NKX2-2" \
  -z 3.0 \
  --seed 1 \
  --epoch 002500 \
  --num_sims 20 \
  --num_cells 300 \
  --num_steps 50 \
  --num_pcs 50 \
  --tp_subset 0 \
  --celltype_subset "stem_cell" \
  --gpu 0 \
  -o /path/to/perturbations/
```

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

### Estimate cell growth weights

Source: https://context7.com/gifford-lab/prescient/llms.txt

Estimates cell proliferation/growth rates from gene expression data using KEGG pathway annotations. Growth weights are essential for training PRESCIENT models.

```python
import prescient.utils
import pandas as pd
import sklearn.preprocessing
import sklearn.decomposition

# Load expression data and metadata
expr = pd.read_csv("expression.csv", index_col=0)
metadata = pd.read_csv("metadata.csv", index_col=0)

# Scale expression for PCA
scaler = sklearn.preprocessing.StandardScaler()
xs = pd.DataFrame(
    scaler.fit_transform(expr),
    index=expr.index,
    columns=expr.columns
)

```

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

### Process scRNA-seq data from CSV

Source: https://context7.com/gifford-lab/prescient/llms.txt

Converts raw scRNA-seq expression and metadata from CSV files into a PRESCIENT-compatible torch file. Performs PCA and UMAP, and incorporates pre-computed cell growth weights.

```bash
prescient process_data \
  -d /path/to/expression.csv \
  -m /path/to/metadata.csv \
  -o /path/to/output/ \
  --tp_col "timepoint" \
  --celltype_col "cell_type" \
  --growth_path /path/to/growth_weights.pt \
  --num_pcs 50 \
  --num_neighbors_umap 10
```

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

### PRESCIENT CLI: train_model

Source: https://context7.com/gifford-lab/prescient/llms.txt

Trains the PRESCIENT neural network model on processed scRNA-seq data. The model learns a potential function that captures cell state dynamics.

```APIDOC
## prescient train_model

### Description
Trains the PRESCIENT neural network model on processed scRNA-seq data. The model learns a potential function that captures cell state dynamics through pretraining with contrastive divergence followed by optimal transport-based training.

### Method
CLI Command

### Endpoint
N/A (CLI Tool)

### Parameters
#### Path Parameters
- **-i** (string) - Required - Path to processed data file (.pt).
- **--out_dir** (string) - Required - Directory to save experiment outputs.

#### Query Parameters
- **--seed** (integer) - Optional - Random seed for reproducibility (default: None).
- **--gpu** (integer) - Optional - GPU device ID to use (default: None).
- **--weight_name** (string) - Optional - Name of pre-trained weights to load (default: None).
- **--k_dim** (integer) - Optional - Dimensionality of the latent space (default: 100).
- **--layers** (integer) - Optional - Number of layers in the neural network (default: 2).
- **--activation** (string) - Optional - Activation function for hidden layers (default: 'softplus').
- **--pretrain_epochs** (integer) - Optional - Number of epochs for pretraining (default: 500).
- **--train_epochs** (integer) - Optional - Number of epochs for main training (default: 2500).
- **--train_lr** (float) - Optional - Learning rate for the optimizer (default: 0.001).
- **--train_dt** (float) - Optional - Time step for ODE solver (default: 0.1).
- **--train_sd** (float) - Optional - Noise level for ODE solver (default: 0.5).
- **--train_tau** (float) - Optional - Time constant for ODE solver (default: 1e-6).
- **--train_batch** (float) - Optional - Batch size as a fraction of total cells (default: 0.1).
- **--train_clip** (float) - Optional - Gradient clipping value (default: 0.25).
- **--save** (integer) - Optional - Save model checkpoint every N epochs (default: 100).

### Request Example
```bash
# Train PRESCIENT model with default parameters
prescient train_model \
  -i /path/to/data.pt \
  --out_dir /path/to/experiments/ \
  --seed 2 \
  --gpu 0

# Train with custom hyperparameters
prescient train_model \
  -i /path/to/data.pt \
  --out_dir /path/to/experiments/ \
  --weight_name "kegg_growth" \
  --k_dim 500 \
  --layers 2 \
  --activation softplus \
  --pretrain_epochs 500 \
  --train_epochs 2500 \
  --train_lr 0.01 \
  --train_dt 0.1 \
  --train_sd 0.5 \
  --train_tau 1e-6 \
  --train_batch 0.1 \
  --train_clip 0.25 \
  --save 100 \
  --seed 2 \
  --gpu 0
```

### Response
N/A (CLI Tool output to file)
```

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

### Load Metadata

Source: https://github.com/gifford-lab/prescient/blob/master/notebooks/estimate-growth-rates.ipynb

Reads the cell metadata CSV file into a pandas DataFrame.

```python
metadata = pd.read_csv("Veres2019/GSE114412_Stage_5.all.cell_metadata.csv", index_col = 0)
metadata.head()
```

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

### Load Expression Data

Source: https://github.com/gifford-lab/prescient/blob/master/notebooks/estimate-growth-rates.ipynb

Reads the expression CSV file into a pandas DataFrame.

```python
expr = pd.read_csv("Veres2019/Stage_5.Seurat.csv", index_col=0)
expr.head()
```

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

### Scale Data for PCA

Source: https://github.com/gifford-lab/prescient/blob/master/notebooks/estimate-growth-rates.ipynb

Standardizes the expression data using sklearn's StandardScaler.

```python
scaler = sklearn.preprocessing.StandardScaler()
xs = pd.DataFrame(scaler.fit_transform(expr), index = expr.index, columns = expr.columns)
```

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

### Perform PCA

Source: https://github.com/gifford-lab/prescient/blob/master/notebooks/estimate-growth-rates.ipynb

Reduces dimensionality of the scaled expression data to 30 components.

```python
pca = sklearn.decomposition.PCA(n_components = 30)
xp_ = pca.fit_transform(xs)
```

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

### PRESCIENT Data Object Structure

Source: https://context7.com/gifford-lab/prescient/llms.txt

Illustrates the structure of the processed PRESCIENT data object saved as 'data.pt'. This object contains all necessary data for training and simulation, including expression, gene names, cell types, timepoints, PCA, and UMAP coordinates.

```python
import torch

# Load PRESCIENT data object
data_pt = torch.load('data.pt')

# Available keys and their contents:
print(data_pt.keys())
# dict_keys(['data', 'genes', 'celltype', 'tps', 'x', 'xp', 'xu', 'y', 'pca', 'um', 'w'])

# data: numpy array of normalized expression (n_cells x n_genes)
# genes: list of gene names
# celltype: list of cell type labels per cell
# tps: numpy array of timepoint assignments per cell
# x: list of torch tensors of scaled expression by timepoint
# xp: list of torch tensors of PCA coordinates by timepoint
# xu: list of torch tensors of UMAP coordinates by timepoint
# y: list of unique timepoints
# pca: fitted sklearn PCA object
# um: fitted UMAP object
# w: list of growth weight arrays by timepoint
```

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

### Single gene perturbation analysis

Source: https://context7.com/gifford-lab/prescient/llms.txt

Simulates the effect of a single gene perturbation on cell trajectories. Compares perturbed vs. unperturbed simulations to analyze differentiation outcomes.

```bash
prescient perturbation_analysis \
  -i /path/to/data.pt \
  --model_path /path/to/model_dir/ \
  -p "SOX2" \
  -z 5.0 \
  --seed 1 \
  --epoch 002500 \
  --num_sims 10 \
  --num_cells 200 \
  --num_pcs 50 \
  -o /path/to/output/
```

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

### PRESCIENT Torch Object Structure

Source: https://github.com/gifford-lab/prescient/blob/master/docs/file_formats.md

The structure of the serialized torch object generated by the 'prescient process_data' command.

```APIDOC
## PRESCIENT Torch Object

### Description
The `prescient process_data` command generates a serialized dictionary (.pt file) containing the following keys:

- **data** (ndarray) - Normalized expression
- **celltype** (list) - Cell type labels
- **genes** (list) - Gene features
- **tps** (list) - Timepoint assignments
- **x** (tensor) - Normalized expression split by timepoint
- **xp** (tensor) - Cell PCs split by timepoint
- **xu** (tensor) - Cell UMAPs split by timepoint
- **pca** (object) - Fitted PCA object
- **um** (object) - Fitted UMAP object
- **y** (list) - Timepoints
- **w** (tensor) - Pre-computed growth weights
```

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

### Input Expression Data Format

Source: https://context7.com/gifford-lab/prescient/llms.txt

Specifies the format for input gene expression data. PRESCIENT accepts normalized (not scaled) data in CSV, TSV, TXT, or H5AD formats, with an expression matrix of n_cells x n_genes.

```text
# expression.csv format
id,gene_1,gene_2,gene_3,...,gene_n
cell_1,0.0,0.121,0.0,...,0.0
cell_2,0.234,0.0,0.0,...,0.0
cell_3,0.0,0.0,0.0,...,1.2
```

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

### Plot growth scores on UMAP

Source: https://github.com/gifford-lab/prescient/blob/master/notebooks/estimate-growth-rates.ipynb

Generates a scatter plot of growth scores mapped onto the UMAP coordinates.

```python
fig, ax = plt.subplots(figsize = (6,6))

c = np.exp(g)
ci = np.argsort(c)
sax = ax.scatter(-xu[ci,0], xu[ci,1], s = 1, c = c[ci])

plt.colorbar(sax, shrink = 0.9)
```

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

### Apply Gene Perturbations with Z-Score

Source: https://context7.com/gifford-lab/prescient/llms.txt

Applies gene perturbations to expression data by setting specified genes to a target z-score value. This is useful for in silico perturbation experiments. Ensure data.pt is loaded and contains 'genes', 'data', and 'pca'.

```python
import torch
import numpy as np
from prescient.perturb.pert import z_score_perturbation

# Load data
data_pt = torch.load('data.pt')
genes = data_pt["genes"].tolist()
expr = data_pt["data"]
pca = data_pt["pca"]

# Apply perturbation to specific genes
perturb_genes = "NEUROG3,PAX4"  # Comma-separated gene names
z_score = 5.0                   # Perturbation magnitude (z-score)

xp_perturbed = z_score_perturbation(
    genes=genes,                # List of all gene names
    perturb_genes=perturb_genes,  # Genes to perturb (comma-separated string)
    x=expr,                     # Original expression matrix
    pca=pca,                    # Fitted PCA object
    z_score=z_score             # Target z-score value
)

# Limit to desired number of PCs
num_pcs = 50
xp_perturbed = xp_perturbed[:, 0:num_pcs]
print(f"Perturbed PCA shape: {xp_perturbed.shape}")

# Compare with unperturbed
xp_original = pca.transform(expr)[:, 0:num_pcs]
diff = np.mean(np.abs(xp_perturbed - xp_original), axis=0)
print(f"Mean absolute difference by PC: {diff[:5]}")
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.