arboreto

Arboreto

When to use

Use Arboreto to rank candidate regulator-target associations from expression measurements. GRNBoost2 fits stochastic gradient boosting regressions; GENIE3 fits random forests. Each target is predicted from candidate regulators, excluding itself. These are observational predictive associations, not proof of direct binding, activation/repression, or causal regulation.

The latest PyPI release checked is 0.1.6 (2021-02-09). Read the Docs still labels its documentation 0.1.5; the current GitHub source contains fixes that are not in the PyPI wheel. Do not assume a successful unpinned installation can run inference. See compatibility and distribution details.

Installation and compatibility

The following exact stack passed dense and CSC-sparse GRNBoost2, dense GENIE3, custom GBM/RF, and wrapper smoke tests on macOS arm64 with Python 3.11.11:

uv venv --python 3.11 .venv-arboreto
uv pip install --python .venv-arboreto/bin/python \
  'arboreto==0.1.6' 'dask[complete]==2024.7.1' 'distributed==2024.7.1' \
  'numpy==1.26.4' 'pandas==2.2.3' 'scikit-learn==1.5.2' 'scipy==1.13.1'

This is a bounded compatibility recipe, not a claim that current releases of all dependencies work. PyPI Arboreto builds an empty metadata graph that the newer Dask dataframe implementation rejects. For this pinned Dask version, select its legacy dataframe backend before importing Arboreto or dask.dataframe:

import dask
dask.config.set({"dataframe.query-planning": False})
from arboreto.algo import grnboost2, genie3

The bundled wrapper does this for Dask 2024.7.1. Restart an existing notebook kernel if it has already imported the newer dataframe backend. Sparse targets also use .A inside Arboreto 0.1.6; this attribute was removed in SciPy 1.14. Keep the tested SciPy pin for sparse inference. No monkeypatch to site-packages is required by this recipe.

Workflow

1. Select biologically comparable cells/samples; document normalization, filtering, batch handling, organism, identifier namespace, and expression layer.
2. Prepare rows = observations, columns = genes. Exclude sample IDs from expression values. Require unique gene names, numeric finite values, and a TF list with a nonempty overlap. All-zero/constant genes provide no useful targets.
3. Choose GRNBoost2 for an efficient starting analysis, GENIE3 for method comparison, or diy for explicit regressor settings. See algorithms.
4. Run a small subset first in the pinned environment, then scale worker counts to available memory. Keep the if __name__ == "__main__": guard in process-based scripts.
5. Inspect worker warnings and target coverage, save the full ranked network, and assess stability across seeds and resampled observations before prioritizing edges.