In this page are presented some useful example about how manage histories with axon functions

1 Summary
2 Examples/Exercises
3 His Computed: Generate Fake histories
- 3.1 His Imported: Write\Read his to\from csv file
- 3.2 His Collected
  - 3.2.1 Sampled
  - 3.2.2 Change Of Value
  - 3.2.3 Consumption
    - 3.2.3.1 Tags usually required
    - 3.2.3.2 Tags usually required
    - 3.2.3.3 Tags usually required
  - 3.2.4 Read Raw his data in span:date..date
  - 3.2.5 Read Raw his data in span:dateTime..dateTime
  - 3.2.6 Read his data in span:dateTime..dateTime with rollup
  - 3.2.7 Read his data in span:date..date with rollup and interpolate
4 lib:his Functions

Summary

There are different ways to handle histories in FIN:

His Computed: used to indicate that histories are generate with function;
His Imported: used to indicate that histories have been imported, usually from a csv file;
His Collected: used to indicate that histories are collect from curVal;
His Synchronized: used to populate histories from the device that the point originated from. (Example TODO)

There are three differents hisMode:

“sampled” (default)
“cov”
“consumption“

Point Type (examples)	hisMode	kind	hisTotalized	rollup fold (usually)

Point Type (examples)	hisMode	kind	hisTotalized	rollup fold (usually)
power or temp or …	“sampled”	“Number”		max, min, avg	`read({{filterExpr}}).hisRead({{dates}}, opts: {-limit}).hisRollup({{fold}}, {{interval}}).hisInterpolate.hisClip`
setpoint or …	“cov”	“Number”		max, min, avg	`read({{filterExpr}}).hisRead({{dates}}, opts: {-limit}).hisRollup({{fold}}, {{interval}}).hisInterpolate`
run or …	“cov”	“Bool”			`read({{filterExpr}}).hisRead({{dates}}, opts: {-limit}).hisRollupAuto`
energy or …	“consumption”	“Number”	M	sum, avg, min, max	`read({{filterExpr}}).hisRead({{dates}}, opts: {-limit}).hisRollup({{fold}}, {{interval}}).hisInterpolate`

Examples/Exercises

In the examples below, there are some examples about how configure and use the different history types.

It’s suggested to follow each chapter with the suggested order, since some concepts/results are reused from previous chapters.

His Computed: Generate Fake histories

Create the function you want to use to create your fake histories: Computed Histories
Examples (you can upload them using folio update of trio files):

hisMode:“sampled”

name:powerHisFunc
func
demoData
hisFuncReady
doc: 
  Generate fake energy histories each day at fixed hours inside 
  the dates span
  It's appliable to a point with kind==\"Number\" and unit:\"kW\"
  
  NOTE: THIS IS JUST AN EXAMPLE. J2 DOESN T ENSURE THAT THIS 
  FUNC IT'S USABLE IN A REAL ENVIRONMENT
src:
  (rec, dates, opts, yield) => do
    tz: rec->tz
    eachDay(dates) day => do
      (0..23).each hour => do
        ts:dateTime(day, time(hour.as(1h),0,0), tz)
        val:random(0..10).as(1kW)
        echo("ts:"+ts+" | val:"+val)
        //TryCatch handles the time change usually takes place in March
        try yield(ts, val) catch echo("SKIPPED!! --> ts:"+ts+" | val:"+val)
      end
    end
  end

hisMode:“cov”

name:occupancyHisFunc
func
demoData
hisFuncReady
doc: 
  Generate a fake occupancy history (true or false) each day at 
  fixed hours inside the dates span.
  It's appliable to a point with kind==\"Bool\" 
  
  NOTE: THIS IS JUST AN EXAMPLE. J2 DOESN T ENSURE THAT THIS 
  FUNC IT'S USABLE IN A REAL ENVIRONMENT
src:
  (rec, dates, opts, yield) => do
    tz: rec->tz
    eachDay(dates) day => do
      yield(dateTime(day, 8:00, tz), true)
      yield(dateTime(day, 22:00, tz), false)
    end
  end
name:setpointHisFunc
func
demoData
hisFuncReady
doc: 
  Generate fake setpoint histories each day at fixed hours inside 
  the dates span
  It's appliable to a point with kind=="Number" and unit:"°C"
  
  NOTE: THIS IS JUST AN EXAMPLE. J2 DOESN'T ENSURE THAT THIS 
  FUNC IT'S USABLE IN A REAL ENVIRONMENT
src:
  (rec, dates, opts, yield) => do
    tz: rec->tz
    eachDay(dates) day => do
      yield(dateTime(day, 8:00, tz), 20°C)
      yield(dateTime(day, 22:00, tz), 16°C)
    end
  end

hisMode:“consumption”

name:energyHisFunc
func
demoData
hisFuncReady
doc: 
  Generate fake energy histories each day at fixed hours inside 
  the dates span
  It's appliable to a point with kind==\"Number\" and unit:\"kWh\"
  
  NOTE: THIS IS JUST AN EXAMPLE. J2 DOESN'T ENSURE THAT THIS 
  FUNC IT'S USABLE IN A REAL ENVIRONMENT
src:
  (rec, dates, opts, yield) => do
    tz: rec->tz
    val: 0kWh
    offset:() => random(0..10).as(1kWh)
    eachDay(dates) day => do
      (0..23).each hour => do
        ts:dateTime(day, time(hour.as(1h),0,0), tz)
        echo("ts:"+ts+" | val:"+val)
        //TryCatch handles the time change usually takes place in March
        try yield(ts, val) catch echo("SKIPPED!! --> ts:"+ts+" | val:"+val)
        val = val + offset()
      end
    end
  end

Create 4 points:
- {navName:"Computed Power", kind=="Number", /* hisMode:“sampled” not required since it's the default */, ... }
- {navName:"Computed Occupancy", kind=="Bool", hisMode:"cov", ... }
- {navName:"Computed Setpoint", kind=="Number", hisMode:"cov", ... }
- {navName:"Computed Energy", kind=="Number", hisMode:"consumption", hisTotalized, ... }

“unit” tag is not required since the history is created by hisFunc. Anyway, it should be better to add the proper one to the points.

For each point enabled history and set to hisType:"computed" Point Property Sheet | History and
- hisFunc:"powerHisFunc"
- hisFunc:"occupancyHisFunc"
- hisFunc:"setpointHisFunc"
- hisFunc:"energyHisFunc"

Test the results using in Folio
- read(navName=="Computed Power").hisRead(today())
- read(navName=="Computed Occupancy").hisRead(lastWeek())
- read(navName=="Computed Setpoint").hisRead(pastMonth())
- read(navName=="Computed Energy").hisRead(thisYear(), {-limit})

If a point has the hisFunc tag (i.e. it is a computed point) the function itself is completely responsible for generating the desired history output. The his read is essentially delegated to the his func.

It means that reading the histories of the Energy Point returns like the “row” his data, so an increasing value and not a “~collected” one.

His Imported: Write\Read his to\from csv file

It could be useful to write and read points to/from a csv file. Here an example of how to do it. This requires to already have configured points as indicated in Generate Fake histories chapter.

Write: You can use one of these functions (in Folio) to write your CSV file in the folder ..\{{FIN_FolderName}}\var\proj\{{projName}}\io\{{fileName.csv}}
- read(navName=="Computed Power").hisRead(thisYear(), {-limit}).addColMeta("ts", {dis:"ts"}).addColMeta("v0", {dis:"val"}).ioWriteCsv(`io/hisPower.csv`)
- read(navName=="Computed Occupancy").hisRead(thisYear(), {-limit}).addColMeta("ts", {dis:"ts"}).addColMeta("v0", {dis:"val"}).ioWriteCsv(`io/hisOccupancy.csv`)
- read(navName=="Computed Setpoint").hisRead(thisYear(), {-limit}).addColMeta("ts", {dis:"ts"}).addColMeta("v0", {dis:"val"}).ioWriteCsv(`io/hisSetpoint.csv`)
- read(navName=="Computed Energy").hisRead(thisYear(), {-limit}).addColMeta("ts", {dis:"ts"}).addColMeta("v0", {dis:"val"}).ioWriteCsv(`io/hisEnergy.csv`)

Why .addColMeta("ts", {dis:"ts"}).addColMeta("v0", {dis:"val"}) ?

These funcs are used to change the names of the columns in the target csv file.

By default ioWriteCsv set as col name the dis value of the grid column return by hisRead(..)

Example before addColMeta:

read(navName=="Computed Power").hisRead(today()).col("ts").meta("dis").dis >>> "Timestamp"
read(navName=="Computed Power").hisRead(today()).col("ts").meta("dis").dis >>> "New Site Computed Points Computed Power"

Example after addColMeta:

read(navName=="Computed Power").hisRead(today()).addColMeta("ts", {dis:"ts"}).addColMeta("v0", {dis:"val"}).col("ts").meta("dis").dis >>> "ts"
read(navName=="Computed Power").hisRead(today()).addColMeta("ts", {dis:"ts"}).addColMeta("v0", {dis:"val"}).col("ts").meta("dis").dis >>> "val"

Create 4 new points
- {navName:"From Csv Power", unit:"kW", kind=="Number", /* hisMode:“sampled” not required since it's the default */, ... }
- {navName:"From Csv Occupancy", kind=="Bool", hisMode:"cov", ... }
- {navName:"From Csv Setpoint", unit:"°C", kind=="Number", hisMode:"cov", ... }
- {navName:"From Csv Energy", unit:"kWh", kind=="Number", hisMode:"consumption", hisTotalized, ... }

For each point enable the history as

Import the following function that will be used to read csv

Read: Populate the 4 points his with
- read(navName=="Imported Power").writeHisFromCsv(`io/hisPower.csv`)
- read(navName=="Imported Occupancy").writeHisFromCsv(`io/hisOccupancy.csv`, parseBool)
- read(navName=="Imported Setpoint").writeHisFromCsv(`io/hisSetpoint.csv`)
- read(navName=="Imported Energy").writeHisFromCsv(`io/hisEnergy.csv`)
Test the results using in Folio
- read(navName=="Imported Power").hisRead(today())
- read(navName=="Imported Occupancy").hisRead(lastWeek())
- read(navName=="Imported Setpoint").hisRead(pastMonth())
- read(navName=="Imported Energy").hisRead(thisYear(), {-limit})

His Collected

Usually these kind of points are sensors that you need to historicize.

There are 3 main types of collecting data like these:

Sampled
Change Of Value [COV]
Consumption

Based on these types, a point have different tags

Sampled

Change Of Value

Consumption

Points Examples:

Temperatures
Power
Instant Flow

Points Examples:

Occupancy
Set Point
On Off

Points Examples:

Energy
Flow-Volume

Tags usually required

his
hisMode:"sampled" //Usually it’s not required since it’s the default value

Tags usually required

his
hisMode:"cov"

Tags usually required

his
hisMode:"consumption"
hisTotalized

Read Raw his data in span:date..date

Here we are reading history data with hisRead → opts:{raw}

Span: 2021-10-08

Point: Power

Notes:

Func:

read(navName=="Imported Power").hisRead(2021-10-08, {raw})

ts	val

ts	val
2021-10-07T23:00:00+02:00 Berlin	8kW
2021-10-08T00:00:00+02:00 Berlin	10kW
2021-10-08T01:00:00+02:00 Berlin	9kW
2021-10-08T02:00:00+02:00 Berlin	4kW
2021-10-08T03:00:00+02:00 Berlin	3kW
2021-10-08T04:00:00+02:00 Berlin	6kW
2021-10-08T05:00:00+02:00 Berlin	10kW
2021-10-08T06:00:00+02:00 Berlin	4kW
2021-10-08T07:00:00+02:00 Berlin	6kW
2021-10-08T08:00:00+02:00 Berlin	7kW
2021-10-08T09:00:00+02:00 Berlin	7kW
2021-10-08T10:00:00+02:00 Berlin	5kW
2021-10-08T11:00:00+02:00 Berlin	5kW
2021-10-08T12:00:00+02:00 Berlin	1kW
2021-10-08T13:00:00+02:00 Berlin	3kW
2021-10-08T14:00:00+02:00 Berlin	3kW
2021-10-08T15:00:00+02:00 Berlin	7kW
2021-10-08T16:00:00+02:00 Berlin	1kW
2021-10-08T17:00:00+02:00 Berlin	10kW
2021-10-08T18:00:00+02:00 Berlin	7kW
2021-10-08T19:00:00+02:00 Berlin	1kW
2021-10-08T20:00:00+02:00 Berlin	7kW
2021-10-08T21:00:00+02:00 Berlin	10kW
2021-10-08T22:00:00+02:00 Berlin	2kW
2021-10-08T23:00:00+02:00 Berlin	8kW
2021-10-09T00:00:00+02:00 Berlin	9kW
2021-10-09T01:00:00+02:00 Berlin	2kW

Point: Setpoint

Notes:

Func:

read(navName=="Imported Setpoint").hisRead(2021-10-08, {raw})

ts	val

ts	val
2021-10-07T22:00:00+02:00 Berlin	16°C
2021-10-08T08:00:00+02:00 Berlin	20°C
2021-10-08T22:00:00+02:00 Berlin	16°C
2021-10-09T08:00:00+02:00 Berlin	20°C
2021-10-09T22:00:00+02:00 Berlin	16°C

Point: Energy

Notes:

Func:

read(navName=="Imported Energy").hisRead(2021-10-08, {raw})

ts	val
2021-10-07T23:00:00+02:00 Berlin	33679kWh
2021-10-08T00:00:00+02:00 Berlin	33683kWh
2021-10-08T01:00:00+02:00 Berlin	33686kWh
2021-10-08T02:00:00+02:00 Berlin	33689kWh
2021-10-08T03:00:00+02:00 Berlin	33692kWh
2021-10-08T04:00:00+02:00 Berlin	33697kWh
2021-10-08T05:00:00+02:00 Berlin	33701kWh
2021-10-08T06:00:00+02:00 Berlin	33707kWh
2021-10-08T07:00:00+02:00 Berlin	33707kWh
2021-10-08T08:00:00+02:00 Berlin	33715kWh
2021-10-08T09:00:00+02:00 Berlin	33724kWh
2021-10-08T10:00:00+02:00 Berlin	33728kWh
2021-10-08T11:00:00+02:00 Berlin	33737kWh
2021-10-08T12:00:00+02:00 Berlin	33744kWh
2021-10-08T13:00:00+02:00 Berlin	33745kWh
2021-10-08T14:00:00+02:00 Berlin	33748kWh
2021-10-08T15:00:00+02:00 Berlin	33748kWh
2021-10-08T16:00:00+02:00 Berlin	33753kWh
2021-10-08T17:00:00+02:00 Berlin	33763kWh
2021-10-08T18:00:00+02:00 Berlin	33772kWh
2021-10-08T19:00:00+02:00 Berlin	33777kWh
2021-10-08T20:00:00+02:00 Berlin	33785kWh
2021-10-08T21:00:00+02:00 Berlin	33787kWh
2021-10-08T22:00:00+02:00 Berlin	33787kWh
2021-10-08T23:00:00+02:00 Berlin	33793kWh
2021-10-09T00:00:00+02:00 Berlin	33796kWh
2021-10-09T01:00:00+02:00 Berlin	33797kWh

In the hisRead documentation you can find these notes:

- if start is Date, then we use midnight of that day
- if end is Date, then we use midnight of next after

and

The result always includes the previous item immediately before the range, and immediately after the range. The leading/trailing values are often needed to interpret the first/last values of the result. If leading/trailing values are not desired, then pipe the result of this function to hisClip()

In the example above we have:

startDate:2021-10-08 → green cells
endDate:2021-10-08 → green cells
The yellow cells are the “leading/trailing” values

Read Raw his data in span:dateTime..dateTime

Here we are reading history data with hisRead → opts:{raw}

Span: dateTime(2021-10-08, time(10,0,0))..dateTime(2021-10-08, time(16,0,0)

Point: Power

Notes:

Func:

read(navName=="Imported Power").hisRead(dateTime(2021-10-08, time(10,0,0))..dateTime(2021-10-08, time(16,0,0)), {raw})

ts	val

ts	val
2021-10-08T09:00:00+02:00 Berlin	10kW
2021-10-08T10:00:00+02:00 Berlin	5kW
2021-10-08T11:00:00+02:00 Berlin	2kW
2021-10-08T12:00:00+02:00 Berlin	0kW
2021-10-08T13:00:00+02:00 Berlin	5kW
2021-10-08T14:00:00+02:00 Berlin	5kW
2021-10-08T15:00:00+02:00 Berlin	3kW
2021-10-08T16:00:00+02:00 Berlin	10kW
2021-10-08T17:00:00+02:00 Berlin	4kW

Point: Setpoint

Notes:

Func:

read(navName=="Imported Setpoint").hisRead(dateTime(2021-10-08, time(10,0,0))..dateTime(2021-10-08, time(16,0,0)), {raw})

ts	val

ts	val
2021-10-08T08:00:00+02:00 Berlin	20°C
2021-10-08T22:00:00+02:00 Berlin	16°C

Point: Energy

Notes:

Func:

read(navName=="Imported Energy").hisRead(dateTime(2021-10-08, time(10,0,0))..dateTime(2021-10-08, time(16,0,0)), {raw})

ts	val
2021-10-08T09:00:00+02:00 Berlin	33724kWh
2021-10-08T10:00:00+02:00 Berlin	33728kWh
2021-10-08T11:00:00+02:00 Berlin	33737kWh
2021-10-08T12:00:00+02:00 Berlin	33744kWh
2021-10-08T13:00:00+02:00 Berlin	33745kWh
2021-10-08T14:00:00+02:00 Berlin	33748kWh
2021-10-08T15:00:00+02:00 Berlin	33748kWh
2021-10-08T16:00:00+02:00 Berlin	33753kWh
2021-10-08T17:00:00+02:00 Berlin	33763kWh

In the example above we have:

startDate:dateTime(2021-10-08, time(10,0,0)) → green cells
endDate:dateTime(2021-10-08, time(16,0,0)) → green cells
The yellow cells are the “leading/trailing” value

Read his data in span:dateTime..dateTime with rollup

Here we are reading history data with hisRead → opts:{raw}

Span: dateTime(2021-10-08, time(10,0,0))..dateTime(2021-10-08, time(16,0,0)
.hisRollup(avg, 15min)

Point: Power

Notes: it’s the same also without {raw}

Func:

read(navName=="Imported Power").hisRead(dateTime(2021-10-08, time(10,0,0))..dateTime(2021-10-08, time(16,0,0)), {raw}).hisRollup(avg, 15min)

ts	val

ts	val
2021-10-07T00:00:00+02:00 Berlin	null
2021-10-07T00:15:00+02:00 Berlin	null
2021-10-07T00:30:00+02:00 Berlin	null
2021-10-07T00:45:00+02:00 Berlin	null
2021-10-07T01:00:00+02:00 Berlin	null
2021-10-07T01:15:00+02:00 Berlin	null
2021-10-07T01:30:00+02:00 Berlin	null
2021-10-07T01:45:00+02:00 Berlin	null
2021-10-07T02:00:00+02:00 Berlin	null
2021-10-07T02:15:00+02:00 Berlin	null
2021-10-07T02:30:00+02:00 Berlin	null
2021-10-07T02:45:00+02:00 Berlin	null
2021-10-07T03:00:00+02:00 Berlin	null
2021-10-07T03:15:00+02:00 Berlin	null
2021-10-07T03:30:00+02:00 Berlin	null
2021-10-07T03:45:00+02:00 Berlin	null
2021-10-07T04:00:00+02:00 Berlin	null
2021-10-07T04:15:00+02:00 Berlin	null
2021-10-07T04:30:00+02:00 Berlin	null
2021-10-07T04:45:00+02:00 Berlin	null
2021-10-07T05:00:00+02:00 Berlin	null
2021-10-07T05:15:00+02:00 Berlin	null
2021-10-07T05:30:00+02:00 Berlin	null
2021-10-07T05:45:00+02:00 Berlin	null
2021-10-07T06:00:00+02:00 Berlin	null
2021-10-07T06:15:00+02:00 Berlin	null
2021-10-07T06:30:00+02:00 Berlin	null
2021-10-07T06:45:00+02:00 Berlin	null
2021-10-07T07:00:00+02:00 Berlin	null
2021-10-07T07:15:00+02:00 Berlin	null
2021-10-07T07:30:00+02:00 Berlin	null
2021-10-07T07:45:00+02:00 Berlin	null
2021-10-07T08:00:00+02:00 Berlin	null
2021-10-07T08:15:00+02:00 Berlin	null
2021-10-07T08:30:00+02:00 Berlin	null
2021-10-07T08:45:00+02:00 Berlin	null
2021-10-07T09:00:00+02:00 Berlin	0kW
2021-10-07T09:15:00+02:00 Berlin	null
2021-10-07T09:30:00+02:00 Berlin	null
2021-10-07T09:45:00+02:00 Berlin	null
2021-10-07T10:00:00+02:00 Berlin	9kW
2021-10-07T10:15:00+02:00 Berlin	null
2021-10-07T10:30:00+02:00 Berlin	null
2021-10-07T10:45:00+02:00 Berlin	null
2021-10-07T11:00:00+02:00 Berlin	10kW
2021-10-07T11:15:00+02:00 Berlin	null
2021-10-07T11:30:00+02:00 Berlin	null
2021-10-07T11:45:00+02:00 Berlin	null
2021-10-07T12:00:00+02:00 Berlin	7kW
2021-10-07T12:15:00+02:00 Berlin	null
2021-10-07T12:30:00+02:00 Berlin	null
2021-10-07T12:45:00+02:00 Berlin	null
2021-10-07T13:00:00+02:00 Berlin	2kW
2021-10-07T13:15:00+02:00 Berlin	null
2021-10-07T13:30:00+02:00 Berlin	null
2021-10-07T13:45:00+02:00 Berlin	null
2021-10-07T14:00:00+02:00 Berlin	8kW
2021-10-07T14:15:00+02:00 Berlin	null
2021-10-07T14:30:00+02:00 Berlin	null
2021-10-07T14:45:00+02:00 Berlin	null
2021-10-07T15:00:00+02:00 Berlin	4kW
2021-10-07T15:15:00+02:00 Berlin	null
2021-10-07T15:30:00+02:00 Berlin	null
2021-10-07T15:45:00+02:00 Berlin	null

Point: Setpoint

Notes: it’s the same also without {raw}

Func:

read(navName=="Imported Setpoint").hisRead(dateTime(2021-10-08, time(10,0,0))..dateTime(2021-10-08, time(16,0,0)), {raw}).hisRollup(avg, 15min)

ts	val

ts	val
2021-10-08T00:00:00+02:00 Berlin	null
2021-10-08T00:15:00+02:00 Berlin	null
2021-10-08T00:30:00+02:00 Berlin	null
2021-10-08T00:45:00+02:00 Berlin	null
2021-10-08T01:00:00+02:00 Berlin	null
2021-10-08T01:15:00+02:00 Berlin	null
2021-10-08T01:30:00+02:00 Berlin	null
2021-10-08T01:45:00+02:00 Berlin	null
2021-10-08T02:00:00+02:00 Berlin	null
2021-10-08T02:15:00+02:00 Berlin	null
2021-10-08T02:30:00+02:00 Berlin	null
2021-10-08T02:45:00+02:00 Berlin	null
2021-10-08T03:00:00+02:00 Berlin	null
2021-10-08T03:15:00+02:00 Berlin	null
2021-10-08T03:30:00+02:00 Berlin	null
2021-10-08T03:45:00+02:00 Berlin	null
2021-10-08T04:00:00+02:00 Berlin	null
2021-10-08T04:15:00+02:00 Berlin	null
2021-10-08T04:30:00+02:00 Berlin	null
2021-10-08T04:45:00+02:00 Berlin	null
2021-10-08T05:00:00+02:00 Berlin	null
2021-10-08T05:15:00+02:00 Berlin	null
2021-10-08T05:30:00+02:00 Berlin	null
2021-10-08T05:45:00+02:00 Berlin	null
2021-10-08T06:00:00+02:00 Berlin	null
2021-10-08T06:15:00+02:00 Berlin	null
2021-10-08T06:30:00+02:00 Berlin	null
2021-10-08T06:45:00+02:00 Berlin	null
2021-10-08T07:00:00+02:00 Berlin	null
2021-10-08T07:15:00+02:00 Berlin	null
2021-10-08T07:30:00+02:00 Berlin	null
2021-10-08T07:45:00+02:00 Berlin	null
2021-10-08T08:00:00+02:00 Berlin	20°C
2021-10-08T08:15:00+02:00 Berlin	null
2021-10-08T08:30:00+02:00 Berlin	null
2021-10-08T08:45:00+02:00 Berlin	null
2021-10-08T09:00:00+02:00 Berlin	null
2021-10-08T09:15:00+02:00 Berlin	null
2021-10-08T09:30:00+02:00 Berlin	null
2021-10-08T09:45:00+02:00 Berlin	null
2021-10-08T10:00:00+02:00 Berlin	null
2021-10-08T10:15:00+02:00 Berlin	null
2021-10-08T10:30:00+02:00 Berlin	null
2021-10-08T10:45:00+02:00 Berlin	null
2021-10-08T11:00:00+02:00 Berlin	null
2021-10-08T11:15:00+02:00 Berlin	null
2021-10-08T11:30:00+02:00 Berlin	null
2021-10-08T11:45:00+02:00 Berlin	null
2021-10-08T12:00:00+02:00 Berlin	null
2021-10-08T12:15:00+02:00 Berlin	null
2021-10-08T12:30:00+02:00 Berlin	null
2021-10-08T12:45:00+02:00 Berlin	null
2021-10-08T13:00:00+02:00 Berlin	null
2021-10-08T13:15:00+02:00 Berlin	null
2021-10-08T13:30:00+02:00 Berlin	null
2021-10-08T13:45:00+02:00 Berlin	null
2021-10-08T14:00:00+02:00 Berlin	null
2021-10-08T14:15:00+02:00 Berlin	null
2021-10-08T14:30:00+02:00 Berlin	null
2021-10-08T14:45:00+02:00 Berlin	null
2021-10-08T15:00:00+02:00 Berlin	null
2021-10-08T15:15:00+02:00 Berlin	null
2021-10-08T15:30:00+02:00 Berlin	null
2021-10-08T15:45:00+02:00 Berlin	null

Point: Energy

Notes: it’s NOT the same also without {raw}

Func:

read(navName=="Imported Energy").hisRead(dateTime(2021-10-08, time(10,0,0))..dateTime(2021-10-08, time(16,0,0)), {raw}).hisRollup(avg, 15min)

ts	val {raw}	val {}
2021-10-08T00:00:00+02:00 Berlin	null	null
2021-10-08T00:15:00+02:00 Berlin	null	null
2021-10-08T00:30:00+02:00 Berlin	null	null
2021-10-08T00:45:00+02:00 Berlin	null	null
2021-10-08T01:00:00+02:00 Berlin	null	null
2021-10-08T01:15:00+02:00 Berlin	null	null
2021-10-08T01:30:00+02:00 Berlin	null	null
2021-10-08T01:45:00+02:00 Berlin	null	null
2021-10-08T02:00:00+02:00 Berlin	null	null
2021-10-08T02:15:00+02:00 Berlin	null	null
2021-10-08T02:30:00+02:00 Berlin	null	null
2021-10-08T02:45:00+02:00 Berlin	null	null
2021-10-08T03:00:00+02:00 Berlin	null	null
2021-10-08T03:15:00+02:00 Berlin	null	null
2021-10-08T03:30:00+02:00 Berlin	null	null
2021-10-08T03:45:00+02:00 Berlin	null	null
2021-10-08T04:00:00+02:00 Berlin	null	null
2021-10-08T04:15:00+02:00 Berlin	null	null
2021-10-08T04:30:00+02:00 Berlin	null	null
2021-10-08T04:45:00+02:00 Berlin	null	null
2021-10-08T05:00:00+02:00 Berlin	null	null
2021-10-08T05:15:00+02:00 Berlin	null	null
2021-10-08T05:30:00+02:00 Berlin	null	null
2021-10-08T05:45:00+02:00 Berlin	null	null
2021-10-08T06:00:00+02:00 Berlin	null	null
2021-10-08T06:15:00+02:00 Berlin	null	null
2021-10-08T06:30:00+02:00 Berlin	null	null
2021-10-08T06:45:00+02:00 Berlin	null	null
2021-10-08T07:00:00+02:00 Berlin	null	null
2021-10-08T07:15:00+02:00 Berlin	null	null
2021-10-08T07:30:00+02:00 Berlin	null	null
2021-10-08T07:45:00+02:00 Berlin	null	null
2021-10-08T08:00:00+02:00 Berlin	null	null
2021-10-08T08:15:00+02:00 Berlin	null	null
2021-10-08T08:30:00+02:00 Berlin	null	null
2021-10-08T08:45:00+02:00 Berlin	null	null
2021-10-08T09:00:00+02:00 Berlin	33724kWh	4kWh
2021-10-08T09:15:00+02:00 Berlin	null	null
2021-10-08T09:30:00+02:00 Berlin	null	null
2021-10-08T09:45:00+02:00 Berlin	null	null
2021-10-08T10:00:00+02:00 Berlin	33728kWh	9kWh
2021-10-08T10:15:00+02:00 Berlin	null	null
2021-10-08T10:30:00+02:00 Berlin	null	null
2021-10-08T10:45:00+02:00 Berlin	null	null
2021-10-08T11:00:00+02:00 Berlin	33737kWh	7kWh
2021-10-08T11:15:00+02:00 Berlin	null	null
2021-10-08T11:30:00+02:00 Berlin	null	null
2021-10-08T11:45:00+02:00 Berlin	null	null
2021-10-08T12:00:00+02:00 Berlin	33744kWh	1kWh
2021-10-08T12:15:00+02:00 Berlin	null	null
2021-10-08T12:30:00+02:00 Berlin	null	null
2021-10-08T12:45:00+02:00 Berlin	null	null
2021-10-08T13:00:00+02:00 Berlin	33745kWh	3kWh
2021-10-08T13:15:00+02:00 Berlin	null	null
2021-10-08T13:30:00+02:00 Berlin	null	null
2021-10-08T13:45:00+02:00 Berlin	null	null
2021-10-08T14:00:00+02:00 Berlin	33748kWh	0kWh
2021-10-08T14:15:00+02:00 Berlin	null	null
2021-10-08T14:30:00+02:00 Berlin	null	null
2021-10-08T14:45:00+02:00 Berlin	null	null
2021-10-08T15:00:00+02:00 Berlin	33748kWh	5kWh
2021-10-08T15:15:00+02:00 Berlin	null	null
2021-10-08T15:30:00+02:00 Berlin	null	null
2021-10-08T15:45:00+02:00 Berlin	null	null

Since in the hisRollup documentation is wrote:

Rollups are inclusive of start and exclusive of end times.

We don’t have anymore the yellow trailing values

But we have the azure values that are the ones added by hisRollup

Note that now we have some red values.

Read his data in span:date..date with rollup and interpolate

Usually these data are used in charts, and a “null” value is never a good value to display.

So, to fill the null values, we can use hisInterpolate

The default behavior for Bool histories is to use "cov" mode and Number histories use "linear". You can explicitly configure a numeric history as "cov" using the hisMode tag.

Point: Power

Notes: hisInterpolate assume as default (so also with otps:{raw}) as hisMode:"sampled" .

With hisMode:"sampled" the interpolation mode is linear:

this mode is used with interval sampled data to compute the approximation using a linear equation based on the previous and next values and the associated timestamps.

Func:

read(navName=="Imported Power").hisRead(2021-10-08).hisRollup(avg, 30min).hisInterpolate

ts	val {} == {raw}	val + .hisClip

ts	val {} == {raw}	val + .hisClip
2021-10-08T00:00:00+02:00 Berlin	10kW	10kW
2021-10-08T00:30:00+02:00 Berlin	9.5kW	9.5kW
2021-10-08T01:00:00+02:00 Berlin	9kW	9kW
2021-10-08T01:30:00+02:00 Berlin	6.5kW	6.5kW
2021-10-08T02:00:00+02:00 Berlin	4kW	4kW
2021-10-08T02:30:00+02:00 Berlin	3.5kW	3.5kW
2021-10-08T03:00:00+02:00 Berlin	3kW	3kW
2021-10-08T03:30:00+02:00 Berlin	4.5kW	4.5kW
2021-10-08T04:00:00+02:00 Berlin	6kW	6kW
2021-10-08T04:30:00+02:00 Berlin	8kW	8kW
2021-10-08T05:00:00+02:00 Berlin	10kW	10kW
2021-10-08T05:30:00+02:00 Berlin	7kW	7kW
2021-10-08T06:00:00+02:00 Berlin	4kW	4kW
2021-10-08T06:30:00+02:00 Berlin	5kW	5kW
2021-10-08T07:00:00+02:00 Berlin	6kW	6kW
2021-10-08T07:30:00+02:00 Berlin	6.5kW	6.5kW
2021-10-08T08:00:00+02:00 Berlin	7kW	7kW
2021-10-08T08:30:00+02:00 Berlin	7kW	7kW
2021-10-08T09:00:00+02:00 Berlin	7kW	7kW
2021-10-08T09:30:00+02:00 Berlin	6kW	6kW
2021-10-08T10:00:00+02:00 Berlin	5kW	5kW
2021-10-08T10:30:00+02:00 Berlin	5kW	5kW
2021-10-08T11:00:00+02:00 Berlin	5kW	5kW
2021-10-08T11:30:00+02:00 Berlin	3kW	3kW
2021-10-08T12:00:00+02:00 Berlin	1kW	1kW
2021-10-08T12:30:00+02:00 Berlin	2kW	2kW
2021-10-08T13:00:00+02:00 Berlin	3kW	3kW
2021-10-08T13:30:00+02:00 Berlin	3kW	3kW
2021-10-08T14:00:00+02:00 Berlin	3kW	3kW
2021-10-08T14:30:00+02:00 Berlin	5kW	5kW
2021-10-08T15:00:00+02:00 Berlin	7kW	7kW
2021-10-08T15:30:00+02:00 Berlin	4kW	4kW
2021-10-08T16:00:00+02:00 Berlin	1kW	1kW
2021-10-08T16:30:00+02:00 Berlin	5.5kW	5.5kW
2021-10-08T17:00:00+02:00 Berlin	10kW	10kW
2021-10-08T17:30:00+02:00 Berlin	8.5kW	8.5kW
2021-10-08T18:00:00+02:00 Berlin	7kW	7kW
2021-10-08T18:30:00+02:00 Berlin	4kW	4kW
2021-10-08T19:00:00+02:00 Berlin	1kW	1kW
2021-10-08T19:30:00+02:00 Berlin	4kW	4kW
2021-10-08T20:00:00+02:00 Berlin	7kW	7kW
2021-10-08T20:30:00+02:00 Berlin	8.5kW	8.5kW
2021-10-08T21:00:00+02:00 Berlin	10kW	10kW
2021-10-08T21:30:00+02:00 Berlin	6kW	6kW
2021-10-08T22:00:00+02:00 Berlin	2kW	2kW
2021-10-08T22:30:00+02:00 Berlin	5kW	5kW
2021-10-08T23:00:00+02:00 Berlin	8kW	8kW
2021-10-08T23:30:00+02:00 Berlin	null

Point: Setpoint

Notes:

hisMode:"cov" is required since Setpoint is a numeric-point
with hisMode:"cov" , hisClip doesn't change anything

With hisMode:"cov" the interpolation mode is cov:

this mode assumes the data was sampled on change-of-value. This means that interpolation always uses the previous value until the next explicit change of value.

Func:

read(navName=="Imported Setpoint").hisRead(2021-10-08).hisRollup(avg, 30min).hisInterpolate

ts	val {} == +.hisClip	val {-hisMode}
2021-10-08T00:00:00+02:00 Berlin	16°C	null
2021-10-08T00:30:00+02:00 Berlin	16°C	null
2021-10-08T01:00:00+02:00 Berlin	16°C	null
2021-10-08T01:30:00+02:00 Berlin	16°C	null
2021-10-08T02:00:00+02:00 Berlin	16°C	null
2021-10-08T02:30:00+02:00 Berlin	16°C	null
2021-10-08T03:00:00+02:00 Berlin	16°C	null
2021-10-08T03:30:00+02:00 Berlin	16°C	null
2021-10-08T04:00:00+02:00 Berlin	16°C	null
2021-10-08T04:30:00+02:00 Berlin	16°C	null
2021-10-08T05:00:00+02:00 Berlin	16°C	null
2021-10-08T05:30:00+02:00 Berlin	16°C	null
2021-10-08T06:00:00+02:00 Berlin	16°C	null
2021-10-08T06:30:00+02:00 Berlin	16°C	null
2021-10-08T07:00:00+02:00 Berlin	16°C	null
2021-10-08T07:30:00+02:00 Berlin	16°C	null
2021-10-08T08:00:00+02:00 Berlin	20°C	20°C
2021-10-08T08:30:00+02:00 Berlin	20°C	19.857142857142858°C
2021-10-08T09:00:00+02:00 Berlin	20°C	19.714285714285715°C
2021-10-08T09:30:00+02:00 Berlin	20°C	19.571428571428573°C
2021-10-08T10:00:00+02:00 Berlin	20°C	19.42857142857143°C
2021-10-08T10:30:00+02:00 Berlin	20°C	19.28571428571429°C
2021-10-08T11:00:00+02:00 Berlin	20°C	19.142857142857146°C
2021-10-08T11:30:00+02:00 Berlin	20°C	19.000000000000004°C
2021-10-08T12:00:00+02:00 Berlin	20°C	18.85714285714286°C
2021-10-08T12:30:00+02:00 Berlin	20°C	18.71428571428572°C
2021-10-08T13:00:00+02:00 Berlin	20°C	18.571428571428577°C
2021-10-08T13:30:00+02:00 Berlin	20°C	18.428571428571434°C
2021-10-08T14:00:00+02:00 Berlin	20°C	18.285714285714292°C
2021-10-08T14:30:00+02:00 Berlin	20°C	18.14285714285715°C
2021-10-08T15:00:00+02:00 Berlin	20°C	18.000000000000007°C
2021-10-08T15:30:00+02:00 Berlin	20°C	17.857142857142865°C
2021-10-08T16:00:00+02:00 Berlin	20°C	17.714285714285722°C
2021-10-08T16:30:00+02:00 Berlin	20°C	17.57142857142858°C
2021-10-08T17:00:00+02:00 Berlin	20°C	17.428571428571438°C
2021-10-08T17:30:00+02:00 Berlin	20°C	17.285714285714295°C
2021-10-08T18:00:00+02:00 Berlin	20°C	17.142857142857153°C
2021-10-08T18:30:00+02:00 Berlin	20°C	17.000000000000007°C
2021-10-08T19:00:00+02:00 Berlin	20°C	16.857142857142865°C
2021-10-08T19:30:00+02:00 Berlin	20°C	16.714285714285722°C
2021-10-08T20:00:00+02:00 Berlin	20°C	16.571428571428577°C
2021-10-08T20:30:00+02:00 Berlin	20°C	16.42857142857143°C
2021-10-08T21:00:00+02:00 Berlin	20°C	16.28571428571429°C
2021-10-08T21:30:00+02:00 Berlin	20°C	16.142857142857146°C
2021-10-08T22:00:00+02:00 Berlin	16°C	16°C
2021-10-08T22:30:00+02:00 Berlin	16°C	null
2021-10-08T23:00:00+02:00 Berlin	16°C	null
2021-10-08T23:30:00+02:00 Berlin	16°C	null

Point: Energy

Notes:

hisMode:"consumption" is required since Setpoint is a numeric-point
with hisMode:"consumption" , hisClip doesn't change anything

With hisMode:"consumption" the interpolation mode is consumption:

if the point has the hisMode tag set to consumption this means the value at the beginning of the interval needs to be apportioned across the interpolated cells.

Func: read(navName=="Imported Energy").hisRead(2021-10-08, {-hisTotalized}).hisRollup(avg, 30min).hisInterpolate

ts	val {} == +.hisClip	{-hisTotalized}	{-hisMode}
2021-10-08T00:00:00+02:00 Berlin	1.5kWh	16843kWh	2kWh
2021-10-08T00:30:00+02:00 Berlin	1.5kWh	16843kWh	2kWh
2021-10-08T01:00:00+02:00 Berlin	1.5kWh	16844.5kWh	1.5kWh
2021-10-08T01:30:00+02:00 Berlin	1.5kWh	16844.5kWh	1.5kWh
2021-10-08T02:00:00+02:00 Berlin	1.5kWh	16846kWh	1.5kWh
2021-10-08T02:30:00+02:00 Berlin	1.5kWh	16846kWh	1.5kWh
2021-10-08T03:00:00+02:00 Berlin	2.5kWh	16848.5kWh	1.5kWh
2021-10-08T03:30:00+02:00 Berlin	2.5kWh	16848.5kWh	1.5kWh
2021-10-08T04:00:00+02:00 Berlin	2kWh	16850.5kWh	2.5kWh
2021-10-08T04:30:00+02:00 Berlin	2kWh	16850.5kWh	2.5kWh
2021-10-08T05:00:00+02:00 Berlin	3kWh	16853.5kWh	2kWh
2021-10-08T05:30:00+02:00 Berlin	3kWh	16853.5kWh	2kWh
2021-10-08T06:00:00+02:00 Berlin	0kWh	16853.5kWh	3kWh
2021-10-08T06:30:00+02:00 Berlin	0kWh	16853.5kWh	3kWh
2021-10-08T07:00:00+02:00 Berlin	4kWh	16857.5kWh	0kWh
2021-10-08T07:30:00+02:00 Berlin	4kWh	16857.5kWh	0kWh
2021-10-08T08:00:00+02:00 Berlin	4.5kWh	16862kWh	4kWh
2021-10-08T08:30:00+02:00 Berlin	4.5kWh	16862kWh	4kWh
2021-10-08T09:00:00+02:00 Berlin	2kWh	16864kWh	4.5kWh
2021-10-08T09:30:00+02:00 Berlin	2kWh	16864kWh	4.5kWh
2021-10-08T10:00:00+02:00 Berlin	4.5kWh	16868.5kWh	2kWh
2021-10-08T10:30:00+02:00 Berlin	4.5kWh	16868.5kWh	2kWh
2021-10-08T11:00:00+02:00 Berlin	3.5kWh	16872kWh	4.5kWh
2021-10-08T11:30:00+02:00 Berlin	3.5kWh	16872kWh	4.5kWh
2021-10-08T12:00:00+02:00 Berlin	0.5kWh	16872.5kWh	3.5kWh
2021-10-08T12:30:00+02:00 Berlin	0.5kWh	16872.5kWh	3.5kWh
2021-10-08T13:00:00+02:00 Berlin	1.5kWh	16874kWh	0.5kWh
2021-10-08T13:30:00+02:00 Berlin	1.5kWh	16874kWh	0.5kWh
2021-10-08T14:00:00+02:00 Berlin	0kWh	16874kWh	1.5kWh
2021-10-08T14:30:00+02:00 Berlin	0kWh	16874kWh	1.5kWh
2021-10-08T15:00:00+02:00 Berlin	2.5kWh	16876.5kWh	0kWh
2021-10-08T15:30:00+02:00 Berlin	2.5kWh	16876.5kWh	0kWh
2021-10-08T16:00:00+02:00 Berlin	5kWh	16881.5kWh	2.5kWh
2021-10-08T16:30:00+02:00 Berlin	5kWh	16881.5kWh	2.5kWh
2021-10-08T17:00:00+02:00 Berlin	4.5kWh	16886kWh	5kWh
2021-10-08T17:30:00+02:00 Berlin	4.5kWh	16886kWh	5kWh
2021-10-08T18:00:00+02:00 Berlin	2.5kWh	16888.5kWh	4.5kWh
2021-10-08T18:30:00+02:00 Berlin	2.5kWh	16888.5kWh	4.5kWh
2021-10-08T19:00:00+02:00 Berlin	4kWh	16892.5kWh	2.5kWh
2021-10-08T19:30:00+02:00 Berlin	4kWh	16892.5kWh	2.5kWh
2021-10-08T20:00:00+02:00 Berlin	1kWh	16893.5kWh	4kWh
2021-10-08T20:30:00+02:00 Berlin	1kWh	16893.5kWh	4kWh
2021-10-08T21:00:00+02:00 Berlin	0kWh	16893.5kWh	1kWh
2021-10-08T21:30:00+02:00 Berlin	0kWh	16893.5kWh	1kWh
2021-10-08T22:00:00+02:00 Berlin	3kWh	16896.5kWh	0kWh
2021-10-08T22:30:00+02:00 Berlin	3kWh	16896.5kWh	0kWh
2021-10-08T23:00:00+02:00 Berlin	3kWh	33796kWh	6kWh
2021-10-08T23:30:00+02:00 Berlin	null	null	null

lib:his Functions

Here the list of the his functions. For more details look at the SkyFoundry documentation

covAvg	Folding function for generating a time weighted average on change-of-value histories (where `hisInterpolate()` is "cov")
discreteBoolPeriods	Fold timestamp/bool value pairs into an encoded Str of discrete minutely intervals
discreteEnumPeriods	Fold timestamp/enum Str value pairs into an encoded Str of discrete minutely intervals
discretePeriods	Fold timestamp/bool value pairs into an encoded Str of discrete minutely intervals
durTrue	Fold function for folding timestamp/bool value pairs into durations when true (runtime)
hisClear	Clear the history items in the given range
hisClip	Remove the rows with leading/trailing timestamps from the actual query range
hisInterpolate	Interpolate all the null value cells for each timestamp
hisJoin	Given a list of history grids, join them by the `ts` timestamp column
hisRead	Query history for an arbitrary range
hisRemove	Remove items from a history using a timestamp or timestamp range
hisRewrite	Rewrite every item of a history using the given transformation function
hisRollup	Roll up a history grid over discrete intervals of time with the given fold function
hisRollupAuto	Automatically chooses the best rollup interval and the best rollup fold function for each history
hisRollups	Perform a series of rollups over discrete intervals
hisSync	Block until any pending history writes/clears are completed
hisWrite	Asynchronously write the specified timestamp/value pairs to the history
parseDiscreteBoolPeriods	Parse a Base64 encoded timeline of discrete Bool periods as encoded by `discreteBoolPeriods()`
parseDiscreteEnumPeriods	Parse a base64 encoded string timeline of discrete enum periods as encoded by `discreteEnumPeriods()`
parseDiscretePeriods	Parse a base64 encoded string timeline of discrete periods as encoded by `discretePeriods()`

FIN Framework

Axon - lib:his

Summary

Examples/Exercises

His Computed: Generate Fake histories

His Imported: Write\Read his to\from csv file

His Collected

Sampled

Change Of Value

Consumption

Tags usually required

Tags usually required

Tags usually required

Read Raw his data in span:date..date

Read Raw his data in span:dateTime..dateTime

Read his data in span:dateTime..dateTime with rollup

Read his data in span:date..date with rollup and interpolate

lib:his Functions