🚀 Quick Start Guide

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

🛠️ Command Overview

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

$ gratools
Welcome to GraTools version: '1.1.0'
@author: GraTools team's
        ____                 __________               ____          
      6MMMMMb/               MMMMMMMMMM               `MM          
     8P    YM               /   MM     \               MM          
    6M      Y ___  __    ___    MM   _____     _____   MM   ____   
    MM        `MM 6MM  6MMMMb   MM  6MMMMMb   6MMMMMb  MM  6MMMMb\ 
    MM         MM69 " 8M'  `Mb  MM 6M'   `Mb 6M'   `Mb MM MM'    ` 
    MM     ___ MM'        ,oMM  MM MM     MM MM     MM MM YM.      
    MM     `M' MM     ,6MM9'MM  MM MM     MM MM     MM MM  YMMMMb  
    YM      M  MM     MM'   MM  MM MM     MM MM     MM MM      `Mb 
     8b    d9  MM     MM.  ,MM  MM YM.   ,M9 YM.   ,M9 MM L    ,MM 
      YMMMMM9  _MM_   `YMMM9'Yb_MM_ YMMMMM9   YMMMMM9 _MM_MYMMMM9 
        \                                    /                /
        /''A''\          /''''''\           /     /''''A'''''\
  ...GC|       |..ATG...C...CG...T....TAG..'..GC.|            |...
        \..C../      \.............../            \...TATA.../
 
Please cite our gitlab: https://forge.ird.fr/diade/gratools.git\

Usage: gratools [OPTIONS] COMMAND [ARGS]...

  A toolkit for analyzing, manipulating, and extracting information from
  pangenome graphs in GFA format.

Options:
  -v, --version  Show the version and exit.
  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 
  -h, --help     Show this message and exit.

GFA Content Information:
  list_samples (samples)
     List the samples embedded in the imported GFA file.

  list_chr (chr)
     List the embedded chromosomes and their fragments if relevant from the
     imported GFA file.

  stats
     Compute and display various statistics for a GFA file.

GFA Data Extraction:
  get_subgraph (subgraph)
     Extracts a subgraph from a GFA file based on a query region.

  get_fasta (fasta)
     Extracts sequences for a specific genomic region in FASTA format.

  to_bandage
     Generates a CSV file for the Bandage graph visualizer.

GFA Analysis:
  pan_ratio (ratio)
     Compute and display the ratio of core and dispensable segments.

  depth_nodes_stat (dns)
     Display various statistics about segment depth (number of embedded
     samples).

  specific_groups_sample (groups)
     Identify segments shared by or specific to defined sample groups.

  get_segments_by_depth (depth)
     List segments within a specified depth range (number of encompassing
     samples).

Other commands:
  import
     Pre-processes a GFA file for faster GraTools operations.

  shell_completion
     Generates shell completion scripts (Bash, Zsh, Fish).

—

📖 Command Examples

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

—

🔄 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.