Arboreto

Arboreto

Overview

Arboreto is a Python library from Aerts Lab for inferring gene regulatory networks (GRNs) from gene expression data. It parallelizes tree-based ensemble regression (GRNBoost2, GENIE3) with Dask across local cores or remote clusters.

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

Upstream: PyPI 0.1.6 (2021-02-09, latest). Docs: arboreto.readthedocs.io. Primary downstream consumer: pySCENIC.

[!WARNING] Maintenance freeze & Dask compatibility break: arboreto has had no PyPI release since 0.1.6 (February 2021). The grnboost2() function raises TypeError: Must supply at least one delayed object with modern Dask (open bugs since Aug 2024, no maintainer response — see arboreto#42, #40). pySCENIC (primary consumer) has had no release since Nov 2022. Workarounds: use Python 3.10.15 with dask-expr==0.5.3 and distributed==2024.2.1 for the reported dask_expr.from_delayed break, apply the unreleased arboreto source fix referenced in arboreto#42, or use arboreto_with_multiprocessing.py / rustscenic to bypass Dask entirely.

Quick Start

Install arboreto:

uv pip install 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)

Critical: Always use if __name__ == '__main__': guard because Dask spawns new processes.

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 --limit 5000

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

Conda (Bioconda):

conda install -c bioconda arboreto

Dependencies (from upstream requirements.txt): dask[complete], distributed, numpy, pandas, scikit-learn, scipy

Input formats: pandas DataFrame, dense numpy.ndarray, or sparse scipy.sparse.csc_matrix (rows = observations, columns = genes). For array/matrix inputs, pass gene_names explicitly.

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)

    # Filter high-confidence links
    high_confidence = network[network['importance'] > 0.5]
    high_confidence.to_csv('grn_high_confidence.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:

Filtering strategy:

• limit=N at inference time (return top N links globally)
• Post-hoc importance threshold (e.g., > 0.5)
• Top links per target via groupby('target')
• Statistical significance testing (permutation tests, external tools)

Integration with pySCENIC

Arboreto powers the GRN inference step in pySCENIC. pySCENIC 0.11+ passes sparse expression matrices to grnboost2 / genie3; pySCENIC 0.12+ defaults to arboreto_with_multiprocessing.py (no Dask) for compatibility — use standalone arboreto when you need Dask scaling.

# Standalone: infer co-expression modules before pySCENIC cisTarget pruning
from arboreto.algo import grnboost2

network = grnboost2(expression_data=expression_df, tf_names=tf_list, limit=5000)

# Downstream: pySCENIC ctx pruning, regulon definition, AUCell (see pySCENIC docs)

Convert AnnData to a DataFrame for arboreto directly:

expression_df = adata.to_df()  # cells x genes

Reproducibility

Always set a seed for reproducible results:

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

Run multiple seeds for robustness analysis:

from distributed import LocalCluster, Client

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

    seeds = [42, 123, 777]
    networks = []

    for seed in seeds:
        net = grnboost2(expression_data=matrix, client_or_address=client, seed=seed)
        networks.append(net)

    # Consensus: links recurring across runs (example: mean importance per TF-target pair)
    import pandas as pd
    combined = pd.concat(networks)
    consensus = (
        combined.groupby(['TF', 'target'], as_index=False)['importance']
        .mean()
        .query('importance > 0.5')
    )

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 (required on Windows/macOS with spawn-based multiprocessing)

Empty results: Check data format (genes as columns), verify TF names match column names in the expression matrix

Sparse data: Use scipy.sparse.csc_matrix and pass matching gene_names; supported since arboreto 0.1.6 / pySCENIC 0.11