Diploid map long read changes

[Sagorikanag]

Changelog Entry

To be copied to the draft changelog by merger:

• vg surject now supports haplotype-aware surjection with --diploid-map, jointly processing a read's graph placements, selecting one overall primary alignment, and reporting a global quality along with haplotype and alignment confidence in the hp, hq, and aq tags.

Description

This PR adds haplotype-aware diploid surjection for long-read GAM and GAF
input through the new --diploid-map NAME option.

vg surject processes each input graph alignment independently.
However, vg giraffe output can contain a primary graph placement and
one or more secondary graph placements for the same read. Processing these
records independently does not allow all haplotype-path surjections to be compared
at the read level.

With --diploid-map, consecutive GAM or GAF records sharing a read name are
processed together. Each graph placement is surjected to all overlapping
paths belonging to the requested reference assembly. The resulting
haplotype-path surjections are annotated individually and then pooled so that
one overall primary alignment and one read-level Global Quality can be
selected across the complete candidate set.

Specifying --diploid-map NAME:

• selects paths belonging to reference assembly NAME, similarly to
  --into-ref;
• enables multimap surjection so all relevant haplotype-path candidates are
  available;
• groups consecutive input records with the same read name;
• compares haplotype paths within each source graph placement;
• compares the pooled surjections from every graph placement;
• selects one overall primary non-supplementary alignment;
• marks the remaining competing alignments secondary;
• emits the lowercase hp, hq, and aq tags.

Output tags

The following lowercase tags are added to non-supplementary surjections:

• hp:Z:pri_hap or hp:Z:sec_hap identifies the preferred and alternative
  haplotype-path surjections for each source graph placement.
• hq:i:<quality> reports confidence in the haplotype choice.
• aq:i:<quality> preserves the original Giraffe MAPQ before output MAPQ is
  replaced with Global Quality.

Haplotype quality is calculated within each source graph placement. After
all graph placements and haplotype surjections for a read are pooled, the
highest-scoring candidate becomes the overall primary and the remaining
candidates become secondary.

Global Quality measures confidence in that overall primary relative to all
other non-supplementary candidates. It is written to the output MAPQ field,
restricted to 0-60, and capped by aq so surjection cannot report greater
confidence than the original graph mapping. Equal top scores use vg's
deterministic Giraffe-style tie-breaking.

Dependencies

• Depends on Add grouped parallel I/O for graph placements of unpaired reads libvgio#93.
• This PR is currently stacked on the mapper-declared tail pruning and
  disjoint-interval classification changes. The branch will be rebased onto
  master after those changes merge.