Module: data

Methods

---

<inner> aggregateNestedDataLayers(layerData, resultKey, copyProperties, sumProperties, staticProperties)

Combine the layers resulting from a d3.nest operation into a single, aggregated layer.

This can be used to combine all sources of a single data type, for example to show all "power" sources as a single layer of chart data. The resulting object has the same structure as the input layerData parameter, with just a single layer of data.

For example:

const layerData = [
  { key : 'A', values : [{watts : 123, foo : 1}, {watts : 234, foo : 2}] },
  { key : 'B', values : [{watts : 345, foo : 3}, {watts : 456, foo : 4}] }
];

const result = aggregateNestedDataLayers(layerData,
    'A and B', ['foo'], ['watts'], {'combined' : true});

Then result would look like this:

[
  { key : 'A and B', values : [{watts : 468, foo : 1, combined : true},
                               {watts : 690, foo : 2, combined : true}] }
]

Parameters:

Name	Type	Description
layerData	Array.<object>	An array of objects with key and values properties, as returned from d3.nest().entries() Properties Name Type Description key string The layer's key value. values Array.<object> The layer's value array.
resultKey	string	The key property to assign to the returned layer.
copyProperties	Array.<string>	An array of string property names to copy as-is from the first layer's data values.
sumProperties	Array.<string>	An array of string property names to add together from all layer data.
staticProperties	object	Static properties to copy as-is to all output data values.

Returns:

An array of objects with key and value properties, the same structure as the provided layerData argument

Type

Array.<object>

---

<inner> groupedBySourceMetricDataArray(data, metricName [, sourceIdMap] [, aggFn])

Transform raw SolarNetwork timeseries data by combining datum from multiple sources into a single data per time key.

This method produces a single array of objects with metric properties derived by grouping that property within a single time slot across one or more source IDs. Conceptually this is similar to module:data~aggregateNestedDataLayers except groups of source IDs can be produced in the final result.

The data will be passed through module:data~normalizeNestedStackDataByDate so that every result object will contain every configured output group, but missing data will result in a null value.

Here's an example where two sources A and B are combined into a single group Generation and a third source C is passed through as another group Consumption:

const queryData = [
    {localDate: '2018-05-05', localTime: '11:00', sourceId: 'A', watts : 123},
    {localDate: '2018-05-05', localTime: '11:00', sourceId: 'B', watts : 234},
    {localDate: '2018-05-05', localTime: '11:00', sourceId: 'C', watts : 345},
    {localDate: '2018-05-05', localTime: '12:00', sourceId: 'A', watts : 456},
    {localDate: '2018-05-05', localTime: '12:00', sourceId: 'B', watts : 567},
    {localDate: '2018-05-05', localTime: '12:00', sourceId: 'C', watts : 678},
];
const sourceMap = new Map([
    ['A', 'Generation'],
    ['B', 'Generation'],
    ['C', 'Consumption'],
]);

const result = groupedBySourceMetricDataArray(queryData, 'watts', sourceMap);

Then result would look like this:

[
    {date : new Date('2018-05-05T11:00Z'), Generation : 357, Consumption: 345},
    {date : new Date('2018-05-05T12:00Z'), Generation : 1023, Consumption: 678}
]

Parameters:

Name	Type	Argument	Description
data	Array.<object>		the raw data returned from SolarNetwork
metricName	string		the datum property name to extract
sourceIdMap	Map	<optional>	an optional mapping of input source IDs to output source IDs; this can be used to control the grouping of data, by mapping multiple input source IDs to the same output source ID
aggFn	function	<optional>	an optional aggregate function to apply to the metric values; defaults to d3.sum; note that the function will be passed an array of input data objects, not metric values

Returns:

array of datum objects, each with a date and one metric value per source ID

Type

Array.<object>

---

<inner> normalizeNestedStackDataByDate(layerData [, fillTemplate] [, fillFn])

Normalize the data arrays resulting from a d3.nest operation so that all group value arrays have the same number of elements, based on a Date property named date.

The data values are assumed to be sorted by date already, and are modified in-place. This makes the data suitable to passing to d3.stack, which expects all stack data arrays to have the same number of values, for the same keys. When querying for data in SolarNetwork there might be gaps in the results, so this function can be used to "fill in" those gaps with "dummy" values so that there are no more gaps.

Filled-in data objects are automatically populated with an appropriate date property and a sourceId property taken from the key of the layer the gap if found in. You can pass a fillTemplate object with static properties to also include on all filled-in data objects. You can also pass a fillFn function to populate the filled-in objects with dynamic data.

For example, given:

const layerData = [
  { key : 'A', values : [{date : new Date('2011-12-02 12:00')}, {date : new Date('2011-12-02 12:10')}] },
  { key : 'B', values : [{date : new Date('2011-12-02 12:00')}] }
];

normalizeNestedStackDataByDate(layerData);

The layerData would be modified in-place and look like this (notice the filled in second data value in the B group):

[
  { key : 'A', values : [{date : new Date('2011-12-02 12:00')}, {date : new Date('2011-12-02 12:10')}] },
  { key : 'B', values : [{date : new Date('2011-12-02 12:00')}, {date : new Date('2011-12-02 12:10'), sourceId : 'B'}] }
]

Parameters:

Name	Type	Argument	Description
layerData	Array.<object>		An array of objects with key and values properties, as returned from d3.nest().entries() Properties Name Type Description key string The layer's key value. values Array.<object> The layer's value array.
fillTemplate	object	<optional>	An object to use as a template for any filled-in data objects. The date property will be populated automatically, and a sourceId property will be populated by the layer's key.
fillFn	module:data~NestedDataOperatorFunction	<optional>	An optional function to populate filled-in data objects with. This function is invoked after populating any fillTemplate values.

Returns:

Type

void

---

<inner> timeNormalizeDataArray(data, aggregate)

Normalize a data array of time series data based on an aggregate time step.

This method is useful for "filling in" gaps of data in situations where something expects the data include placeholders for the gaps. Charting applications often expect this, for example.

Each element in the data array is expected to provide a date property that is a Date object. When gaps are discovered in the array, "filler" objects will be inserted with an approprate date value and all other properties copied from the previous element but set to null.

Here's an example where a new element is added to an array to fill in a missing time slot:

const queryData = [
    {date : new Date('2018-05-05T11:00Z'), Generation : 357, Consumption: 345},
    {date : new Date('2018-05-05T12:00Z'), Generation : 1023, Consumption: 678}
]

timeNormalizeDataArray(queryData, Aggregations.ThirtyMinute);

Then queryData would look like this:

[
    {date : new Date('2018-05-05T11:00Z'), Generation : 357, Consumption: 345},
    {date : new Date('2018-05-05T11:30Z'), Generation : null, Consumption: null},
    {date : new Date('2018-05-05T12:00Z'), Generation : 1023, Consumption: 678}
]

Parameters:

Name	Type	Description
data	Array.<object>	the raw data returned from SolarNetwork; this array is modified in-place
aggregate	module:domain~Aggregation	the expected aggregate level of the data

Returns:

Type

void

Type Definitions

---

NestedDataOperatorFunction(datum, key [, prevDatum])

A callback function that operates on a nested data layer datum object.

Parameters:

Name	Type	Argument	Description
datum	object		the datum object being operated on
key	string		the layer key the datum object is a member of
prevDatum	object	<optional>	the previous datum object in the layer, if available

Returns:

Type

void