Developer Guide

!!! Note To better understand STARNet, you may check out our preprint first to learn about the general idea.

Below we describe the main components of the framework, and how to extend the existing implementations.

Framework

The STARNet code is stored in the src/STARNet folder in the GitHub repository, with the __init__.py file taking care of lazy module loading.

A STARNet framework is primarily composed of 5 components:

  • grn: Gene Regulatory Network inference, including peak-to-gene linking, motif scanning, and GRN construction.

  • pp: Preprocessing and downstream analysis, including peak-gene association extraction, GRN scoring, TF module scoring, and GWAS utilities.

  • pl: Plotting utilities for GRN, GWAS, and spatial visualization.

  • model: The STARNet deep-learning model (PyTorch Geometric-based) for integrating spatial RNA and ATAC data.

  • external: Vendored third-party packages (e.g., scglue, SEACells, scdrs, palantir, epiverse) to avoid installation conflicts.

All public functions are exposed through the top-level STARNet namespace via lazy loading in __init__.py.

For Developers

External Module

In most cases, integrating an existing package is preferable to re-implementing it. We can directly clone the entire package from GitHub and move the folder into the external directory. During this process, pay attention to:

  1. License compatibility with STARNet’s MIT license.

  2. Import hygiene: Change top-level imports of packages that are not STARNet dependencies to function-level imports.

This is incorrect because dgl is not in STARNet’s default requirements:

import dgl

def calculate():
    dgl.run()

The correct approach:

def calculate():
    import dgl
    dgl.run()

We recommend using try/except to detect import errors and guide users to the correct installation page:

def calculate():
    try:
        import dgl
    except ImportError:
        raise ImportError(
            'Please install dgl from https://www.dgl.ai/pages/start.html'
        )
    dgl.run()

Main Module

If you want to contribute a new feature, identify which module it belongs to:

  • grn → algorithms for GRN inference

  • pp → preprocessing and downstream analysis utilities

  • pl → plotting functions

  • model → neural network components

Add a new file (e.g., _newfeature.py) inside the appropriate module folder and expose it in that module’s __init__.py.

All functions require parameter descriptions in the following format:

def infer_grn(rna: ad.AnnData,
              adata_atac: ad.AnnData = None,
              genomic_data_pathway: str = None,
              n_genes: int = 500) -> pd.DataFrame:
    """
    Infer Gene Regulatory Network from multi-omics data.

    Parameters
    ----------
    rna : ad.AnnData
        The AnnData object of spatial RNA-seq data.
    adata_atac : ad.AnnData, optional
        The AnnData object of spatial ATAC-seq data.
    genomic_data_pathway : str, optional
        Path to the genomic data.
    n_genes : int, optional
        Number of genes to consider. Default is 500.

    Returns
    -------
    pd.DataFrame
        Inferred gene regulatory network.
    """

Pull Request

  1. Fork STARNet on GitHub and clone your fork.

  2. Create a feature branch.

  3. Make your changes with clear commit messages.

  4. Open a Pull Request and wait for review.