FAQ

Frequently Asked Questions

Installation

Q: Which Python version should I use?

A: Python 3.8 or higher is required. We recommend Python 3.10 for best compatibility.

Q: Do I need a GPU?

A: No, but GPU acceleration (CUDA) can speed up network inference and Jacobian computation by 10-100×.

Q: How do I install igraph?

A: See Installation for platform-specific instructions. The package works fine without it, but igraph provides significant speedup for large networks.

Data Requirements

Q: What data do I need?

A: You need:

  • Single-cell RNA-seq data in AnnData format

  • RNA velocity computed (e.g., with scVelo)

  • Cell type annotations

  • Highly variable genes selected (50-200 recommended)

Q: Can I use data without RNA velocity?

A: No, RNA velocity is required for network inference. Use scVelo or velocyto to compute it first.

Q: How many genes should I use?

A: We recommend 50-200 highly variable genes for computational efficiency and interpretability.

Analysis

Q: How long does analysis take?

A: On a dataset with 10,000 cells and 100 genes:

  • Network inference: 5-30 minutes (CPU) or 1-5 minutes (GPU)

  • Energy computation: <1 minute

  • Jacobian analysis: 10-60 minutes (CPU) or 2-10 minutes (GPU)

Q: My network inference is slow. How can I speed it up?

A: Try:

  • Use device='cuda' for GPU acceleration

  • Reduce n_epochs (1000 is usually sufficient)

  • Use fewer genes

  • Increase learning_rate slightly

Q: How do I interpret energy values?

A: Lower energy indicates more stable states (attractors). High energy indicates unstable or transitional states.

Q: What does a positive Jacobian eigenvalue mean?

A: It indicates instability in that direction - the cell state wants to move away from its current position.

Memory Issues

Q: I’m running out of memory when computing Jacobians. What should I do?

A: Use HDF5 storage:

sch.tl.compute_jacobians(adata, device='cuda')
sch.tl.save_jacobians(adata, 'jacobians.h5')
# This removes Jacobians from memory

Q: Can I process clusters separately?

A: Yes, process one cluster at a time to save memory.

Results

Q: How do I save my results?

A: All results are stored in the AnnData object. Save it with:

adata.write_h5ad('results.h5ad')

Q: Where are the interaction matrices stored?

A: In adata.varp['W_{cluster}'] for each cluster.

Q: How do I export networks for Cytoscape?

A: Use get_network_links():

links = sch.tl.get_network_links(
    adata, cluster_key='cell_type', return_format='dataframe'
)
links.to_csv('network_edges.csv', index=False)

Troubleshooting

Q: Import error: “No module named ‘scHopfield’”

A: Make sure scHopfield is installed:

pip install -e .

Q: “RuntimeError: CUDA out of memory”

A: Reduce batch size, use fewer genes, or switch to CPU with device='cpu'.

Q: Network inference gives NaN values

A: Try:

  • Reduce learning_rate

  • Check that velocity values are not all zero

  • Ensure proper normalization of input data

Contributing

Q: How can I contribute to scHopfield?

A: See Contributing for guidelines.

Q: I found a bug. Where do I report it?

A: Open an issue on GitHub: https://github.com/Bernaljp/scHopfield/issues

Still Have Questions?