API Reference

CalculateEvolutionFilter

Piwik\DataTable\Filter\

CalculateEvolutionFilter

A DataTable filter that calculates the evolution of a metric and adds it to each row as a percentage.

This filter cannot be used as an argument to DataTable::filter() since it requires corresponding data from another DataTable. Instead, you must manually perform a binary filter (see the MultiSites API for an example).

The evolution metric is calculated as:

((currentValue - pastValue) / pastValue) * 100

Methods

The class defines the following methods:

__construct()

Constructor.

Signature

  • It accepts the following parameter(s):

    • $table (DataTable) —

    • $pastDataTable (DataTable) — The DataTable containing data for the period in the past.

    • $columnToAdd (string) — The column to add evolution data to, eg, 'visits_evolution'.
    • $columnToRead (string) — The column to use to calculate evolution data, eg, 'nb_visits'.
    • $quotientPrecision (int) — The precision to use when rounding the quotient.

filter()

See ColumnCallbackAddColumnQuotient.

Signature

  • It accepts the following parameter(s):

  • It does not return anything or a mixed result.

enableRecursive()

Enables/Disables recursive filtering. Whether this property is actually used is up to the derived BaseFilter class.

Signature

  • It accepts the following parameter(s):

    • $enable (bool) —

  • It does not return anything or a mixed result.

filterSubTable()

Filters a row's subtable, if one exists and is loaded in memory.

Signature

  • It accepts the following parameter(s):
    • $row (Row) — The row whose subtable should be filter.
  • It does not return anything or a mixed result.

calculate()

Calculates the evolution percentage for two arbitrary values.

Signature

  • It accepts the following parameter(s):

    • $currentValue (float|int) — The current metric value.
    • $pastValue (float|int) — The value of the metric in the past. We measure the % change from this value to $currentValue.
    • $quotientPrecision (float|int) — The quotient precision to round to.
    • $appendPercentSign (bool) — Whether to append a '%' sign to the end of the number or not.
    • $prependPlusSignWhenPositive (bool) — Whether to prepend a '+' sign before the number if it's not negative.

  • Returns: string — The evolution percent, eg '15%'.

appendPercentSign()

Signature

  • It accepts the following parameter(s):

    • $number

  • It does not return anything or a mixed result.

prependPlusSignToNumber()

Signature

  • It accepts the following parameter(s):

    • $number

  • It does not return anything or a mixed result.