vg
tools for working with variation graphs
Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Protected Types | Protected Member Functions | Static Protected Member Functions | List of all members
vg::algorithms::GFAParser Class Referenceabstract

#include <gfa_to_handle.hpp>

Inheritance diagram for vg::algorithms::GFAParser:
vg::algorithms::GFATextParser vg::algorithms::GFAzParser

Public Types

using cursor_t = string::const_iterator
 
using chars_t = pair< cursor_t, cursor_t >
 
using tag_list_t = vector< string >
 
using visit_iteratee_t = function< bool(int64_t rank, nid_t node_id, bool is_reverse)>
 
using visit_source_t = function< void(const visit_iteratee_t &)>
 

Public Member Functions

GFAIDMapInfo & id_map ()
 
const GFAIDMapInfo & id_map () const
 
virtual void parse (istream &in)=0
 
virtual void parse (const string &filename)
 
virtual ~GFAParser ()=default
 

Static Public Member Functions

static string extract (const chars_t &range)
 
static size_t length (const chars_t &range)
 
static bool empty (const chars_t &range)
 
static chars_t as_chars (const string &value)
 

Public Attributes

vector< std::function< void(const tag_list_t &tags)> > header_listeners
 These listeners are called for the header line(s), if any. More...
 
vector< std::function< void(nid_t id, const chars_t &sequence, const tag_list_t &tags)> > node_listeners
 
vector< std::function< void(nid_t from, bool from_is_reverse, nid_t to, bool to_is_reverse, const chars_t &overlap, const tag_list_t &tags)> > edge_listeners
 
vector< std::function< void(const string &name, const visit_source_t &visits, const tag_list_t &tags)> > path_listeners
 
vector< std::function< void(const string &sample_name, int64_t haplotype, const string &contig_name, const pair< int64_t, int64_t > &subrange, const visit_source_t &visits, const tag_list_t &tags)> > walk_listeners
 
vector< std::function< void(nid_t id, int64_t offset, size_t length, const string &path_name, int64_t path_rank)> > rgfa_listeners
 
unique_ptr< GFAIDMapInfo > internal_id_map
 
GFAIDMapInfo * external_id_map = nullptr
 
int64_t max_rgfa_rank = -1
 
bool stop_on_duplicate_paths = false
 

Protected Types

using text_visit_iteratee_t = function< bool(int64_t rank, const chars_t &node_name, bool is_reverse)>
 Callback shape for receiving path/walk visits internally. More...
 
using text_visit_source_t = function< void(const text_visit_iteratee_t &)>
 Callback shape for being a producer of path/walk visits. More...
 

Protected Member Functions

text_visit_iteratee_t wrap (const visit_iteratee_t &iteratee) const
 
visit_source_t wrap (const text_visit_source_t &source) const
 

Static Protected Member Functions

static tag_list_t parse_tags (const chars_t &tag_range)
 
static tuple< tag_list_t > parse_h (const string &h_line)
 
static tuple< string, chars_t, tag_list_t > parse_s (const string &s_line)
 
static tuple< string, bool, string, bool, chars_t, tag_list_t > parse_l (const string &l_line)
 
static tuple< string, chars_t, chars_t, tag_list_t > parse_p (const string &p_line)
 
static tuple< string, size_t, string, pair< int64_t, int64_t >, chars_t, tag_list_t > parse_w (const string &p_line)
 
static void scan_p_visits (const chars_t &visit_range, function< bool(int64_t rank, const chars_t &node_name, bool is_reverse)> visit_step)
 
static void scan_w_visits (const chars_t &visit_range, function< bool(int64_t rank, const chars_t &node_name, bool is_reverse)> visit_step)
 
static void scan_visits (const chars_t &visit_range, char line_type, function< bool(int64_t rank, const chars_t &node_name, bool is_reverse)> visit_step)
 
static bool decode_rgfa_tags (const tag_list_t &tags, string *out_name=nullptr, int64_t *out_offset=nullptr, int64_t *out_rank=nullptr)
 
static nid_t assign_new_sequence_id (const string &str, GFAIDMapInfo &id_map_info)
 
static nid_t find_existing_sequence_id (std::string_view str, const GFAIDMapInfo &id_map_info)
 

Detailed Description

Lower-level tools for parsing GFA elements.

Parsing functions return the fields as strings, and don't support overlaps. Optional tags get read as strings into vectors.

Allows you to register "listeners" for different kinds of GFA file items, by adding functions to the various *_listeners vectors. Listeners deal with nodes as having numeric IDs. These listeners can raise GFAFormatError or its subclasses if they do not like what the GFA is saying. Some types of GFAFormatError can be caught internally and processing of the file will continue with the next line, but not with the next listener for that line, so the user is responsible for worrying about what happens if some but not all listeners for something end up getting called because one failed.

Because this contains state (the node ID map), an instance can only parse one file before needing to be discarded.

TODO: Allow resetting the node ID map.

Member Typedef Documentation

◆ chars_t

using vg::algorithms::GFAParser::chars_t = pair<cursor_t, cursor_t>

◆ cursor_t

using vg::algorithms::GFAParser::cursor_t = string::const_iterator

◆ tag_list_t

using vg::algorithms::GFAParser::tag_list_t = vector<string>

Type for a collection of GFA tags. This could become a range or list of ranges if we wanted to copy less.

◆ text_visit_iteratee_t

using vg::algorithms::GFAParser::text_visit_iteratee_t = function<bool(int64_t rank, const chars_t& node_name, bool is_reverse)>
protected

Callback shape for receiving path/walk visits internally.

◆ text_visit_source_t

using vg::algorithms::GFAParser::text_visit_source_t = function<void(const text_visit_iteratee_t&)>
protected

Callback shape for being a producer of path/walk visits.

◆ visit_iteratee_t

using vg::algorithms::GFAParser::visit_iteratee_t = function<bool(int64_t rank, nid_t node_id, bool is_reverse)>

Callback shape for receiving path/walk visits in a listener.

◆ visit_source_t

using vg::algorithms::GFAParser::visit_source_t = function<void(const visit_iteratee_t&)>

Callback shape for being a producer of path/walk visits.

One of these will be provided to a path/walk listener. Because those listeners only happen after the involved nodes have been handled, this only needs to handle the case where all the nodes have numerical IDs assigned.

Constructor & Destructor Documentation

◆ ~GFAParser()

virtual vg::algorithms::GFAParser::~GFAParser ( )
virtualdefault

Member Function Documentation

◆ as_chars()

static chars_t vg::algorithms::GFAParser::as_chars ( const string &  value)
inlinestatic

Turn a string reference into a chars_t. The string must outlive the returned chars_t.

◆ assign_new_sequence_id()

nid_t vg::algorithms::GFAParser::assign_new_sequence_id ( const string &  str,
GFAIDMapInfo &  id_map_info 
)
staticprotected

Parse a GFA name into a numeric id.

If all ids are numeric, they will be converted directly with stol.

If all ids are non-numeric, they will get incrementing ids beginning with 1, in order they are visited.

If they are a mix of numeric and non-numeric, the numberic ones will be converted with stol until the first non-numeric one is found, then it will revert to using max-id.

Since non-numeric ids are dependent on the order the nodes are scanned, there is the unfortunate side effect that they will be different sepending on whether the GFA is processed in lexicographic order or file order.

If the string ID has been seen before, returns 0.

◆ decode_rgfa_tags()

bool vg::algorithms::GFAParser::decode_rgfa_tags ( const tag_list_t &  tags,
string *  out_name = nullptr,
int64_t *  out_offset = nullptr,
int64_t *  out_rank = nullptr 
)
staticprotected

Decode rGFA tags from the given list of tags from an S line. Stores rGFA parameters at the given locations if set. Returns true if a complete set of tags was found.

◆ empty()

static bool vg::algorithms::GFAParser::empty ( const chars_t &  range)
inlinestatic

◆ extract()

static string vg::algorithms::GFAParser::extract ( const chars_t &  range)
inlinestatic

◆ find_existing_sequence_id()

nid_t vg::algorithms::GFAParser::find_existing_sequence_id ( std::string_view  str,
const GFAIDMapInfo &  id_map_info 
)
staticprotected

Find the existing sequence ID for the given node name, or 0 if it has not been seen yet.

◆ id_map() [1/2]

GFAIDMapInfo & vg::algorithms::GFAParser::id_map ( )

Get the ID map we are using for parsing. To translate text node IDs to numbers, we use this.

◆ id_map() [2/2]

const GFAIDMapInfo & vg::algorithms::GFAParser::id_map ( ) const

Get a const reference to the ID map we are using for parsing. To translate text node IDs to numbers, we use this.

◆ length()

static size_t vg::algorithms::GFAParser::length ( const chars_t &  range)
inlinestatic

◆ parse() [1/2]

void vg::algorithms::GFAParser::parse ( const string &  filename)
virtual

Parse GFA from the given filename. The default implementation opens the file as a text GFA stream and calls the stream parser.

Reimplemented in vg::algorithms::GFAzParser, and vg::algorithms::GFATextParser.

◆ parse() [2/2]

virtual void vg::algorithms::GFAParser::parse ( istream &  in)
pure virtual

Parse GFA from the given stream.

Implemented in vg::algorithms::GFAzParser, and vg::algorithms::GFATextParser.

◆ parse_h()

tuple< GFAParser::tag_list_t > vg::algorithms::GFAParser::parse_h ( const string &  h_line)
staticprotected

Parse an H line to tags

◆ parse_l()

tuple< string, bool, string, bool, GFAParser::chars_t, GFAParser::tag_list_t > vg::algorithms::GFAParser::parse_l ( const string &  l_line)
staticprotected

Parse an L line to name, is_reverse, name, is_reverse, overlap, and tags

◆ parse_p()

tuple< string, GFAParser::chars_t, GFAParser::chars_t, GFAParser::tag_list_t > vg::algorithms::GFAParser::parse_p ( const string &  p_line)
staticprotected

Parse a P line into name, visits, overlaps, and tags.

◆ parse_s()

tuple< string, GFAParser::chars_t, GFAParser::tag_list_t > vg::algorithms::GFAParser::parse_s ( const string &  s_line)
staticprotected

Parse an S line to name, sequence, and tags

◆ parse_tags()

GFAParser::tag_list_t vg::algorithms::GFAParser::parse_tags ( const chars_t &  tag_range)
staticprotected

Parse tags out from a possibly empty range to a vector of tag strings.

◆ parse_w()

tuple< string, size_t, string, pair< int64_t, int64_t >, GFAParser::chars_t, GFAParser::tag_list_t > vg::algorithms::GFAParser::parse_w ( const string &  p_line)
staticprotected

Parse a W line into sample, haplotype, sequence, range (start and end), walk, and tags. If some or all of the range is missing, uses NO_SUBRANGE and NO_END_POSITION from PathMetadata. Doesn't include an end position if a start position isn't set.

◆ scan_p_visits()

void vg::algorithms::GFAParser::scan_p_visits ( const chars_t &  visit_range,
function< bool(int64_t rank, const chars_t &node_name, bool is_reverse)>  visit_step 
)
staticprotected

Scan visits extracted from a P line. Calls a callback with all the steps. visit_step takes {rank (-1 if path empty), step node name, step reversed} and returns true if it wants to keep iterating (false means stop).

◆ scan_visits()

void vg::algorithms::GFAParser::scan_visits ( const chars_t &  visit_range,
char  line_type,
function< bool(int64_t rank, const chars_t &node_name, bool is_reverse)>  visit_step 
)
staticprotected

Scan visits extracted from a P or W line, as specified in line_type. Calls a callback with all the steps. visit_step takes {rank (-1 if path empty), step node name, step reversed} and returns true if it wants to keep iterating (false means stop).

◆ scan_w_visits()

void vg::algorithms::GFAParser::scan_w_visits ( const chars_t &  visit_range,
function< bool(int64_t rank, const chars_t &node_name, bool is_reverse)>  visit_step 
)
staticprotected

Scan visits extracted from a W line. Calls a callback with all the steps. visit_step takes {rank (-1 if path empty), step node name, step reversed} and returns true if it wants to keep iterating (false means stop).

◆ wrap() [1/2]

GFAParser::visit_source_t vg::algorithms::GFAParser::wrap ( const text_visit_source_t &  source) const
protected

Convert a visit source that produces text node IDs into one that produces numerical node IDs.

All the node IDs must have already been assigned. Uses our ID map.

◆ wrap() [2/2]

GFAParser::text_visit_iteratee_t vg::algorithms::GFAParser::wrap ( const visit_iteratee_t &  iteratee) const
protected

Convert an iteratee that needs numerical node IDs into one that handles text node names.

All the node IDs must have already been assigned. Uses our ID map.

Member Data Documentation

◆ edge_listeners

vector<std::function<void(nid_t from, bool from_is_reverse, nid_t to, bool to_is_reverse, const chars_t& overlap, const tag_list_t& tags)> > vg::algorithms::GFAParser::edge_listeners

These listeners will be called with information for all edges, after the node listeners for the involved nodes. Listeners are not protected from duplicate edges.

◆ external_id_map

GFAIDMapInfo* vg::algorithms::GFAParser::external_id_map = nullptr

◆ header_listeners

vector<std::function<void(const tag_list_t& tags)> > vg::algorithms::GFAParser::header_listeners

These listeners are called for the header line(s), if any.

◆ internal_id_map

unique_ptr<GFAIDMapInfo> vg::algorithms::GFAParser::internal_id_map

By default we use this internal ID map to translate text node names to numbers.

◆ max_rgfa_rank

int64_t vg::algorithms::GFAParser::max_rgfa_rank = -1

Include paths from rGFA tags at this rank or lower. Set to -1 to ignore rGFA tags.

◆ node_listeners

vector<std::function<void(nid_t id, const chars_t& sequence, const tag_list_t& tags)> > vg::algorithms::GFAParser::node_listeners

These listeners will be called with information for all nodes. Listeners are protected from duplicate node IDs.

◆ path_listeners

vector<std::function<void(const string& name, const visit_source_t& visits, const tag_list_t& tags)> > vg::algorithms::GFAParser::path_listeners

These listeners will be called with information for all P line paths, after the listeners for all involved nodes, and for the first header if any. Listeners are not protected from duplicate path names.

◆ rgfa_listeners

vector<std::function<void(nid_t id, int64_t offset, size_t length, const string& path_name, int64_t path_rank)> > vg::algorithms::GFAParser::rgfa_listeners

These listeners will be called with each visit of an rGFA path to a node, after the node listeners for the involved node, but in an unspecified order with respect to listeners for headers. They will be called in order along each path. The listener is responsible for detecting any gaps in the offset space and producing multiple subpaths if necessary. Listeners are protected from duplicate paths with the same name and different ranks, but not from overlaps of nodes in path offset space.

◆ stop_on_duplicate_paths

bool vg::algorithms::GFAParser::stop_on_duplicate_paths = false

Set to true to treat duplicate paths as errors. Otherwise, they will be treated as warnings and the duplicated will be discarded. Some GFA files, like the first HPRC graph releases, include duplicate paths.

◆ walk_listeners

vector<std::function<void(const string& sample_name, int64_t haplotype, const string& contig_name, const pair<int64_t, int64_t>& subrange, const visit_source_t& visits, const tag_list_t& tags)> > vg::algorithms::GFAParser::walk_listeners

These listeners will be called with information for all W line paths, after the listeners for all involved nodes, and for the first header if any. Listeners are not protected from duplicate path metadata.

The documentation for this class was generated from the following files:
Generated by   doxygen 1.9.1