Feat/annotate design

.github/workflows/cli.yml

@@ -387,7 +387,7 @@ jobs:
 
       - name: "Check that the git diff is clean"
         run: |
-          git -c color.ui=always diff --exit-code 'docs/docs/reference.md' || (echo "Looks like command-line interface has changed, but the autogenerated CLI reference documentation at 'docs/docs/reference.md' is not up-to-date. Please build the fresh version of pangraph, then run 'cd docs && ./generate-reference-docs <path_to_pangraph> docs/docs/reference.md', then verify and commit changes to the file docs/docs/reference.md." >&2; exit 1)
+          git -c color.ui=always diff --exit-code 'docs/docs/reference.md' || (echo "Looks like the command-line interface has changed, but the autogenerated CLI reference at 'docs/docs/reference.md' is not up-to-date. Please build pangraph, then from the repository root run 'cd docs && ./generate-reference-docs <path_to_pangraph> docs/reference.md' (the executable path is relative to docs/, e.g. ../target/release/pangraph), then verify and commit changes to the file docs/docs/reference.md." >&2; exit 1)
 
 
   publish-to-github-releases:

Cargo.toml

@@ -65,7 +65,7 @@ log = "=0.4.28"
 maplit = "=1.0.2"
 ndarray = { version = "=0.16.1", features = ["rayon", "serde", "blas", "approx"] }
 ndarray-stats = "=0.6.0"
-noodles = { version = "=0.60.0", features = ["core", "sam"] }
+noodles = { version = "=0.60.0", features = ["core", "sam", "gff"] }
 num = "=0.4.3"
 num-traits = "=0.2.19"
 num_cpus = "=1.17.0"

data/example.gff

@@ -0,0 +1,6 @@
+##gff-version 3
+##sequence-region chr1 1 1000
+chr1	prokka	gene	5	30	.	+	.	ID=gene0001;Name=dnaA
+chr1	prokka	CDS	5	30	.	+	0	ID=cds0001;Parent=gene0001;product=replication initiator
+chr1	prokka	gene	50	90	.	-	.	ID=gene0002;Name=repA
+chr2	prokka	misc_feature	10	20	.	.	.	ID=feat0003;note=unstranded

docs/docs/reference.md

@@ -31,6 +31,7 @@ If you have Pangraph CLI installed, you can type `pangraph --help` to read the l
 * [`pangraph export core-genome`↴](#pangraph-export-core-genome)
 * [`pangraph simplify`↴](#pangraph-simplify)
 * [`pangraph reconstruct`↴](#pangraph-reconstruct)
+* [`pangraph annotate`↴](#pangraph-annotate)
 * [`pangraph schema`↴](#pangraph-schema)
 * [`pangraph completions`↴](#pangraph-completions)
 * [`pangraph help-markdown`↴](#pangraph-help-markdown)
@@ -58,6 +59,7 @@ Questions, ideas, bug reports: https://github.com/neherlab/pangraph/issues
 * `export` — Export a pangraph to a chosen file format(s)
 * `simplify` — Generates a simplified graph that only contains a subset of the input genomes
 * `reconstruct` — Reconstruct all input fasta sequences from graph
+* `annotate` — Lift genome annotations onto the pangenome graph
 * `schema` — Generate JSON schema for Pangraph file format
 * `completions` — Generate shell completions
 * `help-markdown` — Print command-line reference documentation in Markdown format
@@ -329,6 +331,33 @@ Reconstruct all input fasta sequences from graph
 
 
 
+## `pangraph annotate`
+
+Lift genome annotations onto the pangenome graph
+
+**Usage:** `pangraph annotate [OPTIONS] --gff <GFF> [INPUT]`
+
+###### **Arguments:**
+
+* `<INPUT>` — Path to Pangraph JSON.
+
+   Accepts plain or compressed file. If a compressed file is provided, it will be transparently decompressed. Supported compression formats: `gz`, `bz2`, `xz`, `zstd`. Decompressor is chosen based on file extension.
+
+   If no input file provided, the uncompressed input is read from standard input (stdin).
+
+###### **Options:**
+
+* `--gff <GFF>` — Path to a GFF3 annotation file. Repeat the flag to provide multiple files.
+
+   Accepts plain or compressed files (`gz`, `bz2`, `xz`, `zstd`), chosen by file extension. At least one file is required. Annotation `seqid`s must match the graph path names exactly.
+* `-o`, `--output <OUTPUT>` — Path to the output node-level annotation table (CSV).
+
+   Will be created if it does not exist. The output is compressed if the path ends in a known compression extension (`gz`, `bz2`, `xz`, `zstd`). Use `-` to write uncompressed CSV to standard output (stdout).
+
+  Default value: `-`
+
+
+
 ## `pangraph schema`
 
 Generate JSON schema for Pangraph file format

packages/pangraph/src/annotation/feature.rs

@@ -0,0 +1,69 @@
+use crate::pangraph::strand::Strand;
+use crate::utils::interval::Interval;
+use serde::{Deserialize, Serialize};
+
+/// A genome annotation feature, normalized from an annotation file (currently GFF)
+/// into a single, format-agnostic representation.
+///
+/// The model is deliberately format-neutral: additional readers (e.g. GenBank) can be
+/// added later without touching anything downstream. Coordinates live in `interval` as
+/// 0-based, half-open `[start, end)` over the genome/contig identified by `seqid`.
+/// Everything downstream (matching, the annotation lift, writers) consumes `Feature`
+/// and never the original file format.
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
+pub struct Feature {
+  /// Identifier of the genome/contig the feature belongs to (GFF `seqid` column).
+  /// Matched against pangraph path names.
+  pub seqid: String,
+
+  /// Free-text provenance of the annotation (GFF `source` column), if any.
+  pub source: Option<String>,
+
+  /// Feature type, e.g. `"CDS"` or `"gene"` (GFF `type` column).
+  pub feature_type: String,
+
+  /// Location on `seqid`, as a 0-based half-open interval `[start, end)`.
+  pub interval: Interval,
+
+  /// Strand of the feature, or `None` when unstranded (e.g. GFF `.` or `?`).
+  pub strand: Option<Strand>,
+
+  /// Stable feature identifier (GFF `ID` attribute), if present.
+  pub id: Option<String>,
+
+  /// Human-readable name (GFF `Name` attribute), if present.
+  pub name: Option<String>,
+
+  /// All remaining key→value metadata, preserving order and duplicate keys.
+  pub attributes: Vec<(String, String)>,
+}
+
+/// Build a 0-based half-open [`Interval`] from 1-based, fully-closed coordinates,
+/// the convention used by GFF.
+///
+/// For example `(1, 3)` (three bases, 1-based inclusive) becomes `[0, 3)`.
+pub fn interval_from_one_based_inclusive(start: usize, end: usize) -> Interval {
+  debug_assert!(start >= 1, "1-based coordinates must be >= 1, got start={start}");
+  Interval::new(start - 1, end)
+}
+
+#[cfg(test)]
+mod tests {
+  use super::*;
+  use pretty_assertions::assert_eq;
+
+  #[test]
+  fn test_interval_from_one_based_inclusive_multibase() {
+    assert_eq!(interval_from_one_based_inclusive(1, 3), Interval::new(0, 3));
+  }
+
+  #[test]
+  fn test_interval_from_one_based_inclusive_single_base() {
+    assert_eq!(interval_from_one_based_inclusive(5, 5), Interval::new(4, 5));
+  }
+
+  #[test]
+  fn test_interval_from_one_based_inclusive_offset() {
+    assert_eq!(interval_from_one_based_inclusive(10, 20), Interval::new(9, 20));
+  }
+}