Skip to main content

Installation

AREE is a standard Python src-layout package plus Nextflow workflows and a Streamlit app. This page covers the Python package, which is what the aree CLI, harmonization, meta-analysis, and prioritization code depend on.

Requirements

  • Python >= 3.9
  • pip
  • (optional) Quarto if you plan to render docs/ as a static site
  • (optional) Nextflow + Docker/Apptainer if you plan to execute the raw-data workflows under workflows/ — see roadmap.md for the current status of that path

Install

Create and activate a virtual environment, then install AREE in editable mode with the dev and app extras:

python3 -m venv .venv
source .venv/bin/activate

# Python 3.9's bundled pip is too old for editable installs — upgrade first.
pip install --upgrade pip setuptools wheel

pip install -e ".[dev,app]"

This installs the packages declared in pyproject.toml’s [tool.setuptools] table — aree, common, intake, harmonize, meta_analysis, prioritize, reporting, validation, mappings, query — all under the src/ layout, plus:

  • core runtime dependencies: click, pyyaml, pandas, numpy, scipy, jsonschema, tabulate
  • dev extra: pytest, ruff
  • app extra: streamlit

The aree console script is registered via [project.scripts] and becomes available on your PATH once the package is installed.

Alternative: one conda environment for everything

To run the workflows natively, not just the Python package, use environment.yml. It adds git, Nextflow 26.04, Salmon, fastp, FastQC, MultiQC, R with DESeq2/tximport/limma and Quarto. Python and Nextflow track the CI versions; several bioinformatics and R packages are unpinned, so the resolved environment can differ from CI. It needs no system compilers or Homebrew, so it also works on a Mac without the Xcode Command Line Tools:

# Miniforge: https://github.com/conda-forge/miniforge
conda env create -f environment.yml
conda activate aree
pip install -e ".[dev,app,intake]"

Activate the environment before running Nextflow or Quarto, since it sets JAVA_HOME. methylKit has no Apple Silicon build on bioconda. Install it from R with BiocManager::install("methylKit"), or run the methylation raw path on Linux.

Verify the install

aree --help
aree list-studies

list-studies reads registry/study_registry.csv, a generated index that is not committed. On a freshly cloned repo it does not exist yet, so build it from the study YAMLs once:

aree build-registry

(Re-running plain register-study on an already-registered study fails by design — pass --update to overwrite, or use make demo, which is idempotent. See adding_a_study.md.)

Running the demo end to end

Once installed, the full demo pipeline runs against the committed demo data with no external downloads:

aree validate-study registry/demo_studies/GIGAS_HEAT01.yaml
aree harmonize --study GIGAS_HEAT01
aree meta-analyze --phenotype thermal_tolerance --feature-type gene
aree build-evidence-cards --phenotype thermal_tolerance

See adding_a_study.md, interpreting_meta_analysis.md, and interpreting_candidate_scores.md for what each step produces.

Launching the interface

streamlit run app/main.py

or, for the static documentation/report site:

pip install -e ".[site]"
aree build-dashboard
aree export-site-data
quarto render docs/

Neither requires login or a cloud deployment — both run against local files (registry/, reports/). See architecture.md for how the interface layer relates to the rest of the system.