PivotFilters {pivottabler}

R6 class that defines a set of filter conditions.

Description

The 'PivotFilters' class allows multiple filter conditions relating to different data frame columns to be combined, i.e. a 'PivotFilters' object typically contains multiple PivotFilter objects.

Format

R6Class object.

Details

As well as acting as a container for multiple filter conditions, the 'PivotFilters' class also contains logic for combining filter. The 'action' parameter in many of the methods controls how two filters are combined.
Most common cases:
(1) When working out the rowColFilters for each pivot table cell, the filters from the row and column leaf groups are combined using 'action="intersect"'.
(2) When combining the rowColFilters with calculation filters the action could be any of (in order of most typical) "intersect", "replace" or "union".
"intersect" would apply additional restrictions, e.g. see the example in the Calculations vignette that has a measure for weekend trains only.
"replace" would apply when doing things like percentage of row total calculations - again, see example in the calculations vignette
"union" is probably much less likely (hard to envisage many situations when that would be needed).
(3) In custom calculation functions, the action could be any of "intersect", "replace" or "union".
NOTE: 'pivottabler' does not allow complex conditions to be built up, such as ((A=X) or (B=Y)) and (C=2) since there is complex precedence involved and conditions like this are not typical of pivot tables. If they were really needed, a workaround would be to use a custom calculation function and include this logic in that function.
See Appendix 2 vignette for many more complex calculation details.

Active bindings

count

The number of 'PivotFilter' objects in this 'PivotFilters' object.

filters

A list of 'PivotFilter' objects in this 'PivotFilters' object.

isALL

If TRUE, this 'PivotFilters' object matches all data.

isNONE

If TRUE, this 'PivotFilters' object matches no data.

filteredVariables

The names of the variables that are filtered by this 'PivotFilters' object.

filteredValues

A list of the criteria values for each of the variables filtered by this 'PivotFilters' object, where the list element names are the variable names.

Methods

Public methods

• PivotFilters$new()

• PivotFilters$clearFilters()

• PivotFilters$keepOnlyFiltersFor()

• PivotFilters$removeFiltersFor()

• PivotFilters$getFilter()

• PivotFilters$isFilterMatch()

• PivotFilters$setFilters()

• PivotFilters$setFilter()

• PivotFilters$setFilterValues()

• PivotFilters$addFilter()

• PivotFilters$getFilteredDataFrame()

• PivotFilters$getCopy()

• PivotFilters$asList()

• PivotFilters$asJSON()

• PivotFilters$asString()

• PivotFilters$clone()

Method new()

Create a new 'PivotFilters' object, optionally adding a filter.

Usage

PivotFilters$new(
  parentPivot = NULL,
  variableName = NULL,
  type = "ALL",
  values = NULL
)

Arguments

parentPivot

The pivot table that this 'PivotFilters' instance belongs to.

variableName

The name of the column in the data frame that this filter applies to. Specify 'NULL' to skip adding a filter.

type

Must be either "ALL", "VALUES" or "NONE". "VALUES" is the most common type and means the data is filtered to a subset of values. "ALL" means there is no filtering, i.e. all values match. "NONE" means there can be no matching values/data.

values

A single data value or a vector of multiple data values that the filter will match on.

Returns

A new 'PivotFilters' object.

Method clearFilters()

Remove all filters from this 'PivotFilters' object.

Usage

PivotFilters$clearFilters()

Returns

No return value.

Method keepOnlyFiltersFor()

Remove the filters for all variables except those specified.

Usage

PivotFilters$keepOnlyFiltersFor(variableNames = NULL)

Arguments

variableNames

A character vector specifying the variable names to retain the filter criteria for. Filter criteria for all other variables will be cleared.

Returns

No return value.

Method removeFiltersFor()

Remove the filters for the specified variables.

Usage

PivotFilters$removeFiltersFor(variableNames = NULL)

Arguments

variableNames

A character vector specifying the variable names for which the filter criteria will be cleared. Filter criteria for all other variables will be retained.

Returns

No return value.

Method getFilter()

Find a filter with the specified variable name.

Usage

PivotFilters$getFilter(variableName = NULL)

Arguments

variableName

The variable name to find a filter for.

Returns

A 'PivotFilter' object that filters on the specified variable.

Method isFilterMatch()

Tests whether this 'PivotFilters' object matches specified criteria.

Usage

PivotFilters$isFilterMatch(
  matchMode = "simple",
  variableNames = NULL,
  variableValues = NULL
)

Arguments

matchMode

Either "simple" (default) or "combinations".
"simple" is used when matching only one variable-value, multiple variable-value combinations are effectively logical "OR", i.e. any one single 'PivotFilter' match means the 'PivotFilters' object is a match.
"combinations" is used when matching for combinations of variable values, multiple variable-value combinations are effectively logical "AND", i.e. there must be a matching 'PivotFilter' for every variable name / variable values criteria specified.
See the "Finding and Formatting" vignette for graphical examples.

variableNames

The variable name(s) to find a filter for. This can be a vector containing more than one variable name.

variableValues

A list specifying the variable names and values to find, e.g. 'variableValues=list("PowerType"=c("DMU", "HST"))'.

Returns

'TRUE' if this filters object matches the specified criteria, 'FALSE' otherwise.

Method setFilters()

Update the value of this 'PivotFilters' object with the filters from the specified 'PivotFilters' object, either intersecting, replacing or unioning the filter criteria.

Usage

PivotFilters$setFilters(filters = NULL, action = "replace")

Arguments

filters

A 'PivotFilters' object.

action

Specifies how the criteria defined in 'filters' should be combined with the existing filter criteria. Must be one of "intersect", "replace" or "union".

Returns

No return value.

Method setFilter()

Update the value of this 'PivotFilters' object with the filters from the specified 'PivotFilter' object, either intersecting, replacing or unioning the filter criteria.

Usage

PivotFilters$setFilter(filter = NULL, action = "replace")

Arguments

filter

A 'PivotFilter' object.

action

Specifies how the criteria defined in 'filter' should be combined with the existing filter criteria. Must be one of "intersect", "replace" or "union".

Returns

No return value.

Method setFilterValues()

Update the value of this 'PivotFilters' object with additional filter criteria, either intersecting, replacing or unioning the filter criteria.

Usage

PivotFilters$setFilterValues(
  variableName = NULL,
  type = "ALL",
  values = NULL,
  action = "replace"
)

Arguments

variableName

The name of the column in the data frame that this criteria applies to.

type

Must be either "ALL", "VALUES" or "NONE".

values

A single data value or a vector of multiple data values that comprise the additional filter criteria.

action

Specifies how the criteria defined in 'filter' should be combined with the existing filter criteria. Must be one of "intersect", "replace" or "union".

Returns

No return value.

Method addFilter()

Add a new 'PivotFilter' object to the filter list in this 'PivotFilters' object.

Usage

PivotFilters$addFilter(filter = NULL)

Arguments

filter

A 'PivotFilter' object.

Returns

No return value.

Method getFilteredDataFrame()

Filters the specified data frame using the filters defined in this 'PivotFilters' object and returns the results as another data frame.

Usage

PivotFilters$getFilteredDataFrame(dataFrame = NULL)

Arguments

dataFrame

A data frame to filter.

Returns

A data frame filtered according to the criteria in this 'PivotFilters' object.

Method getCopy()

Create a copy of this 'PivotFilters' object.

Usage

PivotFilters$getCopy()

Returns

A copy of this 'PivotFilters' object.

Method asList()

Return the contents of this object as a list for debugging.

Usage

PivotFilters$asList()

Returns

A list of various object properties.

Method asJSON()

Return the contents of this object as JSON for debugging.

Usage

PivotFilters$asJSON()

Returns

A JSON representation of various object properties.

Method asString()

Return a representation of this object as a character value.

Usage

PivotFilters$asString(includeVariableName = TRUE, seperator = ", ")

Arguments

includeVariableName

'TRUE' (default) to include the variable name in the string.

seperator

A character value used when concatenating multiple filters.

Returns

A character summary of various object properties.

Method clone()

The objects of this class are cloneable with this method.

Usage

PivotFilters$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

pt <- PivotTable$new()
# ...
# PivotFilters constructor allows a filter to be defined
filters <- PivotFilters$new(pt, variableName="Year", values=2017)
# Create a new filter
filter <- PivotFilter$new(pt, variableName="Country", values="England")
# Combine the filters
filters$setFilter(filter)
# filters now contains criteria for both Year and Country
# Now add another filter, this time via an alternative method
filters$setFilterValues(variableName="Product", values="Cadbury Dairy Milk
Chocolate 100g")
# filters now contains criteria for Year, Country and Product