alterlab-arboreto

Files (6)

• SKILL.md
• evals.json · evals/
• algorithms.md · references/
• basic_inference.md · references/
• distributed_computing.md · references/
• basic_grn_inference.py · scripts/

SKILL.md (first lines)

# 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` |

## 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)

From AlterLab-IEU/AlterLab-Academic-Skills, MIT.

More from AlterLab-IEU/AlterLab-Academic-Skills