The `PivotCalculator` class has various functions and methods that assist with calculating the value of a cell or cells in a pivot table.
R6Class object.
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.
batchInfoA summary of the batches used in evaluating the pivot table.
countTotalData()Count the number of "totals" data frames that have been added to the pivot table.
getTotalDataFrame()Retrieve a "totals" data frame that was added to the pivot table.
getCalculation()Retrieve a calculation in the pivot table.
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.
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
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
variableNameThe data frame column name the filter is associated with.
valuesThe filter values for the filter.
setFilters()Combines two `PivotFilters` objects, e.g. to intersect the filters coming from the row and column headings for a particular cell.
setFilter()Combines a `PivotFilters` object with a `PivotFilter` object.
setFilterValues()Combines a `PivotFilters` object with additional filter criteria.
PivotCalculator$setFilterValues(
filters = NULL,
variableName = NULL,
values = NULL,
action = "replace"
)filtersA `PivotFilters` object.
variableNameThe name of the variable (i.e. column) in the data frame that the criteria relates to.
valuesThe values that the specified variable will be filtered to.
actionA character value specifying how to combine the existing filters and new filter criteria. Must be one of "intersect", "replace", "union".
getFilteredDataFrame()Apply a set of filters to a data frame and return the filtered results.
getDistinctValues()Get the distinct values from a specified column in a data frame.
formatValue()Format a value using a variety of different methods.
valueThe value to format.
formatEither 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.
fmtFuncArgsIf `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.
getCombinedFilters()Get the working filters for a calculation by combining row-column filters and calculation filters.
rowColFiltersA `PivotFilters` object containing the combined filters from the row data groups and column data groups.
calcFiltersEither `PivotFilters` object or a `PivotFilterOverrides` object containing filers defined as part of the calculation.
cellA `PivotCell` object that is the cell for which the working data filters are being calculated.
getFiltersForNamedCalculation()Get the working filters for a named calculation by calling `getCombinedFilters()` as needed, depending on the calculation type.
PivotCalculator$getFiltersForNamedCalculation(
calculationName = NULL,
calculationGroupName = NULL,
rowColFilters = NULL,
cell = NULL
)calculationNameThe name of the calculation.
calculationGroupNameThe name of the calculation group.
rowColFiltersA `PivotFilters` object containing the combined filters from the row data groups and column data groups.
cellA `PivotCell` object that is the cell for which the working data filters are being calculated.
setWorkingData()Set the working data filters for a cell in the pivot table.
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.
evaluateSingleValue()Get a single value from a data frame, as part of evaluating a calculation where the calculation is of type `calc$type="value"`.
PivotCalculator$evaluateSingleValue(
dataFrame = NULL,
workingFilters = NULL,
valueName = NULL,
format = NULL,
fmtFuncArgs = NULL,
noDataValue = NULL,
noDataCaption = NULL
)dataFrameThe data frame to retrieve the value from.
workingFiltersThe relevant working data for the calculation.
valueNameThe name of the variable to retrieve from the data frame.
formatThe formatting to apply to the value. See `formatValue()` for details.
fmtFuncArgsAdditional arguments for a custom format function. See `formatValue()` for details.
noDataValueA replacement raw value to use if the value is NULL.
noDataCaptionA replacement formatted value to use if the value is NULL.
evaluateSummariseExpression()Get a summary value from a data frame, as part of evaluating a calculation where the calculation is of type `calc$type="summary"`.
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
)dataNameThe name of the data frame (as specified in `pt$addData()`) containing the data.
dataFrameThe data frame to retrieve the value from.
workingFiltersThe relevant working data for the calculation.
batchNameThe name of the batch that contains the results of the calculation (if batch evaluation is in use and possible for this cell and calculation).
calculationNameThe name of the calculation.
calculationGroupNameThe name of the calculation group.
summaryNameThe name of the summary (typically also the calculation name).
summariseExpressionThe dplyr or data.table expression to aggregate and summarise the data.
formatThe formatting to apply to the value. See `formatValue()` for details.
fmtFuncArgsAdditional arguments for a custom format function. See `formatValue()` for details.
noDataValueA replacement raw value to use if the value is NULL.
noDataCaptionA replacement formatted value to use if the value is NULL.
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"`.
PivotCalculator$evaluateCalculationExpression(
values = NULL,
calculationExpression = NULL,
format = NULL,
fmtFuncArgs = NULL,
noDataValue = NULL,
noDataCaption = NULL
)valuesThe results of other calculations, passed in the form of a list where the element names are the names of those other calculations.
calculationExpressionA character expression to be evaluated, e.g. "values$TotalIncome/values$SaleCount".
formatThe formatting to apply to the value. See `formatValue()` for details.
fmtFuncArgsAdditional arguments for a custom format function. See `formatValue()` for details.
noDataValueA replacement raw value to use if the value is NULL.
noDataCaptionA replacement formatted value to use if the value is NULL.
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"`.
PivotCalculator$evaluateCalculateFunction(
workingFilters = NULL,
calculationFunction = NULL,
calcFuncArgs = NULL,
format = NULL,
fmtFuncArgs = NULL,
baseValues = NULL,
cell = NULL
)workingFiltersThe relevant working data for the calculation.
calculationFunctionThe custom R function to invoke.
calcFuncArgsSpecifies any additional arguments (in the form of a list) that will be passed to the custom calculation function.
formatThe formatting to apply to the value. See `formatValue()` for details.
fmtFuncArgsAdditional arguments for a custom format function. See `formatValue()` for details.
baseValuesThe results of other calculations, passed in the form of a list where the element names are the names of those other calculations.
cellA `PivotCell` object representing the cell being calculated.
evaluateNamedCalculationWD()Invokes the relevant calculation function based upon the calculation type.
PivotCalculator$evaluateNamedCalculationWD(
calculationName = NULL,
calculationGroupName = NULL,
workingData = NULL,
cell = NULL
)calculationNameThe name of the calculation to execute.
calculationGroupNameThe calculation group that the calculation belongs to.
workingDataThe relevant working data for the calculation.
cellA `PivotCell` object representing the cell being calculated.
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.
evaluateNamedCalculation()Invokes the relevant calculation function based upon the calculation type.
PivotCalculator$evaluateNamedCalculation(
calculationName = NULL,
calculationGroupName = NULL,
rowColFilters = NULL
)calculationNameThe name of the calculation to execute.
calculationGroupNameThe calculation group that the calculation belongs to.
rowColFiltersThe filters arising from the row and column groups.
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.
# This class should only be created by the pivot table.
# It is not intended to be created outside of the pivot table.