IM-JS

Class: DataSet

data. DataSet

A DataSet is a Wrapper around a SDMX-JSON DataSet to provide functions for data manipulation.

A DataSet holds an array of Observations where each Observation is uniquely identified by its Dimensions and may contain additional information in its Attributes.

A DataSet can be constructed using the new Operator and passing in SDMX-JSON where the JSON dataset is flat (dimensionAtObservation=AllDimensions). Alternatively a Dataset can be be obtained via the DataQuery and PreDefinedQuery objects

Dimensions and Attributes in a DataSet are anoalogous to both the DimensionBean and AttributeBean, in a DataSet they are both as a DataSetComponent

A DataSetComponent contains only the Codes which exist in the DataSet, these are represented as DataSetCodes.

A DataSetCode and Observations may contain links to additional ReferenceMetadata

A DatSet provides the means to group Observations by a particular dimension using the dataset.createSeries() method

A DatSet provides the means to obtain a subset of the Observations using the dataset.filterObs() method

alt text

new DataSet()

Examples

Obtain a Dataset from a DataQuery

function addQuerySelections(dataQuery) {
  //Add query filters and execute the query on the server
  dataQuery.addCodeSelection("FREQ", "A");
  dataQuery.addCodeSelection("REF_AREA", "UK");
  dataQuery.executeQuery(null, onDataQueryResponse); 
}

function onDataQueryResponse(dataset) {
  //Render the response as a HTML Pivot Table
	 var pivotTable = new PivotTable("#tableDiv");
	 pivotTable.draw(dataset);
}

Group data by time

function onDataQueryResponse(dataset) {
 var seriesGroup = dataset.createSeries("TIME_PERIOD");
 var series = seriesGroup.getSeries();
 for(var i=0; i < series.length; i++) {
    var currentSeries = series[i];
    var observations = currentSeries.getObservations();
 }
}

Obtain all Observations for United Kingdom, Males

function onDataQueryResponse(dataset) {
 var filter = {
 	"REF_AREA", "UK",
 	"SEX", "M",
 }
 var observations = dataset.filterObs(filter);
}

Methods

aggregate(array, func)

Generates an AggregatedDataSet based which aggregates the data by the dimensions passed in, using the aggregation function passed in. The aggregation function can be changed in the resulting AggregatedDataSet using AggregatedDataSet.setAggregationFunction.

Parameters:
Name Type Description
array Array.<string>

of Dimension Ids to aggregate by
func number

the aggregation function which is either
1 - sum
2 - arithmetic mean
3 - min
4 - max
5 - standard deviation
6 - standard deviation population
7 - varience
8 - variance population
9 - count

createSeries(dimensionAtObservation)

Returns SeriesGroup which is a container used to group Observations.

The grouping is based on the dimensionAtObservation grouping parameter.

Parameters:
Name Type Description
dimensionAtObservation string

the id of the Dimension to group by
Returns:
Type
data.SeriesGroup
Example
To create SeriesGroup with Series that iterate Observations over Time:

var seriesGroup = dataSet.createSeries("TIME_PERIOD");

filterObs(obsQuery)

Returns a flat Array of all the Observations which match the filter parameters.

The filter must be a JSON Object which contains one or more Dimension id to Dimension Code Id pairs.

Note: A Dimension can not map to more then one Code Id

Parameters:
Name Type Description
obsQuery object

A JSON Object of dimension values example:
{ "FREQ":"A", "REF_AREA":"UK" }
Returns:
Type
Array.<data.Observation>
Example
function onDataQueryResponse(dataset) {
 var filter = {
 	"REF_AREA", "UK",
 	"SEX", "M",
 }
 var observations = dataset.filterObs(filter);
}

getDataEndDate()

Returns the latest date for this DataSet (based on the reported Observation times)

Returns:
Type
date

getDatasetTitle()

Returns the title of the DataSet, this will be the Dataflow name

Returns:
Type
string

getDataStartDate()

Returns the earliest date for this DataSet (based on the reported Observation times)

Returns:
Type
date

getDimension(dimId)

Returns the DataSetComponent with the given id, or null if no DataSetComponents exist with the given id

Parameters:
Name Type Description
dimId string

The Dimension id, e.g FREQ
Returns:
Type
data.DataSetComponent

getDimensionId(dimIndex)

Returns the DataSetComponent Id for the given array index as it appears in the dataset.getDimensionIds method (zero indexed).

Parameters:
Name Type Description
dimIndex number

the index of the DataSetComponent in the array
Returns:
Type
string

getDimensionIds()

Return the DataSetComponent ids as a string array in the same order that the DataSetComponents appear in the dataset.getDimensions() method

Returns:
Type
Array.<string>

getDimensionIndex(dimId)

Return the data.DataSetComponent index in the data.DataSet#getDimensions array from the given data.DataSetComponent Id

Parameters:
Name Type Description
dimId string

The dimension id, e.g FREQ
Returns:

zero indexed, -1 is returned if it does not exist

Type
number

getDimensions()

Returns an array of DataSetComponent for each Dimension in this DataSet

Returns:
Type
Array.<data.DataSetComponent>

getDimensionSize(dimId)

Returns number of distinct DataSetCodes for the DataSetComponent with the given id.

Parameters:
Name Type Description
dimId string

The Dimension id, e.g FREQ
Returns:

the number of codes values for the dimension in this DataSet

Type
number

getDimensionSizes()

Returns a count of the number of distinct DataSetCodes for each DataSetComponent.

The order of the returned array is in the same sequence as the dataset.getDimensions() method

Returns:
Type
Array.<number>

getMetadata(callback)

Returns any linked ReferenceMetadata to the callback function

Parameters:
Name Type Description
callback function

to be called with ReferenceMetadata[]

getMetadataDefs()

Returns an array of metadata.ReferenceMetadataLink, or an empty array if there are none

Returns:
Type
metadata.ReferenceMetadataLink

getObs()

Returns an array of all the Observations for this DataSet

Returns:
Type
Array.<data.Observation>

getObsAttributes()

Returns the Observation Attributes for this DataSet.

For a DataSet, the Attributes have the same type as the Dimensions - DataSetComponent.

The returned array contains a DataSetComponent for each observation Attribute contained in this DataSet

Each DataSetComponent defines the unique list of reported values as DataSetCodes

Returns:
Type
Array.<data.DataSetComponent>
Example
var allAttributes = dataset.getObsAttributes();
for(var i=0; i < allAttributes.length(); i++) {
  var attr = allAttributes[i];
  var attrLable = attr.getName();   //Returns name, for example 'Observation Status'
  var codes = attr.getCodes();      //Contains all the distinct codes for this dataset, for example A [Normal Value], M [Missing Value], E [Estimated Value]
}

getObsByShortCode(shortCode)

Returns a Observation with the given Shortcode

NOTE: In the case that there are multiple occurrences of this observation due to revisions, the latest Observation is returned. The latest Observation provides access to the revisions with the observation.getRevisions() method

Parameters:
Name Type Description
shortCode string

Observation Short Code
Returns:
Type
data.Observation

getObsByUid(uid)

Returns a Observation with the given UID

Parameters:
Name Type Description
uid string

Observation UID
See:
Returns:
Type
data.Observation

getRequestURI()

Returns the data query URI that was used to retrieve this dataset, for example:
"/data/WB,WDI_ECON_POL_DEBT,1.0/.BN_KLT_DINV_CD."

Returns:
Type
string

getRevisions()

Returns all the DataSetRevision|DataSetRevisions for this DataSet

Returns:
Type
Array.<data.DataSetRevision>

getUid()

Returns a unique identifier for this dataset.

Returns:
Type
string

hasMetadata()

Returns true if there are metadata.ReferenceMetadata attached to this object, if this is true then the dataset.getMetadataDefs() method will return a non-empty array

Returns:
Type
boolean

hasObs()

Returns true if the DataSet has one or more Observations

Returns:
Type
boolean

hasRevisions()

Returns true if the DataSet has one or more Observations with revisions

See:
Returns:
Type
boolean