dspin 1.5.2__tar.gz → 1.5.4__tar.gz

{dspin-1.5.2/dspin.egg-info → dspin-1.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: dspin
-Version: 1.5.2
+Version: 1.5.4
 Summary: Regulatory network models from single-cell perturbation profiling
 Home-page: https://github.com/JialongJiang/DSPIN
 Author: Jialong Jiang
@@ -25,12 +25,24 @@ Requires-Dist: scanpy
 Requires-Dist: tqdm
 Requires-Dist: igraph
 Requires-Dist: leidenalg
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 # D-SPIN: Constructing regulatory network models from scRNA-seq perturbation profiling  
 
 D-SPIN is a computational framework for constructing regulatory network models of genes or gene programs from single-cell RNA-seq profiling of perturbation conditions. D-SPIN integrates information from multiple perturbation conditions for network inference with improved efficienty and accuracy. The regulatory network can be defined on single genes or gene programs (groups of coexpressed genes). The package includes implementation of gene program discovery, network inference, and network analysis. 
 
-If D-SPIN is useful for your research, consider citing "D-SPIN constructs gene regulatory network models from multiplexed scRNA-seq data revealing organizing principles of cellular perturbation response" ([bioRxiv](https://www.biorxiv.org/content/10.1101/2023.04.19.537364)).
+If D-SPIN is useful for your research, consider citing "D-SPIN constructs regulatory network models from scRNA-seq that reveal organizing principles of perturbation response" ([Cell](https://doi.org/10.1016/j.cell.2026.04.028)).
 
 ## Contact 
 

dspin-1.5.4/README.md

@@ -0,0 +1,235 @@
+# DSPIN
+
+Tutorial, code and examples of the D-SPIN framework for the paper "D-SPIN constructs regulatory network models from scRNA-seq that reveal organizing principles of perturbation response" ([Cell](https://doi.org/10.1016/j.cell.2026.04.028))
+
+<div align="center">
+  <img src="figure/readme/Overview_20251110.png" width="800">
+</div>
+
+## Installation
+
+D-SPIN is implemented in Python and MATLAB. The Python package is sufficient for most datasets with <100k cells and a few hundred conditions. The MATLAB implementation is more efficient on large datasets and can be deployed on clusters for parallelization using built-in `parfor`.
+
+Install the Python package:
+
+`pip install dspin`
+
+The MATLAB code is available in the folder `DSPIN_matlab` and is executable after specifying paths to the saved data from the preprocessing with the Python package (see `run_with_matlab=True` below).
+
+## Demos
+
+A tutorial intended for an invited book chapter is available at bioRxiv:
+
+[A guide to D-SPIN: constructing regulatory network models from single-cell RNA-seq perturbation data](https://www.biorxiv.org/content/10.1101/2025.07.28.667326.full).
+
+Two demos of D-SPIN are available on Google Colab:
+
+- **Demo1**: reconstructs a regulatory network from simulated hematopoietic stem cell (HSC) TF expression data under single-gene perturbations simulated with the BEELINE framework (Pratapa et al., *Nat. Methods*, 2020).  
+  [Demo1](https://colab.research.google.com/drive/1Nja8AAcP0L7Ag6DGbyn21SxGafsYX4fA?usp=sharing)
+
+- **Demo2**: reconstructs a regulatory network and response vectors using a subset of the immune dictionary dataset (Cui et al., *Nature*, 2024), where mice were treated with cytokines and lymph nodes were collected and profiled by scRNA-seq.  
+  [Demo2](https://colab.research.google.com/drive/1oLECn3ystwtwfIRiSii9oe92QJ9ac5s1?usp=sharing)
+
+## Dependencies
+
+DSPIN was tested with:
+
+- python (3.9.18)
+- anndata (0.10.3)
+- matplotlib (3.8.2)
+- scanpy (1.9.6)
+- tqdm (4.65.0)
+- leidenalg (0.10.1)
+- igraph (0.10.8)
+
+Note: other versions may work as well.
+
+## Input data
+
+D-SPIN can work with many perturbation types under the assumption that the perturbation conditions share the same core regulatory network:
+
+- **Genetic screens** – Perturb-seq, CRISPR knockdown/activation, RNAi  
+- **Chemical or signaling cues** – drug treatments, growth-factor changes  
+- **Physiological differences** – healthy vs disease, different patients, time courses  
+- **Spatial niches** – local micro-environments from spatial transcriptomics  
+
+Because D-SPIN models the *distribution* of transcriptional states, it is designed for **single-cell RNA-seq** data. The model can also work with bulk RNA-seq data but the performance is limited. 
+
+### AnnData requirements
+
+Minimum fields expected by the examples below:
+
+- `adata.X` — log-normalized (`log1p`) matrix after QC (filter low-quality cells, high mitochondrial content, and typically use HVGs).  
+- `adata.obs['sample_id']` — condition label; cells with the same value form one perturbation group.  
+- `adata.obs['batch']` — batch label; perturbation effects are compared within each batch when controls exist.  
+- `adata.obs['if_control']` — `True` for controls, `False` otherwise.  
+
+Practical guidance:
+- Aim for **≥ 25 cells per condition** when possible.
+- If no explicit controls exist, D-SPIN can still compute responses relative to the global average, but matched controls per batch are preferred.
+
+## Building network models with D-SPIN
+
+### Gene-level network models
+
+```python
+from dspin.dspin import DSPIN
+
+model = DSPIN(adata, save_path, num_spin=adata.shape[1])  # gene-level
+model.network_inference(
+    sample_id_key='sample_id',
+    method='pseudo_likelihood',
+    directed=True,
+    # optional priors / constraints:
+    # sample_list_ordered=None,
+    # perturb_matrix_prior=None,  # shape: (n_genes, n_samples)
+    # prior_network=None,    # binary matrix of likely edges (e.g., motif/ATAC prior)
+    run_with_matlab=False,
+    params={'stepsz': 0.05, 'lambda_l1_j': 0.01}
+)
+model.response_relative_to_control(
+    sample_id_key='sample_id',
+    if_control_key='if_control',
+    batch_key='batch'
+)
+```
+
+**Results saved to `model`:**
+- `model.network` – regulatory weights **J**
+- `model.responses` – responses **h** for each condition
+- `model.relative_responses` – responses relative to control (preferably within each batch)
+
+**Tips**
+- `num_spin=adata.shape[1]` - gene-level network  
+- `directed=True` - only supported with `pseudo_likelihood`  
+- `prior_network` (optional) - prior knowledge on network edges (e.g., TF–motif binding, ATAC-seq data)  
+- `perturb_matrix_prior` (optional) - prior on direct perturbation targets (e.g., Perturb-seq)  
+- `run_with_matlab=True` - write variables to `save_path` for MATLAB inference on large datasets  
+
+---
+
+### Program-level network models
+
+Program-level models first discover gene programs (via consensus oNMF), then infer a network over programs.
+
+```python
+from dspin.dspin import DSPIN
+
+model = DSPIN(adata, save_path, num_spin=20)      # e.g., 20 programs
+model.gene_program_discovery(
+    num_repeat=10,
+    seed=0,
+    cluster_key='cell_type'                       # optional: balance cell types
+)
+model.network_inference(
+    sample_id_key='sample_id',
+    method='mcmc_maximum_likelihood'
+)
+model.response_relative_to_control(
+    sample_id_key='sample_id',
+    if_control_key='if_control',
+    batch_key='batch'
+)
+```
+
+**Extra outputs**
+- Program compositions under `save_path/onmf`
+- Consensus program gene lists under `save_path`
+
+**Tips**
+- A practical heuristic is `num_spin` ≈ 5 × (number of major cell types/clusters), but keep `num_spin ≤ 40` for interpretability.
+- `cluster_key` lets D-SPIN down-sample over-represented cell types before oNMF to reduce overfitting.
+
+---
+
+### Finding gene regulators of programs
+
+Given a program-level model (`model_program`) and a gene-level model (`model_gene`), D-SPIN can regress program activities onto the gene network to nominate regulators.
+
+```python
+# model_program : program-level DSPIN object
+# model_gene    : gene-level   DSPIN object
+model_gene.program_regulator_discovery(
+    model_program.program_representation,
+    sample_id_key='sample_id',
+    params={'stepsz': 0.02, 'lambda_l1_interaction': 0.001}
+)
+```
+
+**Outputs in `model_gene`:**
+- `model_gene.program_interactions` – regression coefficients (gene ↔ program)
+- `model_gene.program_activities` – global activity for each program
+
+**Tips**
+- The two models should be built from `adata` objects with matching `adata.obs` (so each cell aligns between gene- and program-level representations).
+
+---
+
+### Module discovery and visualization (optional)
+
+The package includes helpers for module discovery (Leiden clustering) and plotting.
+
+```python
+import dspin.plot as dp
+
+# Example: program-level network
+G, j_filt = dp.create_undirected_network(
+    model.network,
+    node_names=spin_name,           # list of program (or gene) names
+    thres_strength=0.05
+)
+module_list = dp.compute_modules(G, resolution=1, seed=0)
+
+dp.plot_network_heatmap(j_filt, module_list, spin_name_list=spin_name)
+dp.plot_network_diagram(
+    j_filt, module_list,
+    pos=None,
+    directed=False,
+    weight_thres=0.15,
+    spin_name_list_short=spin_name_short
+)
+dp.plot_response_heatmap(
+    model.relative_responses,
+    module_list,
+    spin_name_list=spin_name,
+    sample_list=model.sample_list
+)
+```
+
+**Tips**
+- `resolution` controls Leiden module granularity (higher - smaller modules).
+- For gene-level models, `spin_name` is typically gene names; for program-level models, use program labels or representative gene names.
+
+## Application to the T cell population of the immune dictionary dataset
+
+<div align="center">
+  <img src="figure/readme/Figure2_immune_dictionary_20250928.png" width="600">
+</div>
+
+<div align="left">
+<b>Figure: Overview and program discovery for the immune dictionary dataset (Cui et al., Nature 2024).</b>
+(A) t-SNE embedding for a subset of cell populations from the immune dictionary dataset. The subset dataset includes CD4, CD8, and regulatory T cells treated by 12 different cytokines, as well as corresponding control samples treated by phosphate-buffered saline (PBS). 
+(B) Heatmaps of gene expression and discretized gene program levels for control and IFN-&alpha;1-treated samples. The gene programs are weighted averages of single-gene expressions that characterize and denoise the major expression pattern of the gene matrix.
+</div>
+<br>
+<div align="center">
+  <img src="figure/readme/Figure3_program_network_20261009.png" width="600">
+</div>
+
+<div align="left">
+<b>Figure: Program-level and gene-level regulatory network inferred by D-SPIN.</b>
+(A) Diagram of D-SPIN-inferred network model on gene programs. The network is partitioned into 4 modules, each associated with a T cell type in the population.
+(B) Heatmap of the program response of each cytokine. Clustering of the response partitions the cytokines into 3 major categories. 
+(C) Diagram of the core subnetwork of the D-SPIN-inferred gene network model. The node sizes scale with the number of identified interactions. The network is partitioned into 4 modules, each primarily composed of genes that have elevated expression in one specific T cell type.
+(D) Interaction diagram for the subnetwork of IFN-&alpha;1/IFN-&beta; and IFN-&gamma; acting on the program P17-IFN-&gamma; response. The D-SPIN model shows that Type I and Type II interferons have different effectors to activate the program.
+</div>
+
+## References
+
+1. Jiang, Jialong, et al. "D-SPIN constructs regulatory network models from scRNA-seq that reveal organizing principles of perturbation response." Cell 189(13):4159-4184.e35 (2026).
+
+2. Jiang, Jialong, and Thomson, Matt. "A guide to D-SPIN: constructing regulatory network models from single-cell RNA-seq perturbation data." bioRxiv (2025).
+
+3. Pratapa, Aditya, et al. "Benchmarking algorithms for gene regulatory network inference from single-cell transcriptomic data." Nature methods 17.2 (2020): 147-154.
+
+4. Cui, Ang, et al. "Dictionary of immune responses to cytokines at single-cell resolution." Nature 625.7994 (2024): 377-384.

{dspin-1.5.2 → dspin-1.5.4}/dspin/compute.py

@@ -413,6 +413,8 @@ def subsample_normalize_gene_matrix(gene_matrix: np.ndarray,
         if method is None:
             gene_matrix_balanced = gene_matrix[np.random.choice(
                 num_cell, num_subsample, replace=False), :]
+            if issparse(gene_matrix_balanced):
+                gene_matrix_balanced = gene_matrix_balanced.toarray()
         else:
             cluster_list, cluster_count = np.unique(cluster_label, return_counts=True)
 
@@ -1343,8 +1345,8 @@ def learn_network_adam(raw_data: Any,
         if if_backtrack:
             print('Backtracking at epoch %d' % counter)
             backtrack_counter += 1
-            cur_j = rec_jmat_all[counter - 1 - backtrack_gap, :, :]
-            cur_h = rec_hvec_all[counter - 1 - backtrack_gap, :, :]
+            cur_j = rec_jmat_all[counter - 1 - backtrack_gap, :, :].copy()
+            cur_h = rec_hvec_all[counter - 1 - backtrack_gap, :, :].copy()
 
             mjj, vjj, mhh, vhh = [log_adam_grad[key][0]
                                   for key in ['mjj', 'vjj', 'mhh', 'vhh']]
@@ -1411,7 +1413,7 @@ def learn_program_regulators(gene_states: List[np.ndarray],
         train_dat.get(key, None) for key in [
             "backtrack_gap", "backtrack_tol"])
 
-    lambda_l1_j, lambda_l2_j = (train_dat.get(key, 0) for key in ["lambda_l1_j", "lambda_l2_j"])
+    lambda_l1_j, lambda_l2_j = (train_dat.get(key, 0) for key in ["lambda_l1_interaction", "lambda_l2_j"])
 
     # Initialize parameters (using zeros)
     cur_interaction = np.zeros((num_gene, num_program))
@@ -1429,6 +1431,7 @@ def learn_program_regulators(gene_states: List[np.ndarray],
     rec_selfh_all = np.zeros((num_epoch, num_program))
     
     rec_grad = np.ones(num_epoch) * np.inf
+    rec_grad_data = np.ones(num_epoch) * np.inf
 
     m_interaction, v_interaction = np.zeros_like(cur_interaction), np.zeros_like(cur_interaction)
     m_selfj, v_selfj = np.zeros_like(cur_selfj), np.zeros_like(cur_selfj)
@@ -1492,6 +1495,8 @@ def learn_program_regulators(gene_states: List[np.ndarray],
         selfj_grad = - np.sum(rec_selfj_grad * samp_weight[:, None], axis=0)
         selfh_grad = - np.sum(rec_selfh_grad * samp_weight[:, None], axis=0)
         
+        # Data-gradient norm for backtracking; the annealed L1 term grows by design and would trigger it
+        rec_grad_data[counter - 1] = np.linalg.norm(interaction_grad)
         if lambda_l1_j > 0:
             interaction_grad += lambda_l1_j * (cur_interaction / l1_base).clip(- 1, 1)
         if lambda_l2_j > 0:
@@ -1522,12 +1527,12 @@ def learn_program_regulators(gene_states: List[np.ndarray],
             pbar.set_postfix({"Network Gradient": f"{rec_grad[counter - 1]:.6f}"})
 
         if_backtrack = False
-        if (counter > backtrack_gap) and (rec_grad[counter - 1] > 1.5 * rec_grad[counter - 1 - backtrack_gap]):
+        if (counter > backtrack_gap) and (rec_grad_data[counter - 1] > 1.5 * rec_grad_data[counter - 1 - backtrack_gap]):
             if_backtrack = True
             
         if (counter > 2 * backtrack_gap) and (counter % backtrack_gap == 0):
-            est_cur_grad = rec_grad[counter - 1 - backtrack_gap: counter - 1].mean()
-            est_prev_grad = rec_grad[counter - 1 - 2 * backtrack_gap: counter - 1 - backtrack_gap].mean()
+            est_cur_grad = rec_grad_data[counter - 1 - backtrack_gap: counter - 1].mean()
+            est_prev_grad = rec_grad_data[counter - 1 - 2 * backtrack_gap: counter - 1 - backtrack_gap].mean()
             
             if est_cur_grad > 1.05 * est_prev_grad:
                 if_backtrack = True
@@ -1535,8 +1540,11 @@ def learn_program_regulators(gene_states: List[np.ndarray],
         if if_backtrack:
             print('Backtracking at epoch %d' % counter)
             backtrack_counter += 1
+            cur_interaction = rec_interaction_all[counter - 1 - backtrack_gap, :, :].copy()
+            cur_selfj = rec_selfj_all[counter - 1 - backtrack_gap, :].copy()
+            cur_selfh = rec_selfh_all[counter - 1 - backtrack_gap, :].copy()
             m_interaction, v_interaction, m_selfj, v_selfj, m_selfh, v_selfh = [log_adam_grad[key][0] for key in ["m_interaction", "v_interaction", "m_selfj", "v_selfj", "m_selfh", "v_selfh"]]
-            counter = counter - backtrack_gap
+            counter = counter - backtrack_gap + 1
             stepsz = stepsz / 4
             if backtrack_counter > backtrack_tol:
                 print(f'Backtracking more than {backtrack_tol} times, stop training.')

{dspin-1.5.2 → dspin-1.5.4}/dspin/dspin.py

@@ -168,7 +168,10 @@ class AbstractDSPIN(ABC):
 
         if clip_percentile < 100:
             for ii in range(onmf_rep_ori.shape[1]):
-                onmf_rep_ori[:, ii] = onmf_rep_ori[:, ii] / np.percentile(onmf_rep_ori[:, ii], clip_percentile)
+                clip_value = np.percentile(onmf_rep_ori[:, ii], clip_percentile)
+                if clip_value == 0:
+                    clip_value = np.max(onmf_rep_ori[:, ii])
+                onmf_rep_ori[:, ii] = onmf_rep_ori[:, ii] / clip_value
             onmf_rep_ori = onmf_rep_ori.clip(0, 1)
 
         onmf_rep_tri = onmf_discretize(onmf_rep_ori, num_init, fig_folder)
@@ -262,7 +265,7 @@ class AbstractDSPIN(ABC):
                           params: dict = None,
                           sample_list_ordered: List[str] = None,
                           prior_network: np.ndarray = None,
-                          perturb_matrix: np.ndarray = None,
+                          perturb_matrix_prior: np.ndarray = None,
                           if_control_key: str = 'if_control',
                           batch_key: str = 'batch',
                           run_with_matlab: bool = False) -> None:
@@ -283,7 +286,7 @@ class AbstractDSPIN(ABC):
             List of ordered sample identifiers. Default is None.
         prior_network : np.ndarray, optional
             Binary matrix of preferred network connectivity from prior knowledge. Default is None.
-        perturb_matrix : np.ndarray, optional
+        perturb_matrix_prior : np.ndarray, optional
             Matrix of putative relative responses to control samples. Default is None.
         if_control_key : str, optional
             Column name in `adata.obs` indicating whether a sample is a control. Default is 'if_control'.
@@ -335,7 +338,7 @@ class AbstractDSPIN(ABC):
             train_dat['j_prior_mask'] = prior_network
             train_dat['lambda_l1_j_prior_mask'] = 0.01
 
-        if perturb_matrix is not None:
+        if perturb_matrix_prior is not None:
             if if_control_key not in self.adata.obs.columns:
                 raise ValueError(f"Column '{if_control_key}' not found in adata.obs.")
             if batch_key not in self.adata.obs.columns:
@@ -348,7 +351,7 @@ class AbstractDSPIN(ABC):
             if_control = np.array([sample_to_control[sample] for sample in sample_list])
             batch_index = np.array([sample_to_batch[sample] for sample in sample_list])
 
-            train_dat['perturb_matrix'] = perturb_matrix
+            train_dat['perturb_matrix'] = perturb_matrix_prior
             train_dat['if_control'] = if_control
             train_dat['batch_index'] = batch_index
             train_dat['lambda_l2_h_rela_prior'] = 0.5
@@ -464,6 +467,7 @@ class GeneDSPIN(AbstractDSPIN):
             if dparams['clip_percentile'] < 100:
                 print(f"Input gene expression seem to be heavy-tailed. Using {dparams['clip_percentile']} percentile for clipping before discretization.")
 
+            np.random.seed(0)
             self.discretize(clip_percentile=dparams['clip_percentile'], 
                             num_init=dparams['num_init'])
 
@@ -491,7 +495,7 @@ class GeneDSPIN(AbstractDSPIN):
         train_dat = {
             'num_epoch': 500,
             'stepsz': 0.01,
-            'lambda_l1_interaction': 0.01,
+            'lambda_l1_interaction': 0.001,
             'rec_gap': 10,
             'backtrack_gap': 40,
             'backtrack_tol': 5
@@ -792,6 +796,9 @@ class ProgramDSPIN(AbstractDSPIN):
             self.discretize(clip_percentile=dparams['clip_percentile'],
                             num_init=dparams['num_init'])
 
+        if mode == 'compute_only':
+            return
+
         num_display_gene = 5
         gene_pd = pd.read_csv(self.gene_program_csv, index_col=None)
         
@@ -802,7 +809,7 @@ class ProgramDSPIN(AbstractDSPIN):
             sub_list_filtered = [gene for gene in sub_list if str(gene) != 'nan']
             top_gene_list_filtered.append(sub_list_filtered)
 
-        program_names = [f'P{ii}-' + ','.join(top_gene_list_filtered[ii]) for ii in range(num_spin)]
+        program_names = [f'P{ii + 1}-' + ','.join(top_gene_list_filtered[ii]) for ii in range(num_spin)]
         self.name_list = program_names
         self.name_list_short = [name.split('-')[0] for name in program_names]
 
@@ -845,6 +852,7 @@ class DSPIN(object):
             warnings.warn("Negative expression detected. Expect normalized log-transformed data.")
 
         # Filtering genes based on the filter_threshold.
+        adata = adata.copy()
         sc.pp.filter_genes(adata, min_cells=adata.shape[0] * filter_threshold)
         print(
             '{} genes have expression in more than {} of the cells'.format(

{dspin-1.5.2 → dspin-1.5.4}/dspin/plot.py

@@ -19,8 +19,11 @@ from scipy.spatial.distance import pdist, squareform
 from scipy.cluster.hierarchy import linkage, leaves_list
 import matplotlib as mpl
 from typing import List, Dict, Optional, Tuple
+import re
 
 
+cmap_hvec = mpl.colors.LinearSegmentedColormap.from_list("", ['#E84B23', '#FFFFFF', '#3285CC'])
+
 def onmf_to_csv(features, gene_name, file_path, thres=0.01, if_write_weights=False):
     """
     Extract gene names in ONMF to CSV.
@@ -74,9 +77,6 @@ def onmf_gene_program_info(features, gene_name, num_gene_show, fig_folder=None):
     gene_name (List[str]): Names of the genes corresponding to feature indices.
     num_gene_show (int): Number of genes to show in the plot.
     fig_folder (str): Folder where the figure will be saved.
-
-    Returns:
-    str: Path of the created figure.
     """
     thres = 0.01
     num_spin = features.shape[0]
@@ -100,10 +100,8 @@ def onmf_gene_program_info(features, gene_name, num_gene_show, fig_folder=None):
     if fig_folder is not None:
         plt.savefig(fig_folder + 'onmf_gene_program_info.png', dpi=300, bbox_inches='tight')
 
-    return(fig_folder + 'onmf_gene_program_info.png')
-
 
-def assign_program_position(onmf_rep_ori, umap_all, repulsion=2):
+def assign_program_position(onmf_rep_ori, umap_all, repulsion=2, if_plot=True):
     """
     Assign the position of gene programs on the UMAP plot.
 
@@ -111,7 +109,8 @@ def assign_program_position(onmf_rep_ori, umap_all, repulsion=2):
     onmf_rep_ori (numpy.ndarray): The gene or gene program representation of the transformed data.
     umap_all (numpy.ndarray): The UMAP coordinates of all cells.
     repulsion (float): The repulsion strength for the layout optimization.
-
+    if_plot (bool): Whether to plot the UMAP plot.
+    
     Returns:
     numpy.ndarray: The assigned positions of gene programs on the UMAP plot.
     """
@@ -133,22 +132,24 @@ def assign_program_position(onmf_rep_ori, umap_all, repulsion=2):
     opt_res = optimize.minimize(layout_loss_fun, program_umap_pos.flatten())
     program_umap_pos = opt_res.x.reshape(- 1, 2)
 
-    sc.set_figure_params(figsize=[4, 4])
-  
-    if umap_all.shape[0] <= 5e4:
-        plt.scatter(umap_all[:, 0], umap_all[:, 1], s=1, c='#bbbbbb', alpha=min(1, 1e4 / umap_all.shape[0]))
-    else:
-        sele_ind = np.random.choice(umap_all.shape[0], size=50000, replace=False).astype(int)
-        plt.scatter(umap_all[sele_ind, 0], umap_all[sele_ind, 1], s=1, c='#bbbbbb', alpha=0.2)
+    if if_plot:
 
-    for ii in range(num_spin):
-        plt.text(program_umap_pos[ii, 0], program_umap_pos[ii, 1], str(ii), fontsize=10)
-    plt.axis('off')
+        sc.set_figure_params(figsize=[4, 4])
+    
+        if umap_all.shape[0] <= 5e4:
+            plt.scatter(umap_all[:, 0], umap_all[:, 1], s=1, c='#bbbbbb', alpha=min(1, 1e4 / umap_all.shape[0]))
+        else:
+            sele_ind = np.random.choice(umap_all.shape[0], size=50000, replace=False).astype(int)
+            plt.scatter(umap_all[sele_ind, 0], umap_all[sele_ind, 1], s=1, c='#bbbbbb', alpha=0.2)
+
+        for ii in range(num_spin):
+            plt.text(program_umap_pos[ii, 0], program_umap_pos[ii, 1], str(ii), fontsize=10)
+        plt.axis('off')
 
     return program_umap_pos
 
 
-def gene_program_on_umap(onmf_rep, umap_all, program_umap_pos, fig_folder=None, subsample=True):
+def gene_program_on_umap(onmf_rep, umap_all, program_umap_pos=None, program_names=None,fig_folder=None, subsample=True):
     """
     Plot gene programs on the UMAP plot.
 
@@ -156,6 +157,7 @@ def gene_program_on_umap(onmf_rep, umap_all, program_umap_pos, fig_folder=None,
     onmf_rep (numpy.ndarray): The gene or gene program representation of the transformed data.
     umap_all (numpy.ndarray): The UMAP coordinates of all cells.
     program_umap_pos (numpy.ndarray): The assigned positions of gene programs on the UMAP plot.
+    program_names (List[str]): The names of gene programs.
     fig_folder (str): The folder where the output figure is saved.
     subsample (bool): Whether to subsample the data for plotting.
 
@@ -165,16 +167,29 @@ def gene_program_on_umap(onmf_rep, umap_all, program_umap_pos, fig_folder=None,
 
     num_spin = onmf_rep.shape[1]
 
-    if subsample:
-        num_subsample = 20000
+    if program_umap_pos is None:
+        program_umap_pos = assign_program_position(onmf_rep, umap_all, if_plot=False)
+
+    if program_names is None:
+        program_names = [str(ii) for ii in range(num_spin)]
+
+    # Check if all program names follow the "P<number>" format
+    match_nums = [re.search(r'\d+', name) for name in program_names]
+    if all(m is not None for m in match_nums):
+        program_order = sorted(range(len(program_names)), key=lambda i: int(match_nums[i].group()))
+    else:
+        program_order = sorted(range(len(program_names)), key=lambda i: program_names[i])
+
+    num_subsample = 20000
+    if subsample & (onmf_rep.shape[0] > num_subsample):
         sub_ind = np.random.choice(onmf_rep.shape[0], num_subsample, replace=False)
         onmf_rep = onmf_rep[sub_ind, :]
         umap_all = umap_all[sub_ind, :]
 
     sc.set_figure_params(figsize=[2, 2])
     fig, grid = sc.pl._tools._panel_grid(0.2, 0.06, ncols=6, num_panels=num_spin)
-    for spin in range(num_spin):
-        ax = plt.subplot(grid[spin])
+    for ind, spin in enumerate(program_order):
+        ax = plt.subplot(grid[ind])
 
         plot_data = onmf_rep[:, spin].copy()
         plot_data /= np.percentile(plot_data, 95)
@@ -182,15 +197,14 @@ def gene_program_on_umap(onmf_rep, umap_all, program_umap_pos, fig_folder=None,
 
         plt.scatter(umap_all[:, 0], umap_all[:, 1], c=plot_data, s=1, 
         alpha=0.5, vmax=1.2, cmap='BuPu', vmin=-0.1)
-        plt.text(program_umap_pos[spin, 0], program_umap_pos[spin, 1], str(spin), fontsize=12, path_effects=[patheffects.withStroke(linewidth=3, foreground='w')])
+        plt.text(program_umap_pos[spin, 0], program_umap_pos[spin, 1], program_names[spin], fontsize=12, path_effects=[patheffects.withStroke(linewidth=3, foreground='w')])
         ax.set_aspect('equal')
         plt.xticks([])
         plt.yticks([])
-        plt.title(spin)
+        plt.title(program_names[spin])
 
     if fig_folder is not None:
         plt.savefig(fig_folder + 'gene_program_on_umap.png', dpi=300, bbox_inches='tight')    
-        return fig_folder + 'gene_program_on_umap.png'
 
 
 def visualize_program_expression(onmf_summary, spin_name, gene_matrix, onmf_rep_tri, fig_folder=None, 
@@ -207,9 +221,6 @@ def visualize_program_expression(onmf_summary, spin_name, gene_matrix, onmf_rep_
     num_gene_select (int): The number of genes to be selected for each gene program. Default is 10.
     n_clusters (int): The number of clusters for KMeans clustering. Default is 5.
     subsample (int): The number cell subsampling for visualization. Default is 10000.
-
-    Returns:
-    str: Path of the created figure.
     """
     # Extracting feature components from the ONMF summary object
     features = onmf_summary.components_
@@ -265,7 +276,6 @@ def visualize_program_expression(onmf_summary, spin_name, gene_matrix, onmf_rep_
 
     if fig_folder is not None:
         plt.savefig(fig_folder + 'gene_program_decomposition.png', bbox_inches='tight')
-        return fig_folder + 'gene_program_decomposition.png'
 
 
 def format_label(label):
@@ -309,6 +319,51 @@ def temporary_spin_name(csv_file, num_gene: int = 4):
     return spin_names_formatted
 
 
+def plot_program_heatmap(onmf_rep: np.ndarray, celltype_label: np.ndarray, program_name: str, fig_folder: Optional[str] = None) -> None:
+
+    """
+    Plot a heatmap of the program expression.
+    
+    Parameters
+    ----------
+    onmf_rep : np.ndarray
+        The program expression.
+    celltype_label : np.ndarray
+        The celltype label.
+    program_name : str
+        The program name.
+    fig_folder : str
+        The folder to save the figure.
+    """
+
+    celltype_label_list = np.unique(celltype_label)
+    num_celltype = len(celltype_label_list)
+    num_program = onmf_rep.shape[1]
+
+    average_onmf_rep = np.zeros((num_celltype, num_program))
+    for ii in range(num_celltype):
+        average_onmf_rep[ii, :] = np.mean(onmf_rep[celltype_label == celltype_label_list[ii], :], axis=0)
+
+    for jj in range(num_program):
+        average_onmf_rep[:, jj] = average_onmf_rep[:, jj] / np.average(average_onmf_rep[:, jj])
+
+    celltype_order = leaves_list(linkage(average_onmf_rep))
+    program_order = leaves_list(linkage(average_onmf_rep.T))
+
+    sc.set_figure_params(figsize=[0.24 * num_celltype, 0.24 * num_program])
+
+    plt.imshow(average_onmf_rep[celltype_order, :][:, program_order].T, cmap='Blues', vmin=0, vmax=2.5, aspect='auto')
+
+    plt.yticks(np.arange(num_program), np.array(program_name)[program_order], fontsize=10); 
+    plt.xticks(np.arange(num_celltype), np.array(celltype_label_list)[celltype_order], fontsize=10, rotation=90); 
+
+    plt.xlabel('Cell types')
+    plt.ylabel('Gene programs')
+
+    if fig_folder is not None:
+        plt.savefig(fig_folder + 'program_heatmap.png')
+
+
 def plot_network_heatmap(j_mat: np.ndarray, 
                        module_list: List[List[int]] = None, 
                        spin_name_list: Optional[List[str]] = None,
@@ -319,7 +374,9 @@ def plot_network_heatmap(j_mat: np.ndarray,
     Parameters
     ----------
     j_mat : np.ndarray
-        The network adjacency matrix.
+        The network adjacency matrix, with rows as regulators and columns as targets (e.g., nx.to_numpy_array
+        of the graph from create_directed_network). model.network is stored as [target, regulator], so pass
+        model.network.T for a directed network.
     modules : List[List[int]]
         List of modules, where each module is a list of node indices.
     spin_name_list : List[str], optional
@@ -338,13 +395,11 @@ def plot_network_heatmap(j_mat: np.ndarray,
     spin_order = [spin for cur_list in module_list for spin in cur_list]
     net_class_len = [len(cur_list) for cur_list in module_list]
     
-    # Create custom colormap
-    cmap_hvec = mpl.colors.LinearSegmentedColormap.from_list("", ['#E84B23', '#FFFFFF', '#3285CC'])
-    
     color_thres = np.percentile(np.abs(j_mat[j_mat != 0]), 95)
 
     # Plot heatmap
-    sc.set_figure_params(figsize=[0.18 * num_spin + 0.5, 0.18 * num_spin])
+    fig_size = np.max([3.7, 0.18 * num_spin])
+    sc.set_figure_params(figsize=[fig_size + 0.5, fig_size])
     plt.imshow(j_mat[:, spin_order][spin_order, :], cmap=cmap_hvec, vmin=- color_thres, vmax=color_thres)
     
     # Add module boundaries
@@ -352,16 +407,19 @@ def plot_network_heatmap(j_mat: np.ndarray,
         plt.axhline(np.sum(net_class_len[:ii]) - 0.5, color='k', linewidth=1)
         plt.axvline(np.sum(net_class_len[:ii]) - 0.5, color='k', linewidth=1)
     
-    fsize = 9
+    fsize = np.max([9, int(fig_size / num_spin * 50)])
 
     # Set labels
     if spin_name_list is not None:
         plt.xticks(np.arange(len(spin_order)), np.array(spin_name_list)[spin_order], rotation=90, fontsize=fsize)
         plt.yticks(np.arange(len(spin_order)), np.array(spin_name_list)[spin_order], fontsize=fsize)
     else:
-        plt.xticks(np.arange(len(spin_order)), [f'P{spin}' for spin in spin_order], rotation=90, fontsize=fsize)
-        plt.yticks(np.arange(len(spin_order)), [f'P{spin}' for spin in spin_order], fontsize=fsize)
-        
+        plt.xticks(np.arange(len(spin_order)), [f'P{spin + 1}' for spin in spin_order], rotation=90, fontsize=fsize)
+        plt.yticks(np.arange(len(spin_order)), [f'P{spin + 1}' for spin in spin_order], fontsize=fsize)
+    
+    plt.xlabel('Targets')
+    plt.ylabel('Regulators')
+
     plt.colorbar(fraction=0.6 / num_spin)
     plt.grid()
     
@@ -369,8 +427,6 @@ def plot_network_heatmap(j_mat: np.ndarray,
     if fig_folder is not None:
         plt.savefig(fig_folder + 'network_heatmap.png', dpi=300, bbox_inches='tight')
     
-    plt.show()
-
 
 def plot_response_heatmap(h_vec: np.ndarray, 
                        module_list: List[List[int]]=None, 
@@ -404,8 +460,6 @@ def plot_response_heatmap(h_vec: np.ndarray,
     net_class_len = [len(cur_list) for cur_list in module_list]
     sample_order = leaves_list(linkage(h_vec.T, method='ward'))
     
-    cmap_hvec = mpl.colors.LinearSegmentedColormap.from_list("", ['#E84B23', '#FFFFFF', '#3285CC'])
-    
     # Plot heatmap
     sc.set_figure_params(figsize=[0.16 * num_spin + 0.5, 0.16 * num_sample])
     plt.imshow(h_vec.T[sample_order, :][:, spin_order], cmap=cmap_hvec, vmin=- 1, vmax=1, aspect='auto')
@@ -418,9 +472,12 @@ def plot_response_heatmap(h_vec: np.ndarray,
     if spin_name_list is not None:
         plt.xticks(np.arange(len(spin_order)), np.array(spin_name_list)[spin_order], rotation=90, fontsize=8)
     else:
-        plt.xticks(np.arange(len(spin_order)), [f'P{spin}' for spin in spin_order], rotation=90, fontsize=8)
+        plt.xticks(np.arange(len(spin_order)), [f'P{spin + 1}' for spin in spin_order], rotation=90, fontsize=8)
     
-    plt.yticks(np.arange(len(sample_order)), np.array(sample_list)[sample_order], fontsize=8)
+    if sample_list is not None:
+        plt.yticks(np.arange(len(sample_order)), np.array(sample_list)[sample_order], fontsize=8)
+    else:
+        plt.yticks(np.arange(len(sample_order)), [f'S{sample + 1}' for sample in sample_order], fontsize=8)
         
     plt.colorbar(fraction=1 / num_spin)
     plt.grid()
@@ -429,11 +486,10 @@ def plot_response_heatmap(h_vec: np.ndarray,
     if fig_folder is not None:
         plt.savefig(fig_folder + 'module_heatmap.png', dpi=300, bbox_inches='tight')
     
-    plt.show()
-
 
 def create_undirected_network(j_mat, node_names, thres_strength=0.05):
 
+    j_mat = j_mat.copy()
     np.fill_diagonal(j_mat, 0)
         
     # Filter weak connections
@@ -450,6 +506,7 @@ def create_undirected_network(j_mat, node_names, thres_strength=0.05):
 
 def create_directed_network(j_mat, node_names,thres_strength=0.05, thres_direction=0.05):
 
+    j_mat = j_mat.copy()
     np.fill_diagonal(j_mat, 0)
 
     num_spin = j_mat.shape[0]
@@ -635,7 +692,9 @@ def plot_network_diagram(j_mat: np.ndarray,
     Parameters
     ----------
     j_mat : np.ndarray
-        The network adjacency matrix.
+        The network adjacency matrix, with rows as regulators and columns as targets (e.g., nx.to_numpy_array
+        of the graph from create_directed_network). model.network is stored as [target, regulator], so pass
+        model.network.T for a directed network.
     modules : List[List[int]]
         List of modules, where each module is a list of node indices.
     directed : bool, optional
@@ -674,7 +733,7 @@ def plot_network_diagram(j_mat: np.ndarray,
     if spin_name_list_short is not None:
         label = {ii: spin_name_list_short[ii] for ii in range(num_spin)}
     else:
-        label = {ii: f'P{ii}' for ii in range(num_spin)}
+        label = {ii: f'P{ii + 1}' for ii in range(num_spin)}
     
     # Plot network
     fig_size = 4 * num_spin ** 0.25
@@ -717,8 +776,9 @@ def plot_network_diagram(j_mat: np.ndarray,
     # Save figure if folder is provided
     if fig_folder is not None:
         plt.savefig(fig_folder + 'network_diagram.png', dpi=300, bbox_inches='tight')
-    
+
     plt.show()
+    
 
 def plot_top_regulators(program_interactions: np.ndarray, 
                         program_index: int, 
@@ -745,13 +805,12 @@ def plot_top_regulators(program_interactions: np.ndarray,
     fig_folder : Optional[str], optional
         The folder to save the figure.
     """
-
     cur_regulators = program_interactions[:, program_index]
     if thres is None:
-        thres = np.sort(np.abs(cur_regulators))[::-1][20]
+        thres = np.sort(np.abs(cur_regulators))[::-1][min(20, len(cur_regulators) - 1)]
 
-    num_gene_show_pos = np.sum(cur_regulators >= thres)
-    num_gene_show_neg = np.sum(cur_regulators <= -thres)
+    num_gene_show_pos = np.sum((cur_regulators >= thres) & (cur_regulators > 0))
+    num_gene_show_neg = np.sum((cur_regulators <= -thres) & (cur_regulators < 0))
     num_gene_show = num_gene_show_pos + num_gene_show_neg
 
     plot_ind_pos = np.argsort(cur_regulators)[::-1][:num_gene_show_pos]
@@ -771,6 +830,63 @@ def plot_top_regulators(program_interactions: np.ndarray,
         plt.title(program_name, fontsize=10)
 
     if fig_folder is not None:
-        plt.savefig(fig_folder + 'top_regulators.png')
+        plt.savefig(fig_folder + f'top_regulators_program_{program_index}.png')
 
-    plt.show()    
+
+def plot_all_regulators(program_interactions: np.ndarray, 
+                        gene_list: np.array, 
+                        program_name: Optional[str] = None, 
+                        thres: Optional[float] = 0.2,
+                        fig_folder: Optional[str] = None) -> None:
+    """
+    Plot the all regulators of all programs.
+
+    Parameters
+    ----------
+    program_interactions : np.ndarray
+        The program interactions.
+    gene_list : np.array
+        The list of genes.
+    program_name : Optional[str], optional
+        The name of the program.
+    thres : Optional[float], optional
+        The threshold for the regulators.
+    fig_folder : Optional[str], optional
+        The folder to save the figure.
+    """
+    program_interactions = program_interactions.copy()
+    program_interactions_raw = program_interactions.copy()
+    num_gene, num_program = program_interactions.shape
+
+    if thres is not None:
+        program_interactions[np.abs(program_interactions) < thres] = 0
+
+    gene_remove = np.sum(np.abs(program_interactions), axis=1) == 0
+    program_interactions = program_interactions[~gene_remove, :]
+    program_interactions_raw = program_interactions_raw[~gene_remove, :]
+    gene_list = np.array(gene_list)[~gene_remove]
+
+    num_gene, num_program = program_interactions.shape
+
+    sc.set_figure_params(figsize=[0.18 * num_gene, 0.2 * num_program])
+
+    gene_order = leaves_list(linkage(program_interactions_raw))
+    program_order = leaves_list(linkage(program_interactions_raw.T))
+
+    cmap_range = np.percentile(np.abs(program_interactions[program_interactions != 0]), 95)
+
+    plt.imshow(program_interactions_raw.T[program_order, :][:, gene_order], cmap=cmap_hvec, vmin=-cmap_range, vmax=cmap_range, aspect='auto')
+
+    plt.xticks(np.arange(num_gene), np.array(gene_list)[gene_order], rotation=90, fontsize=9); 
+    if program_name is not None:
+        plt.yticks(np.arange(num_program), np.array(program_name)[program_order], fontsize=9); 
+    else:
+        plt.yticks(np.arange(num_program), [f'P{program + 1}' for program in program_order], fontsize=9)
+
+    plt.xlabel('Regulators')
+    plt.ylabel('Programs')
+
+    plt.colorbar(fraction=0.6 / num_program)
+
+    if fig_folder is not None:
+        plt.savefig(fig_folder + 'all_regulator_interactions.png')

dspin-1.5.4/dspin/preprocess.py

@@ -0,0 +1,135 @@
+# -*-coding:utf-8 -*-
+'''
+@Time    :   2026/07/30
+@Author  :   Jialong Jiang
+'''
+
+import anndata as ad
+import matplotlib.pyplot as plt
+import numpy as np
+import scanpy as sc
+from scipy.optimize import curve_fit
+from scipy.sparse import issparse
+from sklearn.linear_model import LinearRegression
+from typing import Optional
+
+
+def select_highly_variable_genes(
+        adata: ad.AnnData, 
+        num_gene_select: int = 3000,
+        detect_frac: float = 0.02, 
+        max_mean_percentile: float = 100,
+        fit_method: str = 'nb',
+        group_key: Optional[str] = None) -> np.ndarray:
+    """
+    Select highly variable genes using a fitted mean-CV model.
+
+    The input matrix is expected to contain normalized, non-log-transformed
+    expression values. Linear fit, negative-binomial fit, and selected highly
+    variable gene plots are displayed.
+
+    Parameters
+    ----------
+    adata : ad.AnnData
+        Annotated data matrix containing normalized gene expression.
+    num_gene_select : int, optional
+        Number of highly variable genes to select. Default is 3000.
+    detect_frac : float, optional
+        Minimum fraction of cells expressing a gene across all cells, or in at
+        least one group when ``group_key`` is provided. Default is 0.02.
+    max_mean_percentile : float, optional
+        Upper percentile of gene means retained for selection. Values below
+        100 remove highly expressed housekeeping genes. Default is 100.
+    fit_method : str, optional
+        Fitted baseline used to rank genes. Options are 'linear' or 'nb'.
+        Default is 'nb'.
+    group_key : str or None, optional
+        Column in ``adata.obs`` used to group cells for the detection filter.
+        If None, detection is calculated across all cells. Default is None.
+
+    Returns
+    -------
+    np.ndarray
+        Names of the selected highly variable genes.
+    """
+    batch_size = 2000
+    sum_x = np.zeros(adata.n_vars)
+    sum_x_squared = np.zeros(adata.n_vars)
+    for start in range(0, adata.n_obs, batch_size):
+        block = adata.X[start:start + batch_size]
+        sum_x += np.asarray(block.sum(axis=0)).ravel()
+        sum_x_squared += np.asarray((block.power(2) if issparse(block) else np.square(block)).sum(axis=0)).ravel()
+
+    data_mean = sum_x / adata.n_obs
+    data_var = sum_x_squared / adata.n_obs - data_mean ** 2
+    valid = (data_mean > 0) & (data_var > 0)
+
+    log_mean = np.full(adata.n_vars, np.nan)
+    log_cv = np.full(adata.n_vars, np.nan)
+    log_mean[valid] = np.log10(data_mean[valid])
+    log_cv[valid] = np.log10(np.sqrt(data_var[valid]) / data_mean[valid])
+
+    def nb_model(x, k, b, pi):
+        return k * (x - np.log(1 + pi * np.exp(x))) + b
+
+    linear_model = LinearRegression().fit(
+        log_mean[valid, None], log_cv[valid])
+    linear_fit = np.full(adata.n_vars, np.nan)
+    linear_fit[valid] = linear_model.predict(log_mean[valid, None])
+
+    popt, _ = curve_fit(
+        nb_model, log_mean[valid], log_cv[valid], [-0.5, 1, 0],
+        method='dogbox')
+    nb_fit = np.full(adata.n_vars, np.nan)
+    nb_fit[valid] = nb_model(log_mean[valid], *popt)
+
+    if fit_method == 'linear':
+        fit_res = linear_fit
+    elif fit_method == 'nb':
+        fit_res = nb_fit
+    else:
+        raise ValueError("fit_method must be one of 'linear' or 'nb'")
+
+    if group_key is None:
+        detected = np.asarray((adata.X > 0).mean(axis=0)).ravel()
+    else:
+        detected = np.zeros(adata.n_vars)
+        groups = adata.obs[group_key].astype(str).to_numpy()
+        for group in np.unique(groups):
+            group_detect = np.asarray(
+                (adata.X[groups == group] > 0).mean(axis=0)).ravel()
+            detected = np.maximum(detected, group_detect)
+
+    eligible = (detected > detect_frac) & valid
+    if max_mean_percentile < 100:
+        mean_cutoff = np.percentile(data_mean[valid], max_mean_percentile)
+        eligible &= data_mean <= mean_cutoff
+
+    score = np.full(adata.n_vars, -np.inf)
+    score[valid] = log_cv[valid] - fit_res[valid]
+    cutoff = np.sort(score[eligible])[::-1][num_gene_select - 1]
+    gene_filt = (score >= cutoff) & eligible
+
+    sc.set_figure_params(figsize=[3, 3])
+    fig, grid = sc.pl._tools._panel_grid(0.1, 0.3, ncols=3, num_panels=3)
+    ax = [plt.subplot(grid[ii]) for ii in range(3)]
+    ax[0].scatter(log_mean[valid], log_cv[valid], 5)
+    ax[0].scatter(log_mean[valid], linear_fit[valid], 5)
+    ax[0].set(
+        title=f'linear fit (k={linear_model.coef_[0]:.3f})',
+        xlabel='log10(mean)', ylabel='log10(cv)')
+
+    ax[1].scatter(log_mean[valid], log_cv[valid], 5)
+    ax[1].scatter(log_mean[valid], nb_fit[valid], 5)
+    ax[1].set(
+        title=f'NB model (k={popt[0]:.3f})',
+        xlabel='log10(mean)', ylabel='log10(cv)')
+        
+    ax[2].scatter(log_mean[valid], log_cv[valid], 1, alpha=0.5)
+    ax[2].scatter(
+        log_mean[gene_filt], log_cv[gene_filt], 5, alpha=0.5, label='HVG')
+    ax[2].legend()
+    ax[2].set(xlabel='log10(mean)', ylabel='log10(cv)')
+    plt.show()
+
+    return adata.var_names[gene_filt].to_numpy()

{dspin-1.5.2 → dspin-1.5.4/dspin.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: dspin
-Version: 1.5.2
+Version: 1.5.4
 Summary: Regulatory network models from single-cell perturbation profiling
 Home-page: https://github.com/JialongJiang/DSPIN
 Author: Jialong Jiang
@@ -25,12 +25,24 @@ Requires-Dist: scanpy
 Requires-Dist: tqdm
 Requires-Dist: igraph
 Requires-Dist: leidenalg
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 # D-SPIN: Constructing regulatory network models from scRNA-seq perturbation profiling  
 
 D-SPIN is a computational framework for constructing regulatory network models of genes or gene programs from single-cell RNA-seq profiling of perturbation conditions. D-SPIN integrates information from multiple perturbation conditions for network inference with improved efficienty and accuracy. The regulatory network can be defined on single genes or gene programs (groups of coexpressed genes). The package includes implementation of gene program discovery, network inference, and network analysis. 
 
-If D-SPIN is useful for your research, consider citing "D-SPIN constructs gene regulatory network models from multiplexed scRNA-seq data revealing organizing principles of cellular perturbation response" ([bioRxiv](https://www.biorxiv.org/content/10.1101/2023.04.19.537364)).
+If D-SPIN is useful for your research, consider citing "D-SPIN constructs regulatory network models from scRNA-seq that reveal organizing principles of perturbation response" ([Cell](https://doi.org/10.1016/j.cell.2026.04.028)).
 
 ## Contact 
 

dspin-1.5.4/dspin.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+setup.py
+dspin/__init__.py
+dspin/annotate.py
+dspin/compute.py
+dspin/dspin.py
+dspin/plot.py
+dspin/preprocess.py
+dspin.egg-info/PKG-INFO
+dspin.egg-info/SOURCES.txt
+dspin.egg-info/dependency_links.txt
+dspin.egg-info/requires.txt
+dspin.egg-info/top_level.txt

{dspin-1.5.2 → dspin-1.5.4}/setup.py

@@ -21,7 +21,7 @@ install_requires = [
 # ]
 
 # Managing your version (adjust accordingly)
-version = "1.5.2"  # You can manage versioning in a more sophisticated way if needed
+version = "1.5.4"  # You can manage versioning in a more sophisticated way if needed
 
 # Long description (usually a README file)
 readme = open("README_PyPI.md").read()  # Adjust the file name if necessary

dspin-1.5.2/README.md

@@ -1,179 +0,0 @@
-# DSPIN
-
-Tutorial, code and examples of the D-SPIN framework for the preprint "D-SPIN constructs gene regulatory network models from multiplexed scRNA-seq data revealing organizing principles of cellular perturbation response" ([bioRxiv](https://www.biorxiv.org/content/10.1101/2023.04.19.537364))
-
-<div align="center">
-  <img src="figure/readme/Overview_20250523.png" width="800">
-</div>
-
-## Installation
-
-D-SPIN is implemented in Python and MATLAB. The Python code is sufficient for the analysis of most datasets with less than 100k cells and a few hundreds of conditions. The MATLAB code is more efficient on large datasets as MATLAB can be easily deployed on clusters for parallelization with the build-in "parfor" function. 
-
-The python code can be installed with 
-
-`pip install dspin`
-
-The MATLAB code can be downloaded from the folder "DSPIN_matlab", and directly executable in MATLAB after specifying the path to the data. 
-
-## Demos
-
-A tutorial intended for an invited book chapter is available at [bioRxiv](https://www.biorxiv.org/content/10.1101/2025.07.28.667326).
-
-Two demos of D-SPIN are available on Google Colab. 
-
-The first demo reconstructs the regulatory network of simulated hematopoietic stem cell (HSC) differentiation network with perturbations using the BEELINE framework (Pratapa, Aditya, et al. Nature methods, 2020). 
-
-[Demo1](https://colab.research.google.com/drive/1Nja8AAcP0L7Ag6DGbyn21SxGafsYX4fA?usp=sharing)
-
-The second demo reconstructs regulatory network and response vector in a public single-cell dataset of immune dictionary (Cui, Ang, et al. Nature, 2024), where mouse were treated with different cytokines and lymph nodes were than collected and profiled. 
-
-[Demo2](https://colab.research.google.com/drive/1E8v4awQ-m4D02emG0jp6kmRDmkZ8hjjN?usp=sharing)
-
-## Dependencies
-
-DSPIN package was tested with the following python packages versions:
-
-- python (3.9.18)
-- anndata (0.10.3)
-- matplotlib (3.8.2)
-- scanpy (1.9.6)
-- tqdm (4.65.0)
-- leidenalg (0.10.1)
-- igraph (0.10.8)
-
-Note: other versions may work as well.
-
-## Input data
-
-D‑SPIN can work with many perturbation types **as long as they share the same core regulatory network**:
-
-* **Genetic screens** – Perturb‑seq, CRISPR, RNAi  
-* **Chemical or signaling cues** – drug treatments, growth‑factor changes  
-* **Physiological differences** – healthy vs disease, different patients, time‑course samples  
-* **Spatial niches** – local micro‑environments from spatial transcriptomics  
-
-Because D‑SPIN models the *entire* distribution of transcriptional states, it expects **single‑cell RNA‑seq** data. Bulk data is possible but less informative.
-
-#### AnnData requirements
-
-* `adata.X` — log‑normalized (`log1p`) count matrix **after** QC: remove low‑quality cells, filter high mitochondrial content, keep highly variable genes.  
-* `adata.obs['sample_id']` — condition label; cells with the same value form one perturbation group (≥ 25 cells per group is ideal).  
-* `adata.obs['batch']` — batch identifier for cells processed together; D‑SPIN corrects batch effects by comparing conditions within each batch.  
-* `adata.obs['if_control']` — `True` for controls, `False` otherwise; perturbation effects are measured relative to these controls (or to the overall average if no controls exist).  
-
-## Building network models with D‑SPIN
-
-#### Gene‑level network models
-
-```python
-from dspin.dspin import DSPIN
-
-model = DSPIN(adata, save_path, num_spin=adata.shape[1])
-model.network_inference(
-    sample_id_key='sample_id',
-    method='pseudo_likelihood',
-    directed=True,
-    run_with_matlab=False,
-    params={'stepsz': 0.05, 'lam_l1_j': 0.01}
-)
-model.response_relative_to_control(
-    sample_id_key='sample_id',
-    if_control_key='if_control',
-    batch_key='batch'
-)
-```
-
-* **Results saved to `model`:**
-  * `model.network` – regulatory weights **J**
-  * `model.responses` – gene‑level responses **h**
-  * `model.relative_responses` – responses relative to control (per batch)
-
-* **Key options**
-  * `num_spin=adata.shape[1]` → build a *gene‑level* network  
-  * `directed=True` → only supported with `pseudo_likelihood`  
-  * `run_with_matlab=True` → skip Python inference and write variables to `save_path` for the MATLAB version (speeds up very large data sets)  
-  * `params` → hyper‑parameters such as step size, training epochs, and L1/L2 regularisation  
-
----
-
-#### Program‑level network models
-
-```python
-from dspin.dspin import DSPIN
-
-model = DSPIN(adata, save_path, num_spin=15)      # 15 gene programs
-model.gene_program_discovery(
-    num_repeat=10,
-    seed=0,
-    cluster_key='cell_type'                       # balance cell types
-)
-model.network_inference(
-    sample_id_key='sample_id',
-    method='mcmc_maximum_likelihood'
-)
-model.response_relative_to_control()
-```
-
-* **Extra outputs**
-  * Gene‑program compositions in `save_path/onmf`
-  * Consensus program gene lists in `save_path`
-
-* **Tips**
-  * Choose `num_spin` ≈ 5 × (number of cell types); keep ≤ 40  
-  * `cluster_key` lets D‑SPIN down‑sample over‑represented cell types before oNMF  
-
----
-
-#### Finding gene regulators of programs
-
-```python
-# model_program : program‑level DSPIN object
-# model_gene    : gene‑level   DSPIN object
-model_gene.program_regulator_discovery(
-    model_program.program_representation,
-    sample_id_key='sample_id',
-    params={'stepsz': 0.02, 'lam_l1_interaction': 0.01}
-)
-```
-
-* **Prerequisite** – `adata.obs` metadata must match between the two models so each cell’s gene and program states align.
-
-* **Outputs in `model_gene`:**
-  * `model_gene.program_interactions` – regression coefficients **J** (gene ↔ program)
-  * `model_gene.program_activities` – global activity **h** for each program
-
-
-## Application to the T cell population of the immune dictionary dataset
-
-
-<div align="center">
-  <img src="figure/readme/Figure2_immune_dictionary.png" width="600">
-</div>
-
-<div align="left">
-  <em>Figure&nbsp; Overview and program discovery for the immune dictionary dataset. (A) t-distributed stochastic neighbour (t-SNE) embedding for a subsetted cell population from the immune dictionary dataset \cite{cui2024dictionary}. The subset dataset includes CD4, CD8, and regulatory T cells treated by 12 different cytokines, as well as corresponding control samples treated by phosphate-buffered saline (PBS). 
-(B) Heatmaps of gene expression and discretized gene program levels for control and IFN-$\alpha$1-treated samples. The gene programs are weighted averages of single-gene expressions that characterize and denoise the major expression pattern of the gene matrix.</em>
-</div>
-
-<div align="center">
-  <img src="figure/readme/Figure3_program_network.png" width="600">
-</div>
-
-<div align="left">
-  <em>Figure&nbsp; Program/gene-level regulatory network inferred by D-SPIN.
-(A) Diagram of D-SPIN-inferred network model on gene programs. The network is partitioned into 4 modules, each associated with a T cell type in the population.
-(B) Heatmap of the program response of each cytokine. Clustering of the response partitioned the cytokines into 3 major categories. 
-(C) Diagram of the core subnetwork of the D-SPIN-inferred gene network model. The node sizes scale with the number of identified interactions. The network is partitioned into 4 modules, each primarily composed of genes that have elevated expression in one specific T cell type.
-(D) Interaction diagram for the subnetwork of IFN-$\alpha$1/IFN-$\beta$ and IFN-$\gamma$ acting on the program P18-IFN-$\gamma$ response. D-SPIN model shows that Type I and Type II interferons have different effectors to activate the program.</em>
-</div>
-
-## References
-
-1. Jiang, Jialong, et al. "D-SPIN constructs gene regulatory network models from multiplexed scRNA-seq data revealing organizing principles of cellular perturbation response." bioRxiv (2023).
-
-2. Jiang, Jialong, and Thomson, Matt. "A guide to D-SPIN: constructing regulatory network models from single-cell RNA-seq perturbation data." bioRxiv (2025).
-
-3. Pratapa, Aditya, et al. "Benchmarking algorithms for gene regulatory network inference from single-cell transcriptomic data." Nature methods 17.2 (2020): 147-154.
-
-4. Cui, Ang, et al. "Dictionary of immune responses to cytokines at single-cell resolution." Nature 625.7994 (2024): 377-384.

dspin-1.5.2/dspin.egg-info/SOURCES.txt

@@ -1,21 +0,0 @@
-LICENSE
-README.md
-requirements.txt
-setup.py
-__pycache__/__init__.cpython-310.pyc
-__pycache__/__init__.cpython-37.pyc
-__pycache__/compute.cpython-310.pyc
-__pycache__/compute.cpython-37.pyc
-__pycache__/dspin_abstract.cpython-310.pyc
-__pycache__/plot.cpython-310.pyc
-__pycache__/plotting.cpython-37.pyc
-dspin/__init__.py
-dspin/annotate.py
-dspin/compute.py
-dspin/dspin.py
-dspin/plot.py
-dspin.egg-info/PKG-INFO
-dspin.egg-info/SOURCES.txt
-dspin.egg-info/dependency_links.txt
-dspin.egg-info/requires.txt
-dspin.egg-info/top_level.txt

dspin-1.5.2/requirements.txt

@@ -1,6 +0,0 @@
-anndata
-matplotlib
-scanpy
-tqdm
-igraph
-leidenalg