hub / github.com/Baohua-Chen/GFFx

github.com/Baohua-Chen/GFFx @v0.4.0

repository ↗ · DeepWiki ↗ · release v0.4.0 ↗ · + Follow

119 symbols 268 edges 23 files 56 documented · 47% ● updated 6mo agov0.4.0 · 2025-09-17★ 431 open issues

What it actually does AI analysis from the code graph — generated when you open this

loading…

README

GFFx Command Line Manual

GFFx is a high-performance, Rust-based toolkit for extracting and querying annotations from GFF3 files. It supports fast indexing and feature retrieval with several subcommands. It can be used both as a command-line tool and as a Rust library.

Benchmarking results

Benchmarking runtime and memory usage of ID-based feature extraction

Breaking Changes

Added two useful functionalities: coverage for calculating breadth of coverage and depth for calculating depth of coverage from BAM/SAM/CRAM or BED files on a GFF file.

Added a sample functionality for random downsampling of feature groups from each chromosome at equal ratios.

Updated module organization and source code directory layout to conform to the Rust 2024 edition guidelines for module visibility (pub) and path imports.

GFFx version 0.4.0

Installation
Basic Usage
index - Build index files
extract - Extract features by ID
intersect - Extract features by regions
search - Search features by attributes
coverage - Calculate coverage breadth
depth - Calculate coverage depth
sample - Randomly downsample feature groups
Example Use Cases
Using GFFx as a Rust Library
Available Public APIs
Index File Types
License
Citation

Installation

Option 1: Install via crates.io

cargo install gffx                  # install to default location (~/.cargo/bin)
cargo install gffx --root /your/path  # optional: install to custom location

Option 2: Install from source

git clone https://github.com/Baohua-Chen/GFFx.git
cd GFFx
cargo build --release
# Optionally copy the binary
cp target/release/gffx /your/path

> Requires Rust 1.70 or later. You can install or update Rust using rustup.

Basic Usage

gffx <SUBCOMMAND> [OPTIONS]

Available subcommands:

[index] Build index files
[intersect] Extract features by region
[extract] Extract features by ID
[search] Search features by attribute

`index`

Builds index files from a GFF file to accelerate downstream operations.

gffx index [OPTIONS] --input <INPUT>

Options:

Option	Description
`-i`, `--input`	Input GFF file
`-a`, `--attribute`	Attribute key to extract (default: `gene_name`)
`-v`, `--verbose`	Enable verbose output
`-h`, `--help`	Print help

`intersect`

Extracts models intersecting with regions from a GFF file, either from a single region or a BED file.

gffx intersect [OPTIONS] --input <INPUT> <--region <REGION>|--bed <BED>>

Options: Required | Option | Description | | --------------------------- | ------------------------------------------------------------ | | -i, --input <INPUT> | Input GFF file path | | -r, --region <REGION> | Single region in chr:start-end format | | -b, --bed <BED> | BED file containing multiple regions |

Note: Exactly one of --region or --bed must be specified.

Optional | Option | Description | | ------------------------- | ------------------------------------------------------------------------------ | | -o, --output <OUT> | Output file path (default: stdout) | | -e, --entire-group | Enable the "entire-group" mode. Return entire gene models or feature groups | | | for all matched features, instead of only the directly matched features. | | -v, --invert | Invert selection (exclude matched features) | | -T, --types <TYPES> | Filter output to include only features of specified types (e.g., gene,exon) | | -t, --threads <NUM> | Number of threads [default: 12] | | -V, --verbose | Enable verbose output | | -h, --help | Show help message | | (one of) | | | -c, --contained | Only keep features fully contained within the region | | -C, --contains-region | Only keep features that fully contain the region | | -O, --overlap | Keep features that partially or fully overlap (default mode) |

`extract`

Extracts annotation models by feature ID(s), including their parent models.

gffx extract [OPTIONS] --input <INPUT> <--feature-file <FEATURE_FILE>|--feature-id <FEATURE_ID>>

Options:

Required | Option | Description | | ---------------------------------------- | ------------------------------------------------------------ | | -i, --input <INPUT> | Input GFF file path | | (one of) | | | -f, --feature-id <FEATURE_ID> | Extrach by a single feature id | | -e, --feature-file <FEATURE_FILE> | Extrach by a BED file containing multiple regions |

`search`

Searches for features using a specified attribute value and retrieves the full annotation models.

gffx search -a geneX -i input.gff

Options:

Required | Option | Description | | ---------------------------------------- | ------------------------------------------------------------ | | -i, --input <INPUT> | Input GFF file path | | (one of) | | | -a, --attr <ATTRIBUTE_VALUE> | Search a single attribute value/pattern | | -A, --attr-list <ATTRIBUTE_LIST> | Search attribute values/patterns defined in a text file |

Optional | Option | Description | | ------------------------- | ------------------------------------------------------------------------------ | | -o, --output <OUT> | Output file path (default: stdout) | | -e, --entire-group | Enable the "entire-group" mode. Return entire gene models or feature groups | | | for all matched features, instead of only the directly matched features. | | -r, --regex <REGEX> | Enable regex matching for attribute values | | -T, --types <TYPES> | Filter output to include only features of specified types (e.g., gene,exon) | | -t, --threads <NUM> | Number of threads [default: 12] | | -V, --verbose | Enable verbose output | | -h, --help | Show help message |

`coverage`

Compute coverage breadth across genomic feature.

gffx coverage -i input.gff -s source.bam

Options:

` | Source file in BAM/SAM/CRAM or BED format |

`depth`

Compute coverage depth across genomic feature.

gffx depth -i input.gff -s source.bam

Options:

` | Source file in BAM/SAM/CRAM or BED format |

Optional | Option | Description | | ------------------------- | ------------------------------------------------------------------------------ | | -o, --output <OUT> | Output file path (default: stdout) | | --bin-shift <BIN_SHIFT> | Bin width parameter (2^k bp) for spatial bucketing of features and queries. | | | Choose k so that a typical read and feature span ~1–2 bins [default: 12] | | -e, --entire-group | Enable the "entire-group" mode. Return entire gene models or feature groups | | | for all matched features, instead of only the directly matched features. | | -t, --threads <NUM> | Number of threads [default: 12] | | -V, --verbose | Enable verbose output | | -h, --help | Show help message |

`sample`

Ramdomly downsample feature groups.

gffx sample -i input.gff -r 0.33

Options:

Optional | Option | Description | | ------------------------- | ------------------------------------------------------------------------------ | | -o, --output <OUT> | Output file path (default: stdout) | | -t, --threads <NUM> | Number of threads [default: 12] | | -V, --verbose | Enable verbose output | | -h, --help | Show help message |

Example Use Cases

```bash

Build index

gffx index -i genes.gff -a gene_name

Extract all features overlapping with a region

gffx intersect --region chr1:10000-20000 -i genes.gff -o out.gff -F

Extract models from a l

Core symbols most depended-on inside this repo

is_empty

called by 53

src/index_loader/a2f.rs

get

called by 37

src/index_loader/gof.rs

src/index_loader/gof.rs

bin_of

called by 5

src/commands/depth.rs

safe_mmap_readonly

called by 5

src/index_loader/core.rs

write_gff_output

called by 4

src/utils/common.rs

Shape

Function 55

Method 37

Class 24

Enum 3

Languages

Rust100%

Modules by API surface

src/commands/depth.rs13 symbols

src/commands/coverage.rs13 symbols

src/commands/intersect.rs12 symbols

src/utils/common.rs10 symbols

src/utils/tree.rs9 symbols

src/index_loader/prt.rs9 symbols

src/index_loader/a2f.rs9 symbols

src/index_loader/gof.rs8 symbols

src/index_loader/fts.rs8 symbols

src/utils/tree_io.rs6 symbols

src/index_builder/core.rs5 symbols

src/utils/tree_index.rs3 symbols

For agents

$ claude mcp add GFFx \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact

github.com/Baohua-Chen/GFFx @v0.4.0

GFFx Command Line Manual

Breaking Changes

Table of Contents

Installation

Option 1: Install via crates.io

Option 2: Install from source

> Requires Rust 1.70 or later. You can install or update Rust using rustup.

Basic Usage

`index`

`intersect`

`extract`

`search`

`coverage`

`depth`

`sample`

Example Use Cases

Build index

Extract all features overlapping with a region

Extract models from a l

Core symbols most depended-on inside this repo

Shape

Languages

Modules by API surface

For agents

Ask about this repo answers extend the page