adjudicator

Adjudicator

Version: 1.0.0 · License: Apache-2.0 · Status: Production/Stable
PyPI: pip install adjudicator · Source: ncgr/Adjudicator
Author: Connor Cameron · ctc@ncgr.org · National Center for Genome Resources

---

Overview

Adjudicator is a command-line tool for collapsing and filtering structural genome annotations across multiple sources. It uses best-hit HMM domain scores from gene family assignments (via the Legume Information System) to compare overlapping gene models and select the best-supported annotation for all overlapping models.

Two commands are provided:

• collapse — Merge overlapping gene models from two or more annotators, selecting the best model per region.
• repeat-filter — Remove gene models that overlap known repeat or transposon regions beyond a configurable coverage threshold.

---

Requirements

---

Installation

pip install adjudicator

adjudicator --version
# adjudicator, version 0.1.0

---

Input File Formats

TSV Sample Sheet (--input-tsv)

Tab-separated. Lines beginning with # and blank lines are skipped.

Row order determines precedence when gene models have equivalent scores.

# label	gff3_path	gfa_path
maker	/data/ann/maker.gff3	/data/fam/maker.gfa
helixer	/data/ann/helixer.gff3	/data/fam/helixer.gfa
stringtie	/data/ann/stringtie.gff3	/data/fam/stringtie.gfa

GFF3 (.gff3)

Standard GFF3 format with a three-level hierarchy: gene → mRNA → exon. See the GFF3 specification.

GFA (.gfa)

LIS gene family assignment files produced by the Legume Information System gene family pipeline.

---

Commands

collapse

Collapses overlapping structural annotations across all entries in the TSV. Processing is hierarchical: Row 1 vs. Row 2 produces an intermediate result, which is then compared against Row 3, and so on.

Synopsis

adjudicator collapse --input-tsv <FILE> [OPTIONS]

Options

Output Files

<output-dir>/
├── A_B.wao.gff3                       # Overlap intersections
├── A_B.unique_b.gff3                  # Gene models unique to annotator B
├── A_B.final.gff3                     # Adjudicated gene IDs
├── A_B.gfa                            # Merged gene family assignments
└── A_B.final.wsubfeatures.gff3        # ✅ Primary output

Examples

adjudicator collapse \
    --input-tsv samples.tsv \
    --output-dir results/collapse/

adjudicator collapse \
    --input-tsv samples.tsv \
    --no-orphans \
    --min-overlap 0.4 \
    --output-dir results/collapse/ \
    --verbose

---

repeat-filter

Filters gene models from each entry in the TSV against a reference repeat annotation. Gene models whose exons exceed --max-coverage overlap with a repeat region are removed.

Synopsis

adjudicator repeat-filter --input-tsv <FILE> --annotation <FILE> [OPTIONS]

Options

Output Files

<output-dir>/
├── <label>_repeat_filter.wao.gff3                  # Overlap intersections
└── <label>_repeat_filter.final.wsubfeatures.gff3   # ✅ Primary output

Examples

adjudicator repeat-filter \
    --input-tsv samples.tsv \
    --annotation repeats.gff3 \
    --output-dir results/filtered/

adjudicator repeat-filter \
    --input-tsv samples.tsv \
    --annotation transposons.gff3 \
    --max-coverage 0.3 \
    --output-dir results/filtered/ \
    --strict \
    --verbose

---

Workflow

# Step 1: Filter repeat regions
adjudicator repeat-filter \
    --input-tsv raw_samples.tsv \
    --annotation repeats.gff3 \
    --output-dir step1_filtered/

# Step 2: Rewrite TSV to point to filtered outputs (GFA paths unchanged)
awk -F'\t' 'OFS="\t" { $2="step1_filtered/"$1"_repeat_filter.final.wsubfeatures.gff3"; print }' \
    raw_samples.tsv > filtered_samples.tsv

# Step 3: Collapse filtered annotations
adjudicator collapse \
    --input-tsv filtered_samples.tsv \
    --output-dir step2_collapsed/

---

Error Reference

---

Glossary