Claude Skill

alterlab-arboreto

Infer gene regulatory networks (GRNs) from expression matrices using arboreto's scalable GRNBoost2 and GENIE3 tree-ensemble algorithms with Dask-distributed computation. Use when analyzing bulk or single-cell RNA-seq transcriptomics to map transcription-factor-to-target-gene regu

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download AlterLab-IEU-AlterLab-Academic-Skills-skills_bioinformatics_alterlab-arboreto-3ab6d03.zip · 19 KB

Install

skills CLI npx skills add https://github.com/AlterLab-IEU/AlterLab-Academic-Skills/tree/main/skills/bioinformatics/alterlab-arboreto
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alterlab-ieu-alterlab-academic-skills@llmmart
Git git clone https://github.com/AlterLab-IEU/AlterLab-Academic-Skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole alterlab-ieu/alterlab-academic-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Arboreto

Overview

Arboreto is a computational library for inferring gene regulatory networks (GRNs) from gene expression data using parallelized algorithms that scale from single machines to multi-node clusters.

Core capability: Identify which transcription factors (TFs) regulate which target genes based on expression patterns across observations (cells, samples, conditions).

When to Use This Skill

Use this skill when the user wants to:

  • Infer a TF → target-gene regulatory network from a bulk or single-cell expression matrix.
  • Run the GRN-inference step (step 1) of a SCENIC / pySCENIC pipeline.
  • Compare GRNBoost2 against GENIE3, or build a consensus network across random seeds.
  • Scale GRN inference across cores or a Dask cluster.

Does NOT Trigger

Scenario Use Instead
Differential expression between conditions (counts → padj) alterlab-pydeseq2
Clustering, UMAP, or QC of a single-cell dataset alterlab-scanpy
Deep-learning latent space / batch integration of scRNA-seq alterlab-scvi-tools
Generic graph analysis or centrality on an existing network alterlab-networkx
Tuning the Dask cluster itself rather than running GRN inference alterlab-dask

Hand-off rule. When the request matches a row above, open your answer by naming that skill by its exact id (for example alterlab-pydeseq2) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.

Quick Start

Install arboreto:

uv pip install arboreto

Arboreto 0.1.6 is from 2021 and its internals use dask.delayed plus dask.dataframe.from_delayed. Those APIs still exist in current dask, but if a run fails inside dask rather than inside arboreto, pin dask/distributed to a matching pair in an isolated env (pySCENIC's pins are a good reference) rather than editing arboreto.

Basic GRN inference:

import pandas as pd
from arboreto.algo import grnboost2

if __name__ == '__main__':
    # Load expression data (genes as columns)
    expression_matrix = pd.read_csv('expression_data.tsv', sep='\t')

    # Infer regulatory network
    network = grnboost2(expression_data=expression_matrix)

    # Save results (TF, target, importance)
    network.to_csv('network.tsv', sep='\t', index=False, header=False)

Wrap the entry point in if __name__ == '__main__': — Dask spawns worker processes that re-import the module, so unguarded top-level code runs again in every worker.

Core Capabilities

1. Basic GRN Inference

For standard GRN inference workflows including:

  • Input data preparation (Pandas DataFrame or NumPy array)
  • Running inference with GRNBoost2 or GENIE3
  • Filtering by transcription factors
  • Output format and interpretation

See: references/basic_inference.md

Use the ready-to-run script: scripts/basic_grn_inference.py for standard inference tasks:

python scripts/basic_grn_inference.py expression_data.tsv output_network.tsv --tf-file tfs.txt --seed 777

2. Algorithm Selection

Arboreto provides two algorithms:

GRNBoost2 (Recommended):

  • Fast gradient boosting-based inference
  • Optimized for large datasets (10k+ observations)
  • Default choice for most analyses

GENIE3:

  • Random Forest-based inference
  • Original multiple regression approach
  • Use for comparison or validation

Quick comparison:

from arboreto.algo import grnboost2, genie3

# Fast, recommended
network_grnboost = grnboost2(expression_data=matrix)

# Classic algorithm
network_genie3 = genie3(expression_data=matrix)

For detailed algorithm comparison, parameters, and selection guidance: references/algorithms.md

3. Distributed Computing

Scale inference from local multi-core to cluster environments:

Local (default) - Uses all available cores automatically:

network = grnboost2(expression_data=matrix)

Custom local client - Control resources:

from distributed import LocalCluster, Client

local_cluster = LocalCluster(n_workers=10, memory_limit='8GB')
client = Client(local_cluster)

network = grnboost2(expression_data=matrix, client_or_address=client)

client.close()
local_cluster.close()

Cluster computing - Connect to remote Dask scheduler:

from distributed import Client

client = Client('tcp://scheduler:8786')
network = grnboost2(expression_data=matrix, client_or_address=client)

For cluster setup, performance optimization, and large-scale workflows: references/distributed_computing.md

Installation

uv pip install arboreto

Dependencies: scipy, scikit-learn, numpy, pandas, dask, distributed

Common Use Cases

Single-Cell RNA-seq Analysis

import pandas as pd
from arboreto.algo import grnboost2

if __name__ == '__main__':
    # Load single-cell expression matrix (cells x genes)
    sc_data = pd.read_csv('scrna_counts.tsv', sep='\t')

    # Infer cell-type-specific regulatory network
    network = grnboost2(expression_data=sc_data, seed=42)

    # importance is unbounded (not a 0-1 probability); keep the top links
    # per target rather than applying an absolute threshold.
    top_links = network.sort_values('importance', ascending=False).groupby('target').head(10)
    top_links.to_csv('grn_top_links.tsv', sep='\t', index=False)

Bulk RNA-seq with TF Filtering

from arboreto.utils import load_tf_names
from arboreto.algo import grnboost2

if __name__ == '__main__':
    # Load data
    expression_data = pd.read_csv('rnaseq_tpm.tsv', sep='\t')
    tf_names = load_tf_names('human_tfs.txt')

    # Infer with TF restriction
    network = grnboost2(
        expression_data=expression_data,
        tf_names=tf_names,
        seed=123
    )

    network.to_csv('tf_target_network.tsv', sep='\t', index=False)

Comparative Analysis (Multiple Conditions)

from arboreto.algo import grnboost2

if __name__ == '__main__':
    # Infer networks for different conditions
    conditions = ['control', 'treatment_24h', 'treatment_48h']

    for condition in conditions:
        data = pd.read_csv(f'{condition}_expression.tsv', sep='\t')
        network = grnboost2(expression_data=data, seed=42)
        network.to_csv(f'{condition}_network.tsv', sep='\t', index=False)

Output Interpretation

Arboreto returns a DataFrame with regulatory links:

Column Description
TF Transcription factor (regulator)
target Target gene
importance Regulatory importance score (higher = stronger)

Filtering strategy: importance is an unbounded relative score (derived from tree feature importances), not a probability or correlation — do not apply absolute cutoffs like > 0.5. Prefer:

  • Top N links per target gene
  • A quantile cutoff computed from the run's own distribution
  • In a SCENIC workflow, keep all links and let downstream cisTarget motif pruning do the filtering

Integration with pySCENIC

Arboreto is a core component of the SCENIC pipeline for single-cell regulatory network analysis:

# Step 1: Use arboreto for GRN inference
from arboreto.algo import grnboost2
network = grnboost2(expression_data=sc_data, tf_names=tf_list)

# Step 2: Use pySCENIC for regulon identification and activity scoring
# (See pySCENIC documentation for downstream analysis)

Reproducibility

Always set a seed for reproducible results:

network = grnboost2(expression_data=matrix, seed=777)

GRNBoost2 is stochastic, so a single seed pins one run but does not establish robustness. For a consensus network, run several seeds and keep links that recur, averaging their importance:

import pandas as pd
from distributed import LocalCluster, Client
from arboreto.algo import grnboost2

if __name__ == '__main__':
    client = Client(LocalCluster())

    seeds = [42, 123, 777]
    networks = [
        grnboost2(expression_data=matrix, client_or_address=client, seed=s)
        for s in seeds
    ]
    client.close()

    # Consensus: keep edges present in every run, average their importance
    combined = pd.concat(networks)
    consensus = (combined.groupby(['TF', 'target'])
                 .agg(importance=('importance', 'mean'), n_runs=('importance', 'size'))
                 .reset_index())
    consensus = consensus[consensus['n_runs'] == len(seeds)]

Troubleshooting

Memory errors: Reduce dataset size by filtering low-variance genes or use distributed computing

Slow performance: Use GRNBoost2 instead of GENIE3, enable distributed client, filter TF list

Dask errors: Ensure if __name__ == '__main__': guard is present in scripts

Empty results: Check data format (genes as columns), verify TF names match gene names

Resources

  • references/basic_inference.md — input preparation, running inference, output format
  • references/algorithms.md — GRNBoost2 vs GENIE3 parameters and selection guidance
  • references/distributed_computing.md — cluster setup and large-scale workflows
  • scripts/basic_grn_inference.py — runnable CLI wrapper for a standard GRNBoost2 run

Part of the AlterLab Academic Skills suite.

Files (alterlab-academic-skills)
  • evals
    • fixtures
      • expression.tsv 17.3 KB · in bundle
      • tfs.txt 40 B
        Loading…
    • evals.json 4.4 KB
      Loading…
  • references
    • algorithms.md 4.3 KB
      Loading…
    • basic_inference.md 3.7 KB
      Loading…
    • distributed_computing.md 6.7 KB
      Loading…
  • scripts
    • basic_grn_inference.py 2.9 KB
      Loading…
  • SKILL.md 10.1 KB
    ---
    name: alterlab-arboreto
    description: Infer gene regulatory networks (GRNs) from expression matrices using arboreto's scalable GRNBoost2 and GENIE3 tree-ensemble algorithms with Dask-distributed computation. Use when analyzing bulk or single-cell RNA-seq transcriptomics to map transcription-factor-to-target-gene regulatory interactions, build adjacency networks, or run the GRN-inference step of a SCENIC pipeline on large datasets. Part of the AlterLab Academic Skills suite.
    license: MIT
    allowed-tools: Read Write Edit Bash(python:*) Bash(uv:*)
    compatibility: "Self-contained — runs under `uv run python` with `arboreto` installed (0.1.6, the current and last release, published Feb 2021); it pulls in `dask[complete]` and `distributed`. No API key or account required."
    metadata:
        skill-author: AlterLab
        version: "1.1.0"
        last_updated: "2026-09-23"
    ---
    
    # Arboreto
    
    ## Overview
    
    Arboreto is a computational library for inferring gene regulatory networks (GRNs) from gene expression data using parallelized algorithms that scale from single machines to multi-node clusters.
    
    **Core capability**: Identify which transcription factors (TFs) regulate which target genes based on expression patterns across observations (cells, samples, conditions).
    
    ## When to Use This Skill
    
    Use this skill when the user wants to:
    - Infer a TF → target-gene regulatory network from a bulk or single-cell expression matrix.
    - Run the GRN-inference step (step 1) of a SCENIC / pySCENIC pipeline.
    - Compare GRNBoost2 against GENIE3, or build a consensus network across random seeds.
    - Scale GRN inference across cores or a Dask cluster.
    
    ### Does NOT Trigger
    
    | Scenario | Use Instead |
    |----------|-------------|
    | Differential expression between conditions (counts → padj) | `alterlab-pydeseq2` |
    | Clustering, UMAP, or QC of a single-cell dataset | `alterlab-scanpy` |
    | Deep-learning latent space / batch integration of scRNA-seq | `alterlab-scvi-tools` |
    | Generic graph analysis or centrality on an existing network | `alterlab-networkx` |
    | Tuning the Dask cluster itself rather than running GRN inference | `alterlab-dask` |
    
    **Hand-off rule.** When the request matches a row above, open your answer by naming that skill by its exact id (for example `alterlab-pydeseq2`) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.
    
    ## Quick Start
    
    Install arboreto:
    ```bash
    uv pip install arboreto
    ```
    
    Arboreto 0.1.6 is from 2021 and its internals use `dask.delayed` plus
    `dask.dataframe.from_delayed`. Those APIs still exist in current dask, but if a run fails
    inside dask rather than inside arboreto, pin `dask`/`distributed` to a matching pair in an
    isolated env (pySCENIC's pins are a good reference) rather than editing arboreto.
    
    Basic GRN inference:
    ```python
    import pandas as pd
    from arboreto.algo import grnboost2
    
    if __name__ == '__main__':
        # Load expression data (genes as columns)
        expression_matrix = pd.read_csv('expression_data.tsv', sep='\t')
    
        # Infer regulatory network
        network = grnboost2(expression_data=expression_matrix)
    
        # Save results (TF, target, importance)
        network.to_csv('network.tsv', sep='\t', index=False, header=False)
    ```
    
    Wrap the entry point in `if __name__ == '__main__':` — Dask spawns worker processes that
    re-import the module, so unguarded top-level code runs again in every worker.
    
    ## Core Capabilities
    
    ### 1. Basic GRN Inference
    
    For standard GRN inference workflows including:
    - Input data preparation (Pandas DataFrame or NumPy array)
    - Running inference with GRNBoost2 or GENIE3
    - Filtering by transcription factors
    - Output format and interpretation
    
    **See**: `references/basic_inference.md`
    
    **Use the ready-to-run script**: `scripts/basic_grn_inference.py` for standard inference tasks:
    ```bash
    python scripts/basic_grn_inference.py expression_data.tsv output_network.tsv --tf-file tfs.txt --seed 777
    ```
    
    ### 2. Algorithm Selection
    
    Arboreto provides two algorithms:
    
    **GRNBoost2 (Recommended)**:
    - Fast gradient boosting-based inference
    - Optimized for large datasets (10k+ observations)
    - Default choice for most analyses
    
    **GENIE3**:
    - Random Forest-based inference
    - Original multiple regression approach
    - Use for comparison or validation
    
    Quick comparison:
    ```python
    from arboreto.algo import grnboost2, genie3
    
    # Fast, recommended
    network_grnboost = grnboost2(expression_data=matrix)
    
    # Classic algorithm
    network_genie3 = genie3(expression_data=matrix)
    ```
    
    **For detailed algorithm comparison, parameters, and selection guidance**: `references/algorithms.md`
    
    ### 3. Distributed Computing
    
    Scale inference from local multi-core to cluster environments:
    
    **Local (default)** - Uses all available cores automatically:
    ```python
    network = grnboost2(expression_data=matrix)
    ```
    
    **Custom local client** - Control resources:
    ```python
    from distributed import LocalCluster, Client
    
    local_cluster = LocalCluster(n_workers=10, memory_limit='8GB')
    client = Client(local_cluster)
    
    network = grnboost2(expression_data=matrix, client_or_address=client)
    
    client.close()
    local_cluster.close()
    ```
    
    **Cluster computing** - Connect to remote Dask scheduler:
    ```python
    from distributed import Client
    
    client = Client('tcp://scheduler:8786')
    network = grnboost2(expression_data=matrix, client_or_address=client)
    ```
    
    **For cluster setup, performance optimization, and large-scale workflows**: `references/distributed_computing.md`
    
    ## Installation
    
    ```bash
    uv pip install arboreto
    ```
    
    **Dependencies**: scipy, scikit-learn, numpy, pandas, dask, distributed
    
    ## Common Use Cases
    
    ### Single-Cell RNA-seq Analysis
    ```python
    import pandas as pd
    from arboreto.algo import grnboost2
    
    if __name__ == '__main__':
        # Load single-cell expression matrix (cells x genes)
        sc_data = pd.read_csv('scrna_counts.tsv', sep='\t')
    
        # Infer cell-type-specific regulatory network
        network = grnboost2(expression_data=sc_data, seed=42)
    
        # importance is unbounded (not a 0-1 probability); keep the top links
        # per target rather than applying an absolute threshold.
        top_links = network.sort_values('importance', ascending=False).groupby('target').head(10)
        top_links.to_csv('grn_top_links.tsv', sep='\t', index=False)
    ```
    
    ### Bulk RNA-seq with TF Filtering
    ```python
    from arboreto.utils import load_tf_names
    from arboreto.algo import grnboost2
    
    if __name__ == '__main__':
        # Load data
        expression_data = pd.read_csv('rnaseq_tpm.tsv', sep='\t')
        tf_names = load_tf_names('human_tfs.txt')
    
        # Infer with TF restriction
        network = grnboost2(
            expression_data=expression_data,
            tf_names=tf_names,
            seed=123
        )
    
        network.to_csv('tf_target_network.tsv', sep='\t', index=False)
    ```
    
    ### Comparative Analysis (Multiple Conditions)
    ```python
    from arboreto.algo import grnboost2
    
    if __name__ == '__main__':
        # Infer networks for different conditions
        conditions = ['control', 'treatment_24h', 'treatment_48h']
    
        for condition in conditions:
            data = pd.read_csv(f'{condition}_expression.tsv', sep='\t')
            network = grnboost2(expression_data=data, seed=42)
            network.to_csv(f'{condition}_network.tsv', sep='\t', index=False)
    ```
    
    ## Output Interpretation
    
    Arboreto returns a DataFrame with regulatory links:
    
    | Column | Description |
    |--------|-------------|
    | `TF` | Transcription factor (regulator) |
    | `target` | Target gene |
    | `importance` | Regulatory importance score (higher = stronger) |
    
    **Filtering strategy**: `importance` is an unbounded relative score (derived from tree feature importances), not a probability or correlation — do not apply absolute cutoffs like `> 0.5`. Prefer:
    - Top N links per target gene
    - A quantile cutoff computed from the run's own distribution
    - In a SCENIC workflow, keep all links and let downstream cisTarget motif pruning do the filtering
    
    ## Integration with pySCENIC
    
    Arboreto is a core component of the SCENIC pipeline for single-cell regulatory network analysis:
    
    ```python
    # Step 1: Use arboreto for GRN inference
    from arboreto.algo import grnboost2
    network = grnboost2(expression_data=sc_data, tf_names=tf_list)
    
    # Step 2: Use pySCENIC for regulon identification and activity scoring
    # (See pySCENIC documentation for downstream analysis)
    ```
    
    ## Reproducibility
    
    Always set a seed for reproducible results:
    ```python
    network = grnboost2(expression_data=matrix, seed=777)
    ```
    
    GRNBoost2 is stochastic, so a single seed pins one run but does not establish
    robustness. For a consensus network, run several seeds and keep links that
    recur, averaging their importance:
    ```python
    import pandas as pd
    from distributed import LocalCluster, Client
    from arboreto.algo import grnboost2
    
    if __name__ == '__main__':
        client = Client(LocalCluster())
    
        seeds = [42, 123, 777]
        networks = [
            grnboost2(expression_data=matrix, client_or_address=client, seed=s)
            for s in seeds
        ]
        client.close()
    
        # Consensus: keep edges present in every run, average their importance
        combined = pd.concat(networks)
        consensus = (combined.groupby(['TF', 'target'])
                     .agg(importance=('importance', 'mean'), n_runs=('importance', 'size'))
                     .reset_index())
        consensus = consensus[consensus['n_runs'] == len(seeds)]
    ```
    
    ## Troubleshooting
    
    **Memory errors**: Reduce dataset size by filtering low-variance genes or use distributed computing
    
    **Slow performance**: Use GRNBoost2 instead of GENIE3, enable distributed client, filter TF list
    
    **Dask errors**: Ensure `if __name__ == '__main__':` guard is present in scripts
    
    **Empty results**: Check data format (genes as columns), verify TF names match gene names
    
    
    ## Resources
    
    - `references/basic_inference.md` — input preparation, running inference, output format
    - `references/algorithms.md` — GRNBoost2 vs GENIE3 parameters and selection guidance
    - `references/distributed_computing.md` — cluster setup and large-scale workflows
    - `scripts/basic_grn_inference.py` — runnable CLI wrapper for a standard GRNBoost2 run
    
    Part of the AlterLab Academic Skills suite.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.