Quick Start

This guide will walk you through a basic scHopfield analysis workflow.

Basic Workflow

Import Libraries

import scHopfield as sch
import scanpy as sc
import numpy as np

Load Data

Load your single-cell data with RNA velocity computed:

# Load your data
adata = sc.read_h5ad('data.h5ad')

# Required layers and annotations:
# - adata.layers['Ms'] - spliced counts
# - adata.layers['velocity_S'] - RNA velocity
# - adata.var['gamma'] - degradation rates
# - adata.obs['cell_type'] - cell type annotations

1. Preprocessing

Fit sigmoid activation functions to gene expression:

# Select highly variable genes (50-200 recommended)
highly_variable_genes = adata.var['highly_variable'].values

# Fit sigmoid functions
sch.pp.fit_all_sigmoids(adata, genes=highly_variable_genes)

# Compute sigmoid-transformed expression
sch.pp.compute_sigmoid(adata)

2. Network Inference

Learn interaction matrices from RNA velocity:

sch.inf.fit_interactions(
    adata,
    cluster_key='cell_type',
    n_epochs=1000,
    device='cuda'  # or 'cpu'
)

This infers cluster-specific gene regulatory networks stored in adata.varp['W_{cluster}'].

3. Energy Analysis

Compute energy landscapes:

# Compute total energy and components
sch.tl.compute_energies(adata, cluster_key='cell_type')

# Correlate energies with gene expression
sch.tl.energy_gene_correlation(adata, cluster_key='cell_type')

4. Network Analysis

Analyze network topology:

# Compute centrality metrics
sch.tl.compute_network_centrality(adata, cluster_key='cell_type')

# Eigenvalue decomposition
sch.tl.compute_eigenanalysis(adata, cluster_key='cell_type')

# Compare networks across cell types
sch.tl.network_correlations(adata, cluster_key='cell_type')

5. Stability Analysis

Compute Jacobian matrices and stability metrics:

# Compute Jacobian eigenvalues
sch.tl.compute_jacobians(
    adata,
    cluster_key='cell_type',
    device='cuda'
)

# Compute summary statistics
sch.tl.compute_jacobian_stats(adata)

# Save to disk (optional, to save memory)
sch.tl.save_jacobians(adata, 'jacobians.h5')

6. Visualization

Generate plots:

# Energy landscape
sch.pl.plot_energy_landscape(adata, cluster='HSC')

# Interaction matrix
sch.pl.plot_interaction_matrix(adata, cluster='HSC', top_n=30)

# GRN network graph
sch.pl.plot_grn_network(adata, cluster='HSC', topn=50)

# Jacobian eigenvalue spectra
sch.pl.plot_jacobian_eigenvalue_spectrum(
    adata,
    cluster_key='cell_type'
)

# Energy distributions
sch.pl.plot_energy_boxplots(
    adata,
    cluster_key='cell_type'
)

7. Dynamics Simulation

Simulate gene expression trajectories:

# Simulate from a cell's initial state
trajectory = sch.dyn.simulate_trajectory(
    adata,
    cluster='HSC',
    cell_idx=0,
    t_span=np.linspace(0, 10, 100)
)

# Plot trajectory
sch.pl.plot_trajectory(trajectory, np.linspace(0, 10, 100))

Advanced: Perturbation Experiments

Simulate gene knockouts or overexpression:

# Simulate GATA1 knockout
perturbed = sch.dyn.simulate_perturbation(
    adata,
    cluster='HSC',
    cell_idx=0,
    gene_perturbations={'GATA1': 0.0},  # knockout
    t_span=np.linspace(0, 20, 200)
)

# Simulate GATA1 overexpression
overexpressed = sch.dyn.simulate_perturbation(
    adata,
    cluster='HSC',
    cell_idx=0,
    gene_perturbations={'GATA1': 10.0},  # overexpression
    t_span=np.linspace(0, 20, 200)
)

# Compare with wild-type
wt = sch.dyn.simulate_trajectory(
    adata,
    cluster='HSC',
    cell_idx=0,
    t_span=np.linspace(0, 20, 200)
)

Typical Workflow Summary

A complete analysis typically follows this sequence:

  1. Preprocessing → Fit sigmoid activation functions

  2. Network Inference → Learn cluster-specific interaction matrices

  3. Energy Analysis → Compute landscapes and identify driver genes

  4. Network Analysis → Analyze topology via centrality and eigenanalysis

  5. Stability Analysis → Compute Jacobians for local stability

  6. Visualization → Generate publication-ready plots

  7. Dynamics → Simulate trajectories and test perturbations

Each step builds on the previous, with all results stored in the AnnData object for seamless integration.

Next Steps

  • Read the Tutorial for a detailed walkthrough with real data

  • Explore specific analyses in the User Guide

  • Check the Tools (sch.tl) reference for all available functions

  • See Examples for Jupyter notebooks with complete analyses