Skip to main content

AGENT-P

AGENT-P (Association of Gene Expression to Neuroimaging Traits Pipeline) is a Python package for transcriptome-wide association studies (TWAS) of brain traits.

It predicts how much each gene is expressed in the brain from a person's genotypes (genetically regulated gene expression, or GREx), and tests whether this predicted expression is associated with a trait, such as the volume of a brain region. AGENT-P includes ready-to-use expression models for 8 brain regions from 4 TWAS methods, and runs TWAS in two ways:

Input AGENT-P class
Summary-level TWAS GWAS summary statistics of the trait SummaryTWAS
Genotype-level TWAS genotypes, covariates, and trait values of individual subjects IndividualTWAS

AGENT-P can also combine the results of all models into one p-value per gene (ACAT), make Manhattan, Miami, and scatter plots, and run a GWAS with REGENIE.

Try it online, without installing anything: AGENT-P example in Google Colab

Contents

  1. Install
  2. Download the models
  3. Run the example
  4. Run your own analysis
  5. Results and plots
  6. Run all models and combine them (ACAT)
  7. Available models
  8. More options
  9. Troubleshooting

1. Install

AGENT-P runs on Linux and macOS. The easiest way to install it is with conda (if you do not have conda, install Miniforge first). Open a terminal and run:

git clone https://github.com/nhunghoang/agentp.git
cd agentp
conda env create -f environment.yml      # takes 5-15 minutes
conda activate agentp
pip install --no-deps -e .
R CMD INSTALL agentp/external/plink2R/plink2R

This installs AGENT-P with everything it needs: Python packages, the genetics tools plink2, bgenix, and regenie, and R for the FUSION models. The commands in steps 2 and 3 are run from this agentp folder.

On a Mac with an Apple chip (M1-M4), replace the conda env create line with the one below (the genetics tools are only available for Intel Macs, and run through Rosetta), and run conda config --env --set subdir osx-64 after conda activate agentp:

CONDA_SUBDIR=osx-64 conda env create -f environment.yml

Each time you open a new terminal, run conda activate agentp before using AGENT-P.


2. Download the models

The expression models (about 2 GB) are not included in the GitHub repository. Download models.tar.gz and extract it into the agentp folder inside the repository:

cd agentp                                # the "agentp" folder inside the downloaded repository
tar -xzf ~/Downloads/models.tar.gz       # change the path if you saved the file elsewhere
cd ..

The models are now in agentp/models. You can skip this step if you only want to run the example in step 3, which uses a small set of example models.


3. Run the example

The example uses a small dataset of 2,000 subjects that comes with AGENT-P. It runs both TWAS for one brain region (caudate) and one trait (amygdala volume):

cd example
python run_example.py

When it finishes, open the plots in example/example_run/figures/: a Manhattan plot (manhattan.png) and a Miami plot (miami.png). The Colab notebook walks through the same example step by step.


4. Run your own analysis

Write the steps below in a Python script (for example my_analysis.py), and run it with python my_analysis.py.

Step 1: Create a project

A project is a folder that keeps the inputs and results of one cohort together.

from agentp import Project
project = Project('my_project')     # creates the folder "my_project"

Step 2a: Summary-level TWAS (from a GWAS)

from agentp import SummaryTWAS

stwas = SummaryTWAS(project, 'JTI', 'caudate')                  # model method and brain region
stwas.add_gwas('putamen_volume', 'putamen_volume_gwas.txt')     # trait name and GWAS file
stwas.run_twas('putamen_volume')

The GWAS file needs one row per SNP, with these columns: SNP ID (rsID), the two alleles, and the effect size (beta) with its standard error or a p-value. Output files of REGENIE (and of AGENT-P's own GWAS) are read without any extra settings. For other files, tell AGENT-P the column names:

stwas.add_gwas('putamen_volume', 'putamen_volume_gwas.txt', sep='\t',
               snp_col='rsid', alt_col='a2', ref_col='a1',
               beta_col='beta', beta_se_col='se', pval_col='pval')
  • alt_col is the effect allele: the allele that the beta refers to. ref_col is the other allele.
  • If your file has a z-score or odds ratio instead of a beta, use zscore_col or or_col.

Step 2b: Genotype-level TWAS (from individual-level data)

First add the subject data to the project (only once per project):

project.set_subjects('subjects.txt')             # subject IDs
project.add_covariates('covariates.txt')         # e.g. age, sex, genetic principal components
project.add_phenotypes('phenotypes.txt')         # one or more traits
project.add_genotypes('genotypes', 'chr*.bgen')  # folder, and file names with * for the chromosome number

Then predict gene expression and test the traits:

from agentp import IndividualTWAS

itwas = IndividualTWAS(project, 'JTI', 'caudate')
itwas.predict_grex()                         # predict gene expression (once per method and region)
itwas.run_twas('putamen_volume')             # or a list: ['putamen_volume', 'caudate_volume']

Input files (see example/example_data for examples):

File Format
Subject IDs one ID per line, no header
Covariates a table with an id column and one column per covariate (numbers only, e.g. sex as 0/1); tab-separated by default
Phenotypes a table with an id column and one column per trait; tab-separated by default
Genotypes one BGEN file per chromosome (1-22), each with a matching .sample file, and SNP IDs as rsIDs
  • The subject IDs must be the same in all files (in the .sample files, both ID columns).
  • To use only some columns, add covar_cols=[...] or phen_cols=[...].
  • AGENT-P cleans the genotypes before use: it keeps SNPs with less than 5% missing calls, a minor allele frequency of at least 1%, and a Hardy-Weinberg equilibrium p-value above 1e-5.
  • Genotypes in VCF format can be converted to BGEN with plink2 (see Troubleshooting).

5. Results and plots

Each TWAS saves one table per trait (tab-separated, one row per gene):

TWAS Results file
Summary-level my_project/sTWAS/JTI_caudate/putamen_volume.csv
Genotype-level my_project/iTWAS/JTI_caudate/putamen_volume.csv

The most important columns are gene (Ensembl gene ID), zscore (direction and strength of the association: positive means that higher expression goes with a larger trait value), and pvalue. A common threshold for significance is a Bonferroni correction: p < 0.05 / (number of genes tested).

Plots (saved as image files):

from agentp import load_pvalues, manhattan_plot, miami_plot, scatter_plot

s = load_pvalues('my_project/sTWAS/JTI_caudate/putamen_volume.csv')
g = load_pvalues('my_project/iTWAS/JTI_caudate/putamen_volume.csv')

manhattan_plot(g, label='Genotype-level TWAS', out_file='manhattan.png')        # one set of results
miami_plot(s, g, top_label='Summary-level TWAS', bottom_label='Genotype-level TWAS',
           out_file='miami.png')                                                # two sets, mirrored
scatter_plot(s, g, x_label='Summary-level TWAS', y_label='Genotype-level TWAS',
             out_file='scatter.png')                                            # two sets, gene by gene

Significant genes (Bonferroni) are colored, and the dashed lines show the significance thresholds.


6. Run all models and combine them (ACAT)

run_all_twas runs TWAS with every model (4 methods x 8 brain regions = 32 model sets), then combines the p-values of each gene into one p-value with ACAT (Aggregated Cauchy Association Test):

from agentp import run_all_twas

# summary-level TWAS
run_all_twas(project, 'putamen_volume', twas_type='stwas',
             gwas_files={'putamen_volume': 'putamen_volume_gwas.txt'})

# genotype-level TWAS (after adding the subject data, step 2b)
run_all_twas(project, 'putamen_volume', twas_type='itwas')

The combined results are saved to my_project/sTWAS/ACAT/putamen_volume.csv (or iTWAS/ACAT/). This table has one p-value column per model set, n_models (how many models tested the gene), and the combined p-value (sTWAS_ACAT or iTWAS_ACAT). Genes tested by fewer than 4 models get no combined p-value.

If your GWAS file is not in REGENIE format, give the column names once for all files: gwas_params={'sep': '\t', 'snp_col': 'rsid', 'alt_col': 'a2', ...}. To combine results that you already ran one model at a time, use collect_twas(project, 'putamen_volume').


7. Available models

Method Code Brain region Code
PrediXcan PDX Dorsolateral prefrontal cortex dlpfc
UTMOST UTM Anterior cingulate cortex ant-cingulate
JTI (Joint-Tissue Imputation) JTI Amygdala amygdala
FUSION FUS Hippocampus hippocampus
Caudate caudate
Putamen putamen
Nucleus accumbens nuc-accumbens
Cerebellar hemisphere cerebellar-hemi

Any method can be combined with any region, e.g. SummaryTWAS(project, 'FUS', 'hippocampus').

Adding other models. Models in PredictDB format (a .db weights file and a .txt.gz covariance file, e.g. other GTEx tissues) can be added and then used like the built-in ones:

project.add_model('PDX', 'hypothalamus', weights='en_Brain_Hypothalamus.db',
                  covariance='en_Brain_Hypothalamus.txt.gz')
stwas = SummaryTWAS(project, 'PDX', 'hypothalamus')

8. More options

  • Run a GWAS (needs the subject data from step 2b):
    from agentp import GWAS
    GWAS(project).run(['putamen_volume', 'caudate_volume'])    # saved to my_project/GWAS/
    
  • Run again and replace old results: add overwrite=True, e.g. stwas.run_twas('putamen_volume', overwrite=True). Without it, AGENT-P skips results that already exist.
  • Several traits in parallel: run_twas([...], num_threads=4) runs 4 traits at the same time.
  • Test the installation with the full models: python tests/test_pipeline.py (add --fusion to include FUSION).

9. Troubleshooting

  • git clone fails with an error about "LFS" or "smudge filter". Clone without the large files (the models come from step 2 anyway): GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/nhunghoang/agentp.git.

  • conda env create is very slow or runs out of memory. Use micromamba with the same file: micromamba create -f environment.yml.

  • numpy or h5py errors after installing. AGENT-P was installed without --no-deps, and pip replaced conda's packages. Remove the environment (conda env remove -n agentp) and install again as in step 1.

  • On a Mac: "incompatible architecture". The environment was created without CONDA_SUBDIR=osx-64. Remove it and create it again as in step 1. The first run on a Mac can take a few extra minutes while Rosetta translates the programs.

  • My genotypes are in VCF format. Convert them to BGEN, one file per chromosome:

    for c in $(seq 1 22); do
        plink2 --vcf chr${c}.dose.vcf.gz dosage=DS --double-id --export bgen-1.2 bits=8 --out genotypes/chr${c}
    done
    

    SNP IDs must be rsIDs. If your VCF uses other IDs (e.g. chr1:12345:A:G), add rsIDs first (e.g. with bcftools annotate and a dbSNP file).

  • Very few genes are tested. The SNP IDs in your GWAS or genotypes do not match the models: check that they are rsIDs.


License

MIT (see LICENSE).

Metadata

Release files for agentp 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentp 0.2.0
File Size Uploaded Provenance Actions
agentp-0.2.0.tar.gz 7.5 MB Without provenance Details for agentp-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agentp 0.2.0
File Interpreter ABI Platform Actions
agentp-0.2.0-py3-none-any.whl Python 3 none any Details for agentp-0.2.0-py3-none-any.whl

Total release size: 15.1 MB

Release files / agentp-0.2.0.tar.gz

Download URL agentp-0.2.0.tar.gz
Size 7.5 MB
Tags Source
SHA-256 checksum
How to use checksums
01eaa89e53f4306a1d1f63dbecf4efd1d10dfcecc7efe5ab86843dfc2fc89a5f
BLAKE2b-256 checksum
How to use checksums
908c07fc3fd5c56037d648af77a541c2323f073a9a5a6277bbf437579220b327
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Release files / agentp-0.2.0-py3-none-any.whl

Download URL agentp-0.2.0-py3-none-any.whl
Size 7.6 MB
Tags Python 3
SHA-256 checksum
How to use checksums
ab7263fd04cfd18d40f51f797f82368ae6d39cc09499aab1f08f93f2e81c8862
BLAKE2b-256 checksum
How to use checksums
27e099d8feb2f123bbfc1b415b1ed23e413b004dc51aee93eeede81959a0af4a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Security for agentp 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page