A class template to hold the values of a specific Variant's format field for all samples. More...

#include <individual_field.h>

Public Member Functions
	IndividualField ()
	default constructor of an empty IndividualField More...

	IndividualField (const std::shared_ptr< bcf1_t > &body, bcf_fmt_t *format_ptr)
	creates a new format field object pointing to the shared byte array inside the Variant object More...

	IndividualField (const IndividualField &other)=delete
	copying of the IndividualField object is not allowed. Use move constructor instead. More...

	IndividualField (IndividualField &&other)=default
	safely moves the data from one IndividualField to a new one without making any copies More...

IndividualField &	operator= (const IndividualField &other)=delete
	copying of the IndividualField object is not allowed. Use move constructor instead. More...

IndividualField &	operator= (IndividualField &&other)=default
	safely moves the data from one IndividualField to the other without making any copies More...

bool	operator== (const IndividualField &other) const
	compares two IndividualField objects in the following order: memory address, size and values. More...

bool	operator!= (const IndividualField &other) const
	compares two IndividualField objects in the following order: memory address, size and values. More...

TYPE	operator[] (const uint32_t sample) const
	random access to the value of a given sample for reading or writing More...

IndividualFieldIterator< TYPE >	begin () const
	an iterator to the beginning of the object More...

IndividualFieldIterator< TYPE >	end () const
	an iterator to the end of the object More...

uint32_t	size () const
	the number of values in this IndividualField More...

uint32_t	n_samples () const
	just an alias to size() to simplify interfaces More...

uint32_t	empty () const
	checks if the object is empty. More...

uint32_t	missing () const
	checks if the object is empty. More...

TYPE	front () const
	convenience function to access the first element More...

TYPE	back () const
	convenience function to access the last element More...

Detailed Description

template<class TYPE>
class gamgee::IndividualField< TYPE >

A class template to hold the values of a specific Variant's format field for all samples.

The role of this class is to perform the pointer manipulations behind the scenes that permit the user to navigate the values of a field without making any copies and benefiting from data locality (all the data is stored contiguously in memory).

For example, the genotype quality field (GQ) will hold one uint8_t value for each sample. The PL field will hold at least three values per sample. The IndividualField will hold all these values per sample in a random access (and random access iterator compatible) way. The IndividualField can be used in any algorithm of the stl that requires random access iterators.

A typical use of the IndividualField can be exemplified by the genotype quality accessor in Variant:

const auto gquals = variant_record.integer_individual_field("GQ");

for_each(gquals.begin(), gquals.end(), [](const auto q) { cout << q[0] << endl; });

IndividualField objects can also be used in for loops like so:

for (const auto q : variant_record.integer_individual_field("GQ"))

cout << q[0] << endl;

For a field with multiple values, you can also iterate on the resulting IndividualFieldValue like so:

const auto pls = variant_record.integer_individual_field("PL");
for(const auto& pl : pls) {
  for (const auto x : pl) {
    cout << x << endl;  // here x will be hom_ref, het, homvar in each iteration
  }
}

While the IndividualField objects are not really intended to be created by the user, they are the returned by many accessors in the Variant API like the integer_individual_field("GQ") example above. Utilizing them correctly can really simplify your work by leveraging the power of the STL functions.

Note: all methods are inlined on purpose because they are so simple

Template Parameters

TYPE	the type desired for the given tag. For example for GQ's typically you would request an int32.

Constructor & Destructor Documentation

template<class TYPE>

gamgee::IndividualField< TYPE >::IndividualField ( )

inline

default constructor of an empty IndividualField

Warning: since private members are immutable, creating an empty IndividualField like this means that it will stay empty forever (desired immutability effect)

Note: empty format fields are created when the field requested is missing in the Variant recordfor some reason the = default doesn't work here. Need to check why (probably related to the template).

template<class TYPE>

gamgee::IndividualField< TYPE >::IndividualField	(	const std::shared_ptr< bcf1_t > &	body,
		bcf_fmt_t *	format_ptr
	)

inlineexplicit

creates a new format field object pointing to the shared byte array inside the Variant object

Parameters

body	the full Variant object where all the values of the field are stored (shared ownership)
format_ptr	a structure with a pointer to the location in the raw byte array (m_body->indiv) where the format field starts and information about the values (size, type, number,...)

Note: this implementation doesn't make any copies, simply manages the access to the raw byte array in Variant giving iterator interfaces to the users

template<class TYPE>

gamgee::IndividualField< TYPE >::IndividualField ( const IndividualField< TYPE > & other )

delete

copying of the IndividualField object is not allowed. Use move constructor instead.

template<class TYPE>

gamgee::IndividualField< TYPE >::IndividualField ( IndividualField< TYPE > && other )

default

safely moves the data from one IndividualField to a new one without making any copies

Parameters

other another IndividualField object

Member Function Documentation

template<class TYPE>

TYPE gamgee::IndividualField< TYPE >::back ( ) const

inline

convenience function to access the last element

template<class TYPE>

IndividualFieldIterator<TYPE> gamgee::IndividualField< TYPE >::begin ( ) const

inline

an iterator to the beginning of the object

template<class TYPE>

uint32_t gamgee::IndividualField< TYPE >::empty ( ) const

inline

checks if the object is empty.

Note: empty objects are returned when the requested field is missing

template<class TYPE>

IndividualFieldIterator<TYPE> gamgee::IndividualField< TYPE >::end ( ) const

inline

an iterator to the end of the object

template<class TYPE>

TYPE gamgee::IndividualField< TYPE >::front ( ) const

inline

convenience function to access the first element

template<class TYPE>

uint32_t gamgee::IndividualField< TYPE >::missing ( ) const

inline

checks if the object is empty.

Note: empty objects are returned when the requested field is missing

template<class TYPE>

uint32_t gamgee::IndividualField< TYPE >::n_samples ( ) const

inline

just an alias to size() to simplify interfaces

template<class TYPE>

bool gamgee::IndividualField< TYPE >::operator!= ( const IndividualField< TYPE > & other ) const

inline

compares two IndividualField objects in the following order: memory address, size and values.

Parameters

other something to compare to

Returns: true if the objects are not the same (memory address-wise), or contain different number of values, or the values are not exactly the same. Value comparison is dictated by TYPE's operator== implementation

template<class TYPE>

IndividualField& gamgee::IndividualField< TYPE >::operator= ( const IndividualField< TYPE > & other )

delete

copying of the IndividualField object is not allowed. Use move constructor instead.

template<class TYPE>

IndividualField& gamgee::IndividualField< TYPE >::operator= ( IndividualField< TYPE > && other )

default

safely moves the data from one IndividualField to the other without making any copies

Parameters

other another IndividualField object

template<class TYPE>

bool gamgee::IndividualField< TYPE >::operator== ( const IndividualField< TYPE > & other ) const

inline

compares two IndividualField objects in the following order: memory address, size and values.

Parameters

other something to compare to

Returns: true if the objects are the same (memory address-wise), or contain exactly the same values. Value comparison is dictated by TYPE's operator== implementation

template<class TYPE>

TYPE gamgee::IndividualField< TYPE >::operator[] ( const uint32_t sample ) const

inline

random access to the value of a given sample for reading or writing

Parameters

sample must be between 0 and the number of samples for this record

Note: implementation guarantees this operation to be O(1)

Exceptions

std::out_of_range if sample is out of range or entire field is missing and trying to access invalid memory

Returns: the value if it is a basic type (e.g. GQ, GL), or a specific object if it is a complex type (e.g. PL, AD,...)

template<class TYPE>

uint32_t gamgee::IndividualField< TYPE >::size ( ) const

inline

the number of values in this IndividualField

Note: this will always be the number of samples in the Variant record, which you can obtain once from it and not repeatedly for every IndividualField)

The documentation for this class was generated from the following file:

gamgee/variant/individual_field.h

Public Member Functions

Detailed Description

template<class TYPE> class gamgee::IndividualField< TYPE >

Constructor & Destructor Documentation

Member Function Documentation

template<class TYPE>
class gamgee::IndividualField< TYPE >