PivotCalculator: R6 class that computes the value of a cell or cells.

PivotCalculatorR Documentation

R6 class that computes the value of a cell or cells.

Description

The 'PivotCalculator' class has various functions and methods that assist with calculating the value of a cell or cells in a pivot table.

Format

R6Class object.

Details

This class contains all of the logic necessary for evaluating calculations. For batch mode calculations, it makes use of the 'PivotBatchCalculator' class to carry out the calculation batches, then retrieves the results from the relevant batch for each calculation. For sequential mode calculations, this class carries out the calculations. Where a pivot table contains some cells that can be evaluated in batch mode and some that cannot, this class contains the appropriate logic to use the relevant calculation mode in each case, preferring to use batch mode where possible, unless this has been disabled in the pivot table settings. There are many utility methods in this class that are thin wrappers around methods in other classes. This simplifies calling these other methods as well as providing a more unified way to change in the future how these common operations are performed. Custom calculation functions are passed an instance of the 'PivotCalculator' class, thereby also providing the authors of custom calculation functions an easy way for custom calculation functions to carry out common operations.

Active bindings

batchInfo

A summary of the batches used in evaluating the pivot table.

Methods

Public methods


Method new()

Create a new 'PivotCalculator' object.

Usage
PivotCalculator$new(parentPivot = NULL)
Arguments
parentPivot

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

Returns

A new 'PivotCalculator' object.


Method getDataFrame()

Retrieve a data frame that was added to the pivot table.

Usage
PivotCalculator$getDataFrame(dataName = NULL)
Arguments
dataName

The name of the data frame (as specified in 'pt$addData()') to retrieve.

Returns

The data frame with the specified name.


Method countTotalData()

Count the number of "totals" data frames that have been added to the pivot table.

Usage
PivotCalculator$countTotalData(dataName = NULL)
Arguments
dataName

The name of the data frame (as specified in 'pt$addData()') that the "totals" data frames are associated with.

Returns

The number of "totals" data frames associated with the specified name.


Method getTotalDataFrame()

Retrieve a "totals" data frame that was added to the pivot table.

Usage
PivotCalculator$getTotalDataFrame(dataName = NULL, variableNames = NULL)
Arguments
dataName

The name of the data frame (as specified in 'pt$addData()') that the "totals" data frame is associated with.

variableNames

The names of the variables that the totals are grouped by in the "totals" data frame (i.e. the dimensionality).

Returns

The "totals" data frame.


Method getCalculationGroup()

Retrieve a calculation group in the pivot table.

Usage
PivotCalculator$getCalculationGroup(calculationGroupName = NULL)
Arguments
calculationGroupName

The name of the calculation group to retrieve.

Returns

The calculation group with the specified name.


Method getCalculation()

Retrieve a calculation in the pivot table.

Usage
PivotCalculator$getCalculation(
  calculationGroupName = NULL,
  calculationName = NULL
)
Arguments
calculationGroupName

The name of the calculation group to retrieve.

calculationName

The name of the calculation to retrieve.

Returns

The calculation with the specified name in the specified group.


Method generateBatchesForCellEvaluation()

Examine the data groups and cells in a pivot table to generate the structure of the batches in preparation for evaluating the pivot table.

Usage
PivotCalculator$generateBatchesForCellEvaluation()
Returns

The batches that exist in the pivot table.


Method evaluateBatches()

Execute the batch calculations as part of evaluating the pivot table.

Usage
PivotCalculator$evaluateBatches()
Returns

The number of batches that were evaluated.


Method newFilter()

Create a new 'PivotFilter' object associated with the specified data frame column name and column values. The new filter is conceptually of the form 'variableName

Usage
PivotCalculator$newFilter(variableName = NULL, values = NULL)
Arguments
variableName

The data frame column name the filter is associated with.

values

The filter values for the filter.

Returns

The new 'PivotFilter' object.


Method newFilters()

Create a new 'PivotFilters' object associated with the specified data frame column name and column values. The new filter is conceptually of the form 'variableName

Usage
PivotCalculator$newFilters(variableName = NULL, values = NULL)
Arguments
variableName

The data frame column name the filter is associated with.

values

The filter values for the filter.

Details

A 'PivotFilters' object is a collection of 'PivotFilter' objects, therefore the return value of this method is suitable for use where other filters will subsequently be needed/applied.

Returns

The new 'PivotFilter' object.


Method setFilters()

Combines two 'PivotFilters' objects, e.g. to intersect the filters coming from the row and column headings for a particular cell.

Usage
PivotCalculator$setFilters(
  filters1 = NULL,
  filters2 = NULL,
  action = "replace"
)
Arguments
filters1

A 'PivotFilters' object.

filters2

A 'PivotFilters' object.

action

A character value specifying how to combine the two filters. Must be one of "intersect", "replace", "union".

Returns

A new 'PivotFilters' object.


Method setFilter()

Combines a 'PivotFilters' object with a 'PivotFilter' object.

Usage
PivotCalculator$setFilter(filters = NULL, filter = NULL, action = "replace")
Arguments
filters

A 'PivotFilters' object.

filter

A 'PivotFilters' object.

action

A character value specifying how to combine the two filters. Must be one of "intersect", "replace", "union".

Returns

A new 'PivotFilters' object.


Method setFilterValues()

Combines a 'PivotFilters' object with additional filter criteria.

Usage
PivotCalculator$setFilterValues(
  filters = NULL,
  variableName = NULL,
  values = NULL,
  action = "replace"
)
Arguments
filters

A 'PivotFilters' object.

variableName

The name of the variable (i.e. column) in the data frame that the criteria relates to.

values

The values that the specified variable will be filtered to.

action

A character value specifying how to combine the existing filters and new filter criteria. Must be one of "intersect", "replace", "union".

Returns

A new 'PivotFilters' object.


Method getFilteredDataFrame()

Apply a set of filters to a data frame and return the filtered results.

Usage
PivotCalculator$getFilteredDataFrame(dataFrame = NULL, filters = NULL)
Arguments
dataFrame

The data frame to filter.

filters

A 'PivotFilters' object containing the filter criteria.

dataName

The name of the data frame (as specified in 'pt$addData()') to be filtered.

Returns

A filtered data frame.


Method getDistinctValues()

Get the distinct values from a specified column in a data frame.

Usage
PivotCalculator$getDistinctValues(dataFrame = NULL, variableName = NULL)
Arguments
dataFrame

The data frame.

variableName

The name of the variable to get the distinct values for.

Returns

A vector containing the distinct values.


Method formatValue()

Format a value using a variety of different methods.

Usage
PivotCalculator$formatValue(value = NULL, format = NULL, fmtFuncArgs = NULL)
Arguments
value

The value to format.

format

Either a character format string to be used with 'sprintf()', a list of arguments to be used with 'base::format()' or a custom R function which will be invoked once per value to be formatted.

fmtFuncArgs

If 'format' is a custom R function, then 'fmtFuncArgs' specifies any additional arguments (in the form of a list) that will be passed to the custom function.

Returns

The formatted value if 'format' is specified, otherwise the 'value' converted to a character value.


Method getCombinedFilters()

Get the working filters for a calculation by combining row-column filters and calculation filters.

Usage
PivotCalculator$getCombinedFilters(
  rowColFilters = NULL,
  calcFilters = NULL,
  cell = NULL
)
Arguments
rowColFilters

A 'PivotFilters' object containing the combined filters from the row data groups and column data groups.

calcFilters

Either 'PivotFilters' object or a 'PivotFilterOverrides' object containing filers defined as part of the calculation.

cell

A 'PivotCell' object that is the cell for which the working data filters are being calculated.

Returns

A list of filters, element names: calculationFilters and workingFilters. The working filters are the row-column filters combined with the calculation filters.


Method getFiltersForNamedCalculation()

Get the working filters for a named calculation by calling 'getCombinedFilters()' as needed, depending on the calculation type.

Usage
PivotCalculator$getFiltersForNamedCalculation(
  calculationName = NULL,
  calculationGroupName = NULL,
  rowColFilters = NULL,
  cell = NULL
)
Arguments
calculationName

The name of the calculation.

calculationGroupName

The name of the calculation group.

rowColFilters

A 'PivotFilters' object containing the combined filters from the row data groups and column data groups.

cell

A 'PivotCell' object that is the cell for which the working data filters are being calculated.

Returns

A list of filters, where the element names are calculation names. Reminder: Evaluating a named calculation, if 'calc$type="calculation"', can involve computing multiple named calculations, which is why this return value is a list.


Method setWorkingData()

Set the working data filters for a cell in the pivot table.

Usage
PivotCalculator$setWorkingData(cell = NULL)
Arguments
cell

The cell to generate the working data for.

Details

The working data for a cell is a list of 'PivotFilters' objects - one per named calculation. Most cells only relate to one calculation, but calculations of type 'calc$type="calculation"' can relate to multiple calculations, hence the working data is a list where the element name is the calculation name. This method calls 'getFiltersForNamedCalculation()' internally to generate the filters for the working data.

Returns

No return value.


Method evaluateSingleValue()

Get a single value from a data frame, as part of evaluating a calculation where the calculation is of type 'calc$type="value"'.

Usage
PivotCalculator$evaluateSingleValue(
  dataFrame = NULL,
  workingFilters = NULL,
  valueName = NULL,
  format = NULL,
  fmtFuncArgs = NULL,
  noDataValue = NULL,
  noDataCaption = NULL
)
Arguments
dataFrame

The data frame to retrieve the value from.

workingFilters

The relevant working data for the calculation.

valueName

The name of the variable to retrieve from the data frame.

format

The formatting to apply to the value. See 'formatValue()' for details.

fmtFuncArgs

Additional arguments for a custom format function. See 'formatValue()' for details.

noDataValue

A replacement raw value to use if the value is NULL.

noDataCaption

A replacement formatted value to use if the value is NULL.

Returns

A list containing two elements: rawValue (typically numeric) and formattedValue (typically a character value).


Method evaluateSummariseExpression()

Get a summary value from a data frame, as part of evaluating a calculation where the calculation is of type 'calc$type="summary"'.

Usage
PivotCalculator$evaluateSummariseExpression(
  dataName = NULL,
  dataFrame = NULL,
  workingFilters = NULL,
  batchName = NULL,
  calculationName = NULL,
  calculationGroupName = NULL,
  summaryName = NULL,
  summariseExpression = NULL,
  format = NULL,
  fmtFuncArgs = NULL,
  noDataValue = NULL,
  noDataCaption = NULL
)
Arguments
dataName

The name of the data frame (as specified in 'pt$addData()') containing the data.

dataFrame

The data frame to retrieve the value from.

workingFilters

The relevant working data for the calculation.

batchName

The name of the batch that contains the results of the calculation (if batch evaluation is in use and possible for this cell and calculation).

calculationName

The name of the calculation.

calculationGroupName

The name of the calculation group.

summaryName

The name of the summary (typically also the calculation name).

summariseExpression

The dplyr or data.table expression to aggregate and summarise the data.

format

The formatting to apply to the value. See 'formatValue()' for details.

fmtFuncArgs

Additional arguments for a custom format function. See 'formatValue()' for details.

noDataValue

A replacement raw value to use if the value is NULL.

noDataCaption

A replacement formatted value to use if the value is NULL.

Details

Where batch evaluation is used, the value is retrieved from the pre-calculated batch, otherwise dplyr/data.table is used to calculate the value (i.e. reverting to sequential evaluation mode which performs calculations cell-by-cell, one cell at a time).

Returns

A list containing two elements: rawValue (typically numeric) and formattedValue (typically a character value).


Method evaluateCalculationExpression()

Evaluates an R expression in order to combine the results of other calculations, as part of evaluating a calculation where the calculation is of type 'calc$type="calculation"'.

Usage
PivotCalculator$evaluateCalculationExpression(
  values = NULL,
  calculationExpression = NULL,
  format = NULL,
  fmtFuncArgs = NULL,
  noDataValue = NULL,
  noDataCaption = NULL
)
Arguments
values

The results of other calculations, passed in the form of a list where the element names are the names of those other calculations.

calculationExpression

A character expression to be evaluated, e.g. "values$TotalIncome/values$SaleCount".

format

The formatting to apply to the value. See 'formatValue()' for details.

fmtFuncArgs

Additional arguments for a custom format function. See 'formatValue()' for details.

noDataValue

A replacement raw value to use if the value is NULL.

noDataCaption

A replacement formatted value to use if the value is NULL.

Details

A calculation, where 'calc$type="calculation"', combines the results of other calculations using a simple R expression.

Returns

A list containing two elements: rawValue (typically numeric) and formattedValue (typically a character value).


Method evaluateCalculateFunction()

Invokes a user-provided custom R function to aggregate data and perform calculations, as part of evaluating a calculation where the calculation is of type 'calc$type="function"'.

Usage
PivotCalculator$evaluateCalculateFunction(
  workingFilters = NULL,
  calculationFunction = NULL,
  calcFuncArgs = NULL,
  format = NULL,
  fmtFuncArgs = NULL,
  baseValues = NULL,
  cell = NULL
)
Arguments
workingFilters

The relevant working data for the calculation.

calculationFunction

The custom R function to invoke.

calcFuncArgs

Specifies any additional arguments (in the form of a list) that will be passed to the custom calculation function.

format

The formatting to apply to the value. See 'formatValue()' for details.

fmtFuncArgs

Additional arguments for a custom format function. See 'formatValue()' for details.

baseValues

The results of other calculations, passed in the form of a list where the element names are the names of those other calculations.

cell

A 'PivotCell' object representing the cell being calculated.

Details

A calculation, where 'calc$type="function"', invokes a user provided R function on a cell-by-cell basis.

Returns

A list containing two elements: rawValue (typically numeric) and formattedValue (typically a character value).


Method evaluateNamedCalculationWD()

Invokes the relevant calculation function based upon the calculation type.

Usage
PivotCalculator$evaluateNamedCalculationWD(
  calculationName = NULL,
  calculationGroupName = NULL,
  workingData = NULL,
  cell = NULL
)
Arguments
calculationName

The name of the calculation to execute.

calculationGroupName

The calculation group that the calculation belongs to.

workingData

The relevant working data for the calculation.

cell

A 'PivotCell' object representing the cell being calculated.

Details

This function examines the 'calc$type' property then invokes either 'evaluateSingleValue()', 'evaluateSummariseExpression()', 'evaluateCalculationExpression()' or 'evaluateCalculateFunction()'. Sometimes, more than one of the these functions is invoked, since calculation type "calculation" and "function" can/do make use of values from other calculations, which must be evaluated first.

Returns

A list containing two elements: rawValue (typically numeric) and formattedValue (typically a character value).


Method evaluateNamedCalculation()

Invokes the relevant calculation function based upon the calculation type.

Usage
PivotCalculator$evaluateNamedCalculation(
  calculationName = NULL,
  calculationGroupName = NULL,
  rowColFilters = NULL
)
Arguments
calculationName

The name of the calculation to execute.

calculationGroupName

The calculation group that the calculation belongs to.

rowColFilters

The filters arising from the row and column groups.

Details

This function is a higher-level wrapper around 'evaluateNamedCalculationWD()'. This version incorporates logic to convert the filters from the row and column data groups into the working data filters, then calls 'evaluateNamedCalculationWD()'. This version has no suffix in the name, since this is the version users are more likely to invoke, e.g. from within a custom calculation function.

Returns

A list containing two elements: rawValue (typically numeric) and formattedValue (typically a character value).


Method evaluateCell()

Evaluate calculations to compute the value of a cell in a pivot table.

Usage
PivotCalculator$evaluateCell(cell = NULL)
Arguments
cell

A 'PivotCell' object representing the cell to calculate.

Returns

A list containing two elements: rawValue (typically numeric) and formattedValue (typically a character value).


Method clone()

The objects of this class are cloneable with this method.

Usage
PivotCalculator$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

Examples

# This class should only be created by the pivot table.
# It is not intended to be created outside of the pivot table.

pivottabler documentation built on Oct. 1, 2023, 5:07 p.m.