PbiFilter¶

#include <pbbam/PbiFilter.h>

class PacBio::BAM::PbiFilter¶

The PbiFilter class provides a mechanism for performing PBI-enabled lookups.

The PbiFilter API is designed to be flexible, both built-in and for client-side customization. Built-in 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 built-in 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 (logical-OR over all direct children) or PbiFilter::Intersection (logical-AND 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 built-in 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(const PbiFilter &other)¶

PbiFilter(PbiFilter &&other)¶

PbiFilter &operator=(const PbiFilter &other)¶

PbiFilter &operator=(PbiFilter &&other)¶

~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 object
row: record number in BAM/PBI files

Public Types

enum CompositionType¶

Values:

INTERSECT¶

UNION¶

PbiFilter¶

Previous topic

Next topic

This Page