class to build Sam objects from existing data or from scratch More...

#include <sam_builder.h>

Public Member Functions
	SamBuilder (const SamHeader &header, const bool validate_on_build=true)
	create a Sam from scratch, starting only with a header More...

	SamBuilder (const Sam &starting_read, const bool validate_on_build=true)
	create a Sam starting with an existing read and its header More...

	SamBuilder (const SamHeader &header, const Sam &starting_read, const bool validate_on_build=true)
	create a Sam starting with an existing read, and manually set the header to a custom value More...

	SamBuilder (SamBuilder &&other)=default

SamBuilder &	operator= (SamBuilder &&other)=default

	SamBuilder (const SamBuilder &other)=delete

SamBuilder &	operator= (const SamBuilder &other)=delete

	~SamBuilder ()=default

SamBuilder &	set_name (const std::string &new_name)
	set the read's QNAME to the specified value More...

SamBuilder &	set_cigar (const Cigar &new_cigar)
	set the read's cigar to the cigar of an existing read More...

SamBuilder &	set_cigar (const std::vector< CigarElement > &new_cigar)
	set the read's cigar using a vector of CigarElements More...

SamBuilder &	set_cigar (const std::initializer_list< CigarElement > new_cigar)
	set the read's cigar using an initializer_list of CigarElements More...

SamBuilder &	set_cigar (const std::string &new_cigar)
	set the read's cigar using a string representation of a cigar (eg., "3M1I3M") More...

SamBuilder &	set_bases (const ReadBases &new_bases)
	set the read's bases to the bases of an existing read More...

SamBuilder &	set_bases (const std::vector< Base > &new_bases)
	set the read's bases using a vector of Bases More...

SamBuilder &	set_bases (const std::initializer_list< Base > new_bases)
	set the read's bases using an initializer_list of Bases More...

SamBuilder &	set_bases (const std::string &new_bases)
	set the read's bases using a string of base values (eg., "ACGT") More...

SamBuilder &	set_base_quals (const BaseQuals &new_base_quals)
	set the read's base qualities to the base qualities of an existing read More...

SamBuilder &	set_base_quals (const std::vector< uint8_t > &new_base_quals)
	set the read's base qualities using a vector of quality scores More...

SamBuilder &	set_base_quals (const std::initializer_list< uint8_t > new_base_quals)
	set the read's base qualities using an initializer_list of (uint8_t) quality scores More...

SamBuilder &	set_base_quals (const std::initializer_list< int > new_base_quals)
	set the read's base qualities using an initializer_list of (int) quality scores More...

SamBuilder &	set_chromosome (const uint32_t chr)
	simple setter for the chromosome index. Index is 0-based. More...

SamBuilder &	set_alignment_start (const uint32_t start)
	simple setter for the alignment start. More...

SamBuilder &	set_mate_chromosome (const uint32_t mchr)
	simple setter for the mate's chromosome index. Index is 0-based. More...

SamBuilder &	set_mate_alignment_start (const uint32_t mstart)
	simple setter for the mate's alignment start. More...

SamBuilder &	set_paired ()

SamBuilder &	set_not_paired ()

SamBuilder &	set_unmapped ()

SamBuilder &	set_not_unmapped ()

SamBuilder &	set_mate_unmapped ()

SamBuilder &	set_not_mate_unmapped ()

SamBuilder &	set_reverse ()

SamBuilder &	set_not_reverse ()

SamBuilder &	set_mate_reverse ()

SamBuilder &	set_not_mate_reverse ()

SamBuilder &	set_first ()

SamBuilder &	set_not_first ()

SamBuilder &	set_last ()

SamBuilder &	set_not_last ()

SamBuilder &	set_secondary ()

SamBuilder &	set_not_secondary ()

SamBuilder &	set_fail ()

SamBuilder &	set_not_fail ()

SamBuilder &	set_duplicate ()

SamBuilder &	set_not_duplicate ()

SamBuilder &	set_supplementary ()

SamBuilder &	set_not_supplementary ()

Sam	build () const
	build a Sam (can be called repeatedly) More...

Sam	one_time_build ()
	build a Sam more efficiently by moving the builder's data out of it and invalidating future builds More...

Detailed Description

class to build Sam objects from existing data or from scratch

Unlike the setters in the Sam class, which only allow in-place modification of the data for efficiency reasons, SamBuilder lets you construct a read in arbitrary ways (including resizing data elements like the number of quality scores and the cigar).

To use, either start from scratch with only a header:

auto builder = SamBuilder{header};

or start with the state in an existing read:

auto builder = SamBuilder{existing_read};

Then make the desired modifications and build repeatedly.

auto read1 = builder.set_cigar("1M1I1M").set_base_quals({1,2,3}).build(); auto read2 = builder.set_name("new_name").set_chromosome(3).build();

Alternatively, you may use the one_time_build() function if you only need to ever build one read using a given builder. This is slightly more efficient than the more general-purpose repeatable build() function.

You must provide a value for all essential data fields before building if you build from scratch, unless you disable validation (not recommended).

Some methods of setting values are more efficient than others. For example, setting a cigar using a vector is much more efficient than setting it via a string:

builder.set_cigar(vector<CigarElement>{Cigar::make_cigar_element(3, CigarOperator::M)}); is faster than: builder.set_cigar("3M");

since the string must be parsed and validated.

The builder always copies the data it's given in the set_* methods, even when it belongs to another read, for safety reasons. Altering a read after passing some of its data into a builder will not affect the state of the builder.

Before building, the builder performs a validation step to ensure that the read it will create is logically consistent (eg., number of base qualities must match the number of bases). This validation step can be disabled during construction of the builder, but disabling validation is dangerous and not recommended.

Constructor & Destructor Documentation

gamgee::SamBuilder::SamBuilder	(	const SamHeader &	header,
		const bool	validate_on_build = `true`
	)

explicit

create a Sam from scratch, starting only with a header

Note: users of this constructor will need to fill in sufficient parts of the read to produce a valid read

gamgee::SamBuilder::SamBuilder	(	const Sam &	starting_read,
		const bool	validate_on_build = `true`
	)

explicit

create a Sam starting with an existing read and its header

Note: the data in the existing read is copied into the builder so that future changes to the read will not affect the builder

gamgee::SamBuilder::SamBuilder	(	const SamHeader &	header,
		const Sam &	starting_read,
		const bool	validate_on_build = `true`
	)

explicit

create a Sam starting with an existing read, and manually set the header to a custom value

Note: the data in the existing read is copied into the builder so that future changes to the read will not affect the builder

gamgee::SamBuilder::SamBuilder ( SamBuilder && other )

default

gamgee::SamBuilder::SamBuilder ( const SamBuilder & other )

delete

gamgee::SamBuilder::~SamBuilder ( )

default

Member Function Documentation

Sam gamgee::SamBuilder::build ( ) const

build a Sam (can be called repeatedly)

build a Sam record using the current state of the builder

Note: this version of build() can be called repeatedly to build multiple Sam objects with small variations

Sam gamgee::SamBuilder::one_time_build ( )

build a Sam more efficiently by moving the builder's data out of it and invalidating future builds

build a Sam record more efficiently by moving the builder's data out to the caller and invalidating the builder's state

Note: this method can be called only once, and the builder should not be used after it's called

SamBuilder& gamgee::SamBuilder::operator= ( SamBuilder && other )

default

SamBuilder& gamgee::SamBuilder::operator= ( const SamBuilder & other )

delete

SamBuilder& gamgee::SamBuilder::set_alignment_start ( const uint32_t start )

inline

simple setter for the alignment start.

Warning: You should use (1-based and inclusive) alignment but internally this is stored 0-based to simplify BAM conversion.

SamBuilder & gamgee::SamBuilder::set_base_quals ( const BaseQuals & new_base_quals )

set the read's base qualities to the base qualities of an existing read

Note: copies the existing read's base qualities

SamBuilder & gamgee::SamBuilder::set_base_quals ( const std::vector< uint8_t > & new_base_quals )

set the read's base qualities using a vector of quality scores

Note: copies the contents of the vector

SamBuilder & gamgee::SamBuilder::set_base_quals ( const std::initializer_list< uint8_t > new_base_quals )

set the read's base qualities using an initializer_list of (uint8_t) quality scores

Note: to use this version, you must explicitly specify that the type of elements in the initializer_list is uint8_t (eg., initializer_list<uint8_t>{1, 2, 3})

SamBuilder & gamgee::SamBuilder::set_base_quals ( const std::initializer_list< int > new_base_quals )

set the read's base qualities using an initializer_list of (int) quality scores

Note: this version can be used without specifying the type of the elements in the initializer_list (eg., set_base_quals({1, 2, 3})), but it is less efficient than the other versions since it must perform a range check on each score

SamBuilder & gamgee::SamBuilder::set_bases ( const ReadBases & new_bases )

set the read's bases to the bases of an existing read

Note: copies the other read's bases

SamBuilder & gamgee::SamBuilder::set_bases ( const std::vector< Base > & new_bases )

set the read's bases using a vector of Bases

Note: copies the contents of the vector

SamBuilder & gamgee::SamBuilder::set_bases ( const std::initializer_list< Base > new_bases )

set the read's bases using an initializer_list of Bases

Note: initializer_lists must be passed by value as per Stroustrup p. 497, but this is efficient as internally only pointers are copied

SamBuilder & gamgee::SamBuilder::set_bases ( const std::string & new_bases )

set the read's bases using a string of base values (eg., "ACGT")

Note: this is the least efficient way to set the bases

SamBuilder& gamgee::SamBuilder::set_chromosome ( const uint32_t chr )

inline

simple setter for the chromosome index. Index is 0-based.

SamBuilder & gamgee::SamBuilder::set_cigar ( const Cigar & new_cigar )

set the read's cigar to the cigar of an existing read

Note: performs a copy of the other read's cigar

SamBuilder & gamgee::SamBuilder::set_cigar ( const std::vector< CigarElement > & new_cigar )

set the read's cigar using a vector of CigarElements

Note: CigarElements can be created via Cigar::make_cigar_element(); copies the contents of the vector

SamBuilder & gamgee::SamBuilder::set_cigar ( const std::initializer_list< CigarElement > new_cigar )

set the read's cigar using an initializer_list of CigarElements

Note: CigarElements can be created via Cigar::make_cigar_element(); initializer_lists must be passed by value as per Stroustrup p. 497, but this is efficient as internally only pointers are copied

SamBuilder & gamgee::SamBuilder::set_cigar ( const std::string & new_cigar )

set the read's cigar using a string representation of a cigar (eg., "3M1I3M")

Note: will throw invalid_argument if there is an error parsing the string; this is the least efficient way to set a cigar

SamBuilder& gamgee::SamBuilder::set_duplicate ( )

inline

SamBuilder& gamgee::SamBuilder::set_fail ( )

inline

SamBuilder& gamgee::SamBuilder::set_first ( )

inline

SamBuilder& gamgee::SamBuilder::set_last ( )

inline

SamBuilder& gamgee::SamBuilder::set_mate_alignment_start ( const uint32_t mstart )

inline

simple setter for the mate's alignment start.

Warning: You should use (1-based and inclusive) alignment but internally this is stored 0-based to simplify BAM conversion.

SamBuilder& gamgee::SamBuilder::set_mate_chromosome ( const uint32_t mchr )

inline

simple setter for the mate's chromosome index. Index is 0-based.

SamBuilder& gamgee::SamBuilder::set_mate_reverse ( )

inline

SamBuilder& gamgee::SamBuilder::set_mate_unmapped ( )

inline

SamBuilder & gamgee::SamBuilder::set_name ( const std::string & new_name )

set the read's QNAME to the specified value

SamBuilder& gamgee::SamBuilder::set_not_duplicate ( )

inline

SamBuilder& gamgee::SamBuilder::set_not_fail ( )

inline

SamBuilder& gamgee::SamBuilder::set_not_first ( )

inline

SamBuilder& gamgee::SamBuilder::set_not_last ( )

inline

SamBuilder& gamgee::SamBuilder::set_not_mate_reverse ( )

inline

SamBuilder& gamgee::SamBuilder::set_not_mate_unmapped ( )

inline

SamBuilder& gamgee::SamBuilder::set_not_paired ( )

inline

SamBuilder& gamgee::SamBuilder::set_not_reverse ( )

inline

SamBuilder& gamgee::SamBuilder::set_not_secondary ( )

inline

SamBuilder& gamgee::SamBuilder::set_not_supplementary ( )

inline

SamBuilder& gamgee::SamBuilder::set_not_unmapped ( )

inline

SamBuilder& gamgee::SamBuilder::set_paired ( )

inline

SamBuilder& gamgee::SamBuilder::set_reverse ( )

inline

SamBuilder& gamgee::SamBuilder::set_secondary ( )

inline

SamBuilder& gamgee::SamBuilder::set_supplementary ( )

inline

SamBuilder& gamgee::SamBuilder::set_unmapped ( )

inline

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

gamgee/sam/sam_builder.h
gamgee/sam/sam_builder.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation