Welcome to GraTools! This guide will help you install the software and run your first pangenome graph analyses in minutes.

📦 Installation

📋 Requirements

• Python:

• System Tools: Bedtools must be installed.

• Build Tools: For Python ≥ 3.12, build-essential, python3-dev and zlib1g-dev are required to compile dependencies (e.g., pybedtools) if wheels are not available.

🚀 Stable (PyPi)

python3 -m pip install -U pip setuptools
python3 -m pip install gratools

🏗️ Development (Git)

# Replace 'main' with a specific branch or tag if needed
python3 -m pip install GraTools@git+https://forge.ird.fr/diade/gratools.git@main

🐋 Docker / Podman

# Both engines use the same syntax
podman pull registry.forge.ird.fr/diade/gratools/gratools:latest
# or: docker pull registry.forge.ird.fr/diade/gratools/gratools:latest

🚀 Apptainer (HPC)

apptainer pull gratools.sif docker://registry.forge.ird.fr/diade/gratools/gratools:latest

✔️ Verification

🐍 Local (PyPi / Git)

gratools --version
gratools --help

🐋 Docker / Podman

# Mount current directory to /data (default WORKDIR)
podman run --rm -v $(pwd):/data registry.forge.ird.fr/diade/gratools/gratools:latest --version

🚀 Apptainer (HPC)

./gratools.sif --version

📖 Common Workflows by Task

GraTools provides a rich set of subcommands. You can see them all by running gratools --help.

“For the full reference, see GraTools: A Pangenome GFA Toolkit”

Click on the headers below to see example outputs for each major command.

📊 stats: Compute graph statistics

Compute a range of statistics on the graph structure (segments, links, walks, connectivity).

$ gratools stats --gfa Og_cactus.gfa.gz

For more details, see the complete documentation for gratools stats.

👥 list_samples & list_chr: Explore graph content

Lists all unique sample names or chromosomes per sample found in a GFA file.

$ gratools list_samples --gfa Og_cactus.gfa.gz
$ gratools list_chr --gfa Og_cactus.gfa.gz

For more details, see gratools list_samples and gratools list_chr.

✂️ get_subgraph & get_fasta: Data extraction

Extract specific regions defined by sample, chromosome, and positions.

# Extract Subgraph
$ gratools get_subgraph --gfa Og_cactus.gfa.gz \
    --sample-query CG14 --chrom-query CG14_Chr07 \
    --start-query 100000 --stop-query 150000 \
    --all-samples

# Get FASTA
$ gratools get_fasta --gfa Og_cactus.gfa.gz \
    --sample-query CG14 --chrom-query CG14_Chr07 \
    --start-query 10000 --stop-query 15000 \
    --all-samples

For more details, see gratools get_subgraph and gratools get_fasta.

⚖️ pan_ratio & depth_nodes_stat: Pangenome analysis

Analyze how segments are shared across samples (core vs dispensable).

# Ratio Core/Dispensable
$ gratools pan_ratio -g Og_cactus.gfa.gz --input-as-number \
    --shared-min 4 --specific-max 2 --filter-len 50

# Node Depth Summary
$ gratools depth_nodes_stat --gfa Og_cactus.gfa.gz --filter-len 50 --threads 4

For more details, see gratools pan_ratio and gratools depth_nodes_stat.

🔍 specific_groups_sample: Group comparisons

Identify segments shared by or specific to defined sample groups.

$ gratools specific_groups_sample --gfa Og_cactus.gfa.gz \
    --samples-list-A list_A.txt \
    --samples-list-B list_B.txt \
    --output-csv

For more details, see gratools specific_groups_sample.

—

🔄 Typical Workflow

1️⃣ Importing

Crucial first step. Import your GFA file to speed up all future operations.

gratools import --gfa my_graph.gfa.gz

2️⃣ Exploration

Get an overview of your samples and graph properties.

gratools list_samples --gfa my.gfa.gz
gratools stats --gfa my.gfa.gz

3️⃣ Analysis

Perform deep analysis or extract sequences/subgraphs.

gratools get_fasta --gfa my.gfa.gz ...
gratools pan_ratio ...

—

📥 Testing GraTools

Download our curated test dataset to explore functionalities immediately.

📥 Download Dataset

wget http://itrop.ird.fr/GraTools/data-gratools.tar.gz
tar -zxvf data-gratools.tar.gz

Dataset Structure:

data-gratools/
├── Bacteria/ (ecoli_MGC_graph.full.gfa)
├── Bathyprasinos/ (Bathyprasinos_graph.full.gfa.gz)
└── Rice/ (Og_cactus.gfa.gz, NewRiceGraph_MGC.gfa.gz, ...)

—

⚠️ Troubleshooting

🛠️ Setup Issues

• Dependencies: Ensure bedtools is in your system’s PATH.

• Logs: Check GraTools log files in the output directory for precise error messages.

🔄 Data Changes

• Import Mismatch: If you modify your GFA, delete the import directory (*_GraTools-IMPORT/) and run gratools import again.

—

📬 Further Assistance

• Documentation: Browse the sidebar for in-depth command references.

• Issues: Open a ticket on the project’s Git repository.

• Mailing List: Contact us at gratools@ird.fr.