gratools depth_nodes_stat

Summarize how segments are shared across samples by calculating their ‘depth’.

🧬 Understanding Node Depth

This command analyzes the distribution of every segment in your graph. The Depth represents the number of unique samples passing through a segment.

Depth = 1: Private segments (specific to one individual).
Depth = N: Core segments (shared by all N individuals).

🛠️ Options

View Command Line Options

$ gratools depth_nodes_stat
Welcome to GraTools version: '1.2.0.dev19'
@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 depth_nodes_stat [OPTIONS]
Aliases: dns

  This command computes how segments are shared across different samples by
  calculating the 'depth' of each segment (i.e., the number of unique samples
  encompassing it). It outputs a table showing the count of segments for each
  depth level. An optional length filter can be applied to consider only
  segments above a certain size for a 'filtered' count. Results are displayed in
  the terminal and saved to a CSV file. This command relies on a pre-existing
  GraTools import.
  
  For more details, see the full documentation:
  https://gratools.readthedocs.io/en/latest/commands/depth_nodes_stat.html

Node Depth Statistics Options:
  -g, --gfa PATH
     Path to the input GFA file (e.g., myGraph.gfa or myGraph.gfa.gz).
     [required]

  -o, --outdir DIRECTORY
     Output directory for GraTools results. If not specified, results are
     typically placed in a subdirectory within the GFA file's parent directory
     (e.g., 'GraTools-output_<gfa_name>').

  -su, --suffix TEXT
     Custom suffix to append to output filenames. If not provided, a default
     suffix will be generated based on the command line parameters.

  -fl, --filter-len INTEGER
     Minimal segment length (bp) to be considered in the depth count. A value of
     0 means no length filter.  [default: 0]

Logging Options:
  -vv, --verbosity [DEBUG|INFO|ERROR]
     Set the logging verbosity level.  [default: INFO]

  -l, --log-path DIRECTORY
     Directory where the log files will be saved. If not specified, logs will be
     placed in the main output directory (or in a default GraTools log
     location).

Performance Options:
  -t, --threads INTEGER
     Number of threads to be used for parallelizable operations.  [default: 1]

Other options:
  -h, --help
     Show this message and exit.

▶️ Usage Examples

📊 Node Depth Distribution

Analyze how segments are shared while filtering out very short segments (e.g., < 50 bp) to focus on structural content.

$ gratools depth_nodes_stat --gfa Og_cactus.gfa.gz --filter-len 50 --threads 4

Output Summary:

────────────────  Summary ────────────────────────────────────────
Total segments analyzed: 2,354,995
Total segments passing length filter: 210,046 (8.92%)

          Node Depth Statistics — Og_cactus (Len ≥ 50bp)
╭───────┬──────────┬────────────┬───────────────────┬────────────╮
│ Depth │ Segments │ Percentage │ Filtered Segments │ Filtered % │
├───────┼──────────┼────────────┼───────────────────┼────────────┤
│   1   │ 575,292  │   24.43%   │       1,257       │   0.60%    │
│   2   │ 316,053  │   13.42%   │       7,345       │   3.50%    │
│   3   │ 301,588  │   12.81%   │       5,604       │   2.67%    │
│   4   │ 501,321  │   21.29%   │      11,500       │   5.47%    │
│   5   │ 660,741  │   28.06%   │      184,340      │   87.76%   │
╰───────┴──────────┴────────────┴───────────────────┴────────────╯

📖 Understanding the Output

Table Columns

Depth: Number of unique samples containing the segment.
Segments: Raw count of segments at this depth.
Percentage: Proportion relative to the total GFA segments.
Filtered Segments: Count of segments at this depth longer than --filter-len.
Filtered %: Proportion relative to the total filtered segments.

🔍 Filter Logic

The --filter-len (or -fl) option is crucial for pangenome analysis.

In many graphs, a high percentage of segments are very short (1-10 bp) and correspond to small polymorphisms. Filtering by length allows you to see the distribution of larger genomic blocks, which often show a much higher conservation (Core genome).

💡 Insight

Compare the Percentage column with the Filtered % column. If the Filtered % for the maximum depth is significantly higher than the raw Percentage, it indicates that your “Core Genome” is mostly composed of longer, well-conserved sequences, while “Specific” regions are often made of smaller segments.

📑 Quick Links

Command Import: gratools import
Related Tool: gratools pan_ratio
Explore stats: gratools stats