odgi position

Find, translate, and liftover graph and path positions between graphs. Results are printed to stdout.

SYNOPSIS

odgi position [-i, --target=FILE] [OPTION]…

DESCRIPTION

The odgi position command translates positions and coordinate ranges between nodes and embedded paths. It provides liftover functionality, allowing us to translate a position between any reference paths embedded in the -i, --target graph. We can additionally project coordinates and annotations from a source graph -x, --source into the target. When completing this “graph lift”, the intersecting set of paths in the two graphs are used to complete the coordinate projection.

OUTPUT

Graph positions given with -g, --graph-pos or -G, --graph-pos-file are node identifiers, not linear coordinates: -g 42 means node 42, offset 0, not base 42 of a path.

The output is a tab-separated table. With a reference path (-r, --ref-path or -R, --ref-paths) the columns are:

target.graph.pos

The queried graph position as node_id,offset,strand.

target.path.pos

The nearest position on the reference path, as path_name,offset,strand.

dist.to.ref

Distance in base pairs from the queried node to that reference position. 0 means the node lies on the reference path; a non-zero value means the node is off the reference (for example inside a bubble) and target.path.pos is the nearest reference anchor.

strand.vs.ref

Orientation of the node relative to the reference (+ or -).

Without a reference path the third column is dist.to.path (distance to the nearest embedded path) instead of dist.to.ref. With -v, --give-graph-pos only target.graph.pos is emitted. When lifting from a source graph (-x, --source) a leading source.graph.pos column is added.

Example (reference path chm13__LPA__tig00000001):

# node 3 lies on the reference: dist.to.ref is 0
$ odgi position -i lpa.og -r chm13__LPA__tig00000001 -g 3
#target.graph.pos  target.path.pos              dist.to.ref  strand.vs.ref
3,0,+              chm13__LPA__tig00000001,0,+  0            +

# node 1 is off the reference: nearest anchor is base 5, 38 bp away
$ odgi position -i lpa.og -r chm13__LPA__tig00000001 -g 1
#target.graph.pos  target.path.pos              dist.to.ref  strand.vs.ref
1,0,+              chm13__LPA__tig00000001,5,+  38           +

OPTIONS

MANDATORY OPTIONS

-i, --target=FILE

Load the succinct variation graph in ODGI format from this FILE. The file name usually ends with .og. It also accepts GFAv1 or GFAz (compressed GFA), but the on-the-fly conversion to the ODGI format requires additional time!

Position Options

-x, --source=FILE

Translate positions from this FILE graph into the target graph using common -l, --lift-paths shared between both graphs (default: use the same source/target graph). It also accepts GFAv1 or GFAz (compressed GFA), but the on-the-fly conversion to the ODGI format requires additional time!

-r, --ref-path=STRING

Translate the given positions into positions relative to this reference path STRING.

-R, --ref-paths=FILE

Use the ref-paths in FILE for positional translation.

--all-ref-positions

When multiple reference paths are given (-R, --ref-paths), lift each input range into every reference path, emitting one output line per reference instead of only the nearest one.

-l, --lift-path=STRING

Lift positions from -x, --source to -i, --target via coordinates in this path common to both graphs (default: all common paths between -x, --source and -i, --target).

-L, --lift-paths=FILE

Same as in -l, --lift-paths, but for all paths in FILE.

-g, --graph-pos=[[node_id][,offset[,(+|-)]**]**]

A graph position, e.g. 42,10,+ or 302,0,-.

-G, --graph-pos-file=FILE

Same as in -g, --graph-pos, but for all graph positions in FILE.

-p, --path-pos=[path_name][,offset[,(+|-)]]**

A path position, e.g. chr8,1337,+ or chrZ,3929,-.

-F, --path-pos-file=FILE

A FILE with one path position per line.

-b, --bed-input=FILE

A BED file of ranges in paths in the graph to lift into the target graph -v, --give-graph-pos emit graph positions.

-E, --gff-input=FILE

A GFF/GTF file with annotation of ranges in paths in the graph to lift into the target (sub)graph emitting graph identifiers with annotation. The output is a CSV reading for the visualization within Bandage. The first column is the node identifier, the second column the annotation. If several annotations exist for the same node, they are combined via ';'.

-v, --give-graph-pos

Emit graph positions (node, offset, strand) rather than path positions.

-I, --all-immediate

Emit all positions immediately at the given graph/path position.

-d, --search-radius=DISTANCE

Limit coordinate conversion breadth-first search up to DISTANCE bp from each given position (default: 10000).

-w, --jaccard-context=N

Maximum walking distance in nucleotides for one orientation when finding the best target (reference) range for each query path (default: 10000). Note: If we walked 9999 base pairs and w, --jaccard-context is 10000, we will also include the next node, even if we overflow the actual limit.

Threading

-t, --threads=N

Number of threads to use for parallel operations.

Processing Information

-P, --progress

Print information about the operations and the progress to stderr.

Program Information

-h, --help

Print a help message for odgi position.