PbiFilter¶
#include <pbbam/PbiFilter.h>

class
PacBio::BAM::
PbiFilter
¶ The PbiFilter class provides a mechanism for performing PBIenabled lookups.
The PbiFilter API is designed to be flexible, both builtin and for clientside customization. Builtin filters are provided for common queries, and client code can define and use custom filters as well. More complex filtering rules can be constructed via composition of simpler child filters.
Filter objects used as children of PbiFilter need only provide a method that matches this signature:
bool Accepts(const PbiRawData& index, const size_t row) const;
This requirement is enforced internally, using the PbiFilterConcept to require a compatible interface without requiring inheritance. This approach allows composition of heterogeneous filter types without worrying about a class hierarchy, pointer ownership across library/client boundaries, etc.
Thus a client application can define a custom filter if the builtin filters do not quite meet requirements. This filter may then be used in further PbiFilter composition, or directly to PbiFilterQuery
struct MyCustomFilter { bool Accepts(const PbiRawData& index, const size_t row) const { // Look up data for record at the provided row. Do any calculations // necessary, then return whether that record passes your // filter criteria. return true; } }; // use in composite filters PbiFilter f; f.Add(PbiMovieNameFilter("foo")); f.Add(MyCustomFilter()); // pass directly to PbiFilterQuery PbiFilterQuery query(MyCustomFilter(), "foo.bam"); for (const BamRecord& record : query) // ... do stuff ...
As mentioned above, complex filters can be built up using multiple “child” filters. These complex filters are constructed by using either PbiFilter::Union (logicalOR over all direct children) or PbiFilter::Intersection (logicalAND over direct children).
// (f1 && f2)  f3 PbiFilter f1; PbiFilter f2; PbiFilter intersect_f1_f2 = PbiFilter::Intersection(f1, f2); PbiFilter f3; PbiFilter final = PbiFilter::Union(intersect_f1_f2, f3);
Set Operations

static PbiFilter
Intersection
(const std::vector<PbiFilter> &filters)¶ Creates a PbiFilter that acts as intersection of the input filters.
A record must satisfy all of this filter’s direct “child” filters.
Equivalent to:
PbiFilter result{ PbiFilter::INTERSECT }; result.Add(filters); return result;
 Return
 composite filter
 Parameters
filters
: vector of child filters

static PbiFilter
Intersection
(std::vector<PbiFilter> &&filters)¶ Creates a PbiFilter that acts as an intersection of the input filters.
A record must satisfy all of this filter’s direct “child” filters.
Equivalent to:
PbiFilter result{ PbiFilter::INTERSECT }; result.Add(std::move(filters)); return result;
 Return
 composite filter
 Parameters
filters
: vector of child filters

static PbiFilter
Union
(const std::vector<PbiFilter> &filters)¶ Creates a PbiFilter that acts as a union of the input filters.
A record must satisfy any of this filter’s direct “child” filters.
Equivalent to:
PbiFilter result{ PbiFilter::UNION }; result.Add(filters); return result;
 Return
 composite filter
 Parameters
filters
: vector of child filters

static PbiFilter
Union
(std::vector<PbiFilter> &&filters)¶ Creates a PbiFilter that acts as a union of the input filters.
A record must satisfy any of this filter’s direct “child” filters.
Equivalent to:
PbiFilter result{ PbiFilter::UNION }; result.Add(std::move(filters)); return result;
 Return
 composite filter
 Parameters
filters
: vector of child filters
Constructors & Related Methods

static PbiFilter
FromDataSet
(const DataSet &dataset)¶ Creates a PbiFilter from a DataSet’s described filters.
A DataSet may contain a Filters element, itself a list of Filter elements. Each Filter element will contain a Properties element, itself a list of Property elements.
The Filters hierarchy looks like this (in its XML output):
<Filters> <Filter> <Properties> <Property /> # A <Property /> # B </Properties> </Filter> <Filter> <Properties> <Property /> # C <Property /> # D </Properties> </Filter> </Filters>
The resulting PbiFilter represents a union over all Filter elements, with each Filter element requiring an intersection of all of its Property criteria. These Property elements are mapped to builtin PBI filter types. To use the labels in the example XML above, the filter created here is equivalent to:
(A && B)  (C && D)
If a DataSet lacks any Filters, then an empty PbiFilter will be created
 corresponding to the dataset’s entire contents.
 Return
 composite filter
 Parameters
dataset
: maybe containing filters

PbiFilter
(const CompositionType type = INTERSECT)¶ Creates an empty filter.
 Note
 An empty filter will result in all records being returned, e.g. for query iteration.
 Parameters
type
: composition type. Any additional child filters added to this composite will be treated according to this type. If INTERSECT, a record must match all child filters. If UNION, a record must match any child filter.
 template <typename T>

PbiFilter
(const T &filter)¶ Creates a composite filter (of INTERSECT type) with an initial child filter.
 Note
 T must satisfy PbiFilterConcept
 Parameters
filter
: initial child filter
 template <typename T>

PbiFilter
(T &&filter)¶ Creates a composite filter (of INTERSECT type) with an initial child filter.
 Note
 T must satisfy PbiFilterConcept
 Parameters
filter
: initial child filter

PbiFilter
(const std::vector<PbiFilter> &filters)¶ Creates a composite filter (of INTERSECT type) with a list of initial child filters.
 Parameters
filters
: initial child filters

PbiFilter
(std::vector<PbiFilter> &&filters)¶ Creates composite filter (of INTERSECT type) with a list of initial child filters.
 Parameters
filters
: initial child filters

~PbiFilter
()¶
Composition
 template <typename T>

PbiFilter &
Add
(const T &filter)¶ Adds a new child filter of type T.
 Return
 reference to this filter
 Parameters
filter
: additional child filter. Type T must satisfy PbiFilterConcept.
 template <typename T>

PbiFilter &
Add
(T &&filter)¶ Adds a new child filter of type T.
 Return
 reference to this filter
 Parameters
filter
: additional child filter. Type T must satisfy PbiFilterConcept.

PbiFilter &
Add
(const PbiFilter &filter)¶ Adds a new child filter.
 Return
 reference to this filter
 Parameters
filter
: additional child filter

PbiFilter &
Add
(PbiFilter &&filter)¶ Adds a new child filter.
 Return
 reference to this filter
 Parameters
filter
: additional child filter

PbiFilter &
Add
(const std::vector<PbiFilter> &filters)¶ Add child filters.
 Return
 reference to this filter
 Parameters
filters
: additional child filters

PbiFilter &
Add
(std::vector<PbiFilter> &&filters)¶ Add child filters.
 Return
 reference to this filter
 Parameters
filters
: additional child filters

bool
IsEmpty
() const¶  Return
 true if this filter has no child filters.
Lookup

bool
Accepts
(const BAM::PbiRawData &idx, const size_t row) const¶ Performs the PBI index lookup, combining child results a composite filter.
 Return
 true if record at
row
passes this filter criteria, including children (if any)  Parameters
idx
: PBI (raw) index objectrow
: record number in BAM/PBI files

static PbiFilter