---
title: "Statistics and value info"
description: "TapHome script statistics and Value info: CurrentValueTime, PreviousValue, LastKnownValue, History.Values of finished periods, how many periods are kept, examples."
url: "https://taphome.com/en/docs/script/value-info/"
language: en
lastmod: 2026-10-26
generator: hugo
ai:
  topics: ["scripting-language","variables","statistics","value-info","history"]
  questions: ["How do I use a statistic of a device in a TapHome script?","How do I get the last known value of a device that is now NaN?","How long has a device value not changed?","How do I read yesterday's value of a statistic in a script?","How many finished periods does a statistic keep?","How do I add up the rainfall of the last 48 hours from a daily rain statistic?"]
---

# Statistics and value info

Statistics and Value info in TapHome scripts: the value of a statistic, the time of the last change, the previous and last known value, and the values of finished periods.

Last updated: 2026-10-26

Besides the plain value of a device, a script variable can hold a statistic of the device, or information about a value: when it last changed, its previous value and the values of finished periods. Both are picked in the device value picker of the script editor.

## Statistics

Besides the plain device values, the device value picker offers the statistics of the device (section **Statistics**): the statistics the user enabled on the device or that the device provides itself, for example the minimum, maximum, average, count or sum of a value over a period. A variable picked this way holds the value of that statistic:

- A **Current period** statistic, for example the average of the current hour, is calculated from the start of the running period — the hour, day or month — up to now.
- A **Period to now** statistic, for example the average of the last 24 hours, is calculated over a sliding window of the given length that ends now.

```taphome
# Se was picked as the 1-hour average of Temperature (current period)
IF Se > 25
    RETURN(1);
END
0;
```

Values of finished periods are not part of the statistic itself; read them from the [Value info](https://taphome.com/en/docs/script/value-info/#value-info) of the statistic.

## Value info

Input variables of the Equation, Formula and Script smart rules, of the Formula limiting condition and of notification texts can also be picked as Value info; the picker lists it as **Value info of***name of the value*, both for a plain device value and for a **Current period** statistic. Such a variable does not hold a number but information about the value:

| Property | Type | Contents |
|---|---|---|
| `Current` | `currentvalueinfo` | The current and previous value, see [Current and previous value](https://taphome.com/en/docs/script/value-info/#current-and-previous-value). Filled for a plain device value, `Null` for a statistic. |
| `History` | `historyvalues` | Values of the finished periods, see [History of a statistic](https://taphome.com/en/docs/script/value-info/#history-of-a-statistic). Filled for a statistic with history, `Null` for a plain device value. |

Value info does not contain the value itself. To work with the value and its information together, add the device value to the script twice: once as the value (for example `Se`) and once as Value info (for example `SeInfo`).

**Available** — TapHome Next 2026.1.36599+.

## Current and previous value

`Current` describes the last change of the value:

| Property | Type | Contents |
|---|---|---|
| `CurrentValueTime` | `datetime` | When the value changed to its current value. The device sending the same value again does not move it. |
| `PreviousValue` | any | The value before the last change; it can be `NaN` or `Null`. |
| `PreviousValueTime` | `datetime` | When the value changed to `PreviousValue`. |
| `LastKnownValue` | any | The most recent previous value that was neither `NaN` nor `Null`. |
| `LastKnownValueTime` | `datetime` | When the value changed to `LastKnownValue`. |

`Current` is `Null` until the value changes for the first time — check it with `ISNULL` before reading its properties.

**Example — a window open for more than 10 minutes**

```taphome
# Wi = window contact (1 = open), WiInfo = Value info of the window contact
IF ISNULL(WiInfo.Current)
    RETURN(0);
END
IF Wi = 1 AND WiInfo.Current.CurrentValueTime < DATETIMEADD(NOW(), 0, 0, 0, 0, -10)
    RETURN(1);
END
0;
```

**Example — is the value rising or falling**

```taphome
# Se = Temperature, SeInfo = Value info of Temperature
IF ISNULL(SeInfo.Current) OR ISNULL(SeInfo.Current.LastKnownValue)
    RETURN(0);
END
VAR change := Se - SeInfo.Current.LastKnownValue;
IF change > 0
    RETURN(1);
ELSEIF change < 0
    RETURN(-1);
END
0;
```

## History of a statistic

For a **Current period** statistic, `History` holds the values of the periods that already finished:

| Property | Type | Contents |
|---|---|---|
| `Values` | collection | `Values[0]` is the last finished period, `Values[1]` the period before it, and so on. A period without data is `Null`. The running period is not included — it is the value of the statistic itself. |
| `FirstPeriodStartTime` | `datetime` | Start of the period of `Values[0]`. |

How many periods are kept depends on the period of the statistic and on whether history recording is enabled for it — the history switch of the statistic on the **Statistics** page of the device:

| Period | Kept periods, history recording on | Kept periods, history recording off |
|---|---|---|
| 5 minutes | 36 (3 hours) | 3 |
| 10 minutes | 18 (3 hours) | 3 |
| 15 minutes | 12 (3 hours) | 3 |
| 1 hour | 48 (2 days) | 3 |
| 3 hours | 17 (about 2 days) | 3 |
| 1 day | 35 | 3 |
| 1 month | 25 | 3 |
| 1 year | 10 | 3 |

For any other period (1, 2, 3 and 30 minutes, 12 hours, 2 and 3 days, 1 week, 1 quarter) and for a **Period to now** statistic, `History` is `Null`. `Values` can be shorter than the number of kept periods, for example shortly after the statistic was enabled — check `LENGTH` before reading an index that may not exist.

**Example — today's consumption so far compared with the whole of yesterday**

```taphome
# En = daily sum of Energy (current period), EnInfo = Value info of the same statistic
VAR yesterday := GETAT(EnInfo.History.Values, 0);
IF ISNULL(yesterday)
    RETURN(NaN);
END
En - yesterday;
```

**Example — average daily consumption of the last 7 days**

```taphome
# EnInfo = Value info of the daily sum of Energy (current period)
AVG(COPY(EnInfo.History.Values, 0, MIN(7, LENGTH(EnInfo.History.Values))));
```

`COPY` takes the first 7 days — `MIN` covers a history shorter than 7 days, because `COPY` beyond the end of the collection is an error — and `AVG` skips the days without data. `MIN`, `MAX` and `AVG` skip `Null`, so a whole history can also be used directly:

```taphome
# SeInfo = Value info of the 1-hour maximum of Temperature (current period)
MAX(SeInfo.History.Values);
# Result: the highest temperature of the kept hours
```

**See also** — [Variables and constants](https://taphome.com/en/docs/script/variables/), [MIN, MAX and AVG](https://taphome.com/en/docs/script/mathematical-functions/#min), [COPY](https://taphome.com/en/docs/script/text-string-and-byte-array/#copy).