GFF/GTF Pipeline

High-level convenience pipeline for GFF/GTF-based benchmarking.

Wraps the load → map → build-arrays → benchmark steps into a single call, so that common workflows can be expressed in a few lines.

gene_calling_benchmark.pipeline.benchmark_from_gff(gt_path, pred_paths, label_config, metrics=None, *, gt_feature_role_map=None, pred_feature_role_maps=None, transcript_types=None, exclude_features=None, mapping_output_path=None, locus_matching_mode=LocusMatchingMode.FULL_DISCOVERY, infer_introns=False, ignore_novel_predictions=False, ignore_missed_reference=False)[source]

Run the full benchmark pipeline from GFF/GTF files.

This is a convenience wrapper that performs:

Parse GT and prediction GFF/GTF files
Map GT transcripts to predictions (strand-aware, locus-based)
Build paired annotation arrays
Compute all requested metrics

label_config defines the integer label semantics. Feature-role maps control how GFF/GTF feature names are translated to benchmark roles such as "exon", "cds", "five_prime_utr", "three_prime_utr". When omitted, mode-specific defaults are used — EXON_INTRON maps both "exon" and "CDS" to the exon role; UTR_CDS_INTRON maps "five_prime_UTR", "CDS", and "three_prime_UTR" to their respective roles.

Parameters:

gt_path (str | Path) – Path to the ground-truth GFF/GTF annotation file.
pred_paths (dict[str, str | Path]) – {predictor_name: path} for each prediction file.
label_config (LabelConfig) – Token-to-name mapping and semantic label roles.
metrics (list[EvalMetrics] | None) – Metric groups to compute. Defaults to _DEFAULT_METRICS (REGION_DISCOVERY, BOUNDARY_EXACTNESS, NUCLEOTIDE_CLASSIFICATION, STATE_TRANSITIONS) — the same default used by _benchmark_gt_vs_pred_single() / benchmark_from_arrays(), so all entry points agree.
gt_feature_role_map (dict[str, str] | None) – Maps GT GFF/GTF feature types to benchmark roles. When None, the mode-specific default is used.
pred_feature_role_maps (dict[str, str] | dict[str, dict[str, str]] | None) – Maps prediction GFF/GTF feature types to roles. A flat {feature_type: role} dict applies to every predictor; a nested {predictor_name: {feature_type: role}} dict allows predictor-specific parsing. None means every predictor uses the GT role map.
transcript_types (list[str] | None) – Feature types that define transcript boundaries. Defaults to ["mRNA", "transcript"].
exclude_features (list[str] | None) – GFF feature types to ignore (e.g., ["gene"]).
mapping_output_path (str | Path | None) – If given, write the GT-to-prediction mapping table to this path (TSV format, similar to gffcompare’s .loci file).
locus_matching_mode (LocusMatchingMode) – Controls how transcripts are paired within each locus. FULL_DISCOVERY (default) maximises 1:1 matches. BEST_PER_LOCUS keeps only the single best-scoring pair per locus; suited for single-transcript predictors (e.g. Augustus).
infer_introns (bool) – If True, fill background gaps between adjacent coding segments with label_config.intron_label before benchmarking.
ignore_novel_predictions (bool) – gffcompare -Q: exclude prediction transcripts that overlap no GT transcript from both the global precision metrics and the aggregated micro-metrics (incomplete-ground-truth correction). Default False.
ignore_missed_reference (bool) – gffcompare -R: exclude GT transcripts that overlap no prediction from both the global sensitivity metrics and the aggregated micro-metrics (incomplete-prediction correction). Default False.

Returns:

{predictor_name: {"aggregated": ..., "global": ...}} where aggregated is the corpus-level micro-averaged summary returned by benchmark_from_arrays() (not a per-transcript list).

Return type:

dict[str, dict]