The Imperative API provides a set of methods that enable you to work with DataSet in a way similar to a procedural API. The goal of the extensions is to enable simple data operations with a minimum amount of code. Additionally, it unifies the API with other languages like C, R, Python etc. Note that these are just helper methods that call the universal object model API.

This page briefly descibes the methods. For a complete reference, see the documentation included in the release.
Assembly and namespace
The Imperative API is located in Microsoft.Research.Science.Data.Imperative assembly in namespace with the same name. Following using directive should be added to C# source files in order to use Imperative API.

using Microsoft.Research.Science.Data.Imperative;
Range methods
These methods are static methods of the DataSet class. They produce an instance of type Range.
  • Range(Int32 index) Gets the range of a single index.
  • Range(Int32 from, Int32 to) Gets the range of indices from from up to to.
  • Range(Int32 from, Int32 step, Int32 to) Gets the range of indices from from up to t" with step step.
  • FromToEnd(Int32 from) Gets the range of indices from from up to the maximum index for a given dimension.
  • FromToEnd(Int32 from, Int32 step) Gets the range of indices from from up to the maximum index with step for a given dimension.
  • ReduceDim(int index) Gets the range of a single index to choose and reduce a dimension.

The following methods are methods for the class DataSet and are defined in the Microsoft.Research.Science.Data.Imperative.DataSetExtensions class (assembly Microsoft.Research.Science.Data.Imperative).
Add methods
  • Add<D>(DataSet ds, String var, params String[] dims) Creates a new variable and adds it to the DataSet.
ds.Add<double[,]>("mat") // Creates a variable named "mat" of type double and of rank 2 depending on default dimensions
ds.Add<double>("mat", "x", "y") // Also creates a variable named "mat" of type double and of rank 2 depending on "x","y" 
ds.Add<double[,]>("mat", "x", "y") // Does the same
  • Add<D>(DataSet ds, String var, D data, params String[] dims) Creates a new variable with initial data and adds it to the DataSet.
ds.Add<double[,]>("mat", new double[,]{{1},{2}}); // Creates a variable named "mat" of type double and of rank 2
ds.Add<double[,]>("mat", new double[,]{{1},{2}}, "x", "y"); // Creates a variable named "mat" of type double and of rank 2 depending on "x","y"
// ds.Add<double>("mat", new double[,]{{1},{2}}, "x", "y") // It is incorrect!
ds.Add<double>("mat", 10.0); // Creates a scalar variable with value 10.0
PutData methods
  • PutData<D>(DataSet ds, Func<Variable, Boolean> predicate, D data) Replaces all the variable data with a new one.
// Opens a data set:
var ds = DataSet.Open("test.csv?openMode=open");        
// Updates a variable that satisfies the predicate:
ds.PutData(v => v.Metadata["action"] == "toUpdate", new int[] { 9, 8, 7, 6 });
  • PutData<D>(DataSet ds, Int32 var, D data) Replaces all the variable data with new values.
// Opens a data set:
var ds = DataSet.Open("test.csv?openMode=create");        
var id = ds.Add<int[]>("int1").ID;
// Updates a one-dimensional variable with given id:
ds.PutData(id, new int[] { 9, 8, 7, 6 });
  • PutData<D>(DataSet ds, String var, D data) Replaces all the variable data with new values.
// Opens a data set:
var ds = DataSet.Open("test.csv?openMode=open");        
// Updates a one-dimensional variable with name "int1" and type of data int:
ds.PutData("int1", new int[] { 9, 8, 7, 6 });
  • PutData<D>(DataSet ds, Func<Variable, Boolean> predicate, D data, params Range[] range) Puts a range of values into a variable.
  • PutData<D>(DataSet ds, Func<Variable, Boolean> predicate, D data, params Int32[] indices) Sets one value in the variable data.
  • PutData<D>(DataSet ds, Int32 var, D data, params Range[] rage) Puts a range of values into a variable.
  • PutData<D>(DataSet ds, Int32 var, D data, params Int32[] indices) Sets one value in the variable data.
// Creates new data set:
var ds = DataSet.Open("test.csv?openMode=create");
// Adds a new variable with name "int1" that is a one-dimensional array of int and depends on dimension "idx".
// id2 contains the unique identifier of the new variable.
int id2 = ds.Add<int[]>("int1", "idx").ID;
// Sets the first element of the id2 to 7:
ds.PutData(id2, 7, 0);
  • PutData<D>(DataSet ds, String var, D data, params Range[] range) Puts a range of values into a variable.
// Let variable "var2d" has rank 2
ds.PutData<double[]>( "var2d", new double[] { 1, 2, 3 }, 
 DataSet.Range(0,2), // 1st dim: from 0 to 2
 DataSet.ReduceDim(1)); // 2nd dim is reduced in the input data set and its index is 1.
  • PutData<D>(DataSet ds, String var, D data, params Int32[] range) Sets one value in the variable data.

Examples
// Creates a new data set:
var ds = DataSet.Open("test.csv?openMode=create");

// Adds a new string scalar variable with name "str" to the data set:
ds.Add<string>("str"); 

// Data for the variable "str" is "data string":
ds.PutData("str", "data string");

// Adds a new variable with name "int1" that is a one-dimensional array of int and depends on dimension "idx".
// id2 contains the unique identifier of the new variable.
int id2 = ds.Add<int[]>("int1", "idx").ID;

// Data of the variable "int1" is { 9, 8, 7, 6 }:
ds.PutData(id2, new int[] { 9, 8, 7, 6 });

// Adds a new variable "double2" depending on two dimensions:
ds.Add<double>("double2", "i1", "i2");

// Adds a new variable "double3" depending on 3 default dimensions:
ds.Add<double[, ,]>("double3");

// Displays the data set brief description:
Console.WriteLine(ds);
Append methods
  • Append<D>(DataSet ds, Func<Variable, Boolean> predicate, D data) Appends data to a variable.
  • Append<D>(DataSet ds, Int32 var, D data) Appends data to a variable.
// Creates new data set:
var ds = DataSet.Open("test.csv?openMode=create");
// Adds a new variable with name "int1" that is a one-dimensional array of int and depends on dimension "idx".
// id2 contains the unique identifier of the new variable.
int id2 = ds.Add<int[]>("int1", "idx").ID;
// Data of the variable "int1" is { 9, 8, 7, 6 }:
ds.PutData(id2, new int[] { 9, 8, 7, 6 });
// Appends one more value to the end of the variable:
ds.Append(id2, 5);
// Now id2 contains { 9, 8, 7, 6, 5 }
  • Append<D>(DataSet ds, String var, D data) Appends data to a variable.
  • Append<D>(DataSet ds, Func<Variable, Boolean> predicate, D data, Int32 dim) Appends data to a variable.
  • Append<D>(DataSet ds, Func<Variable, Boolean> predicate, D data, String dim) Appends data to a variable.
  • Append<D>(DataSet ds, Int32 var, D data, Int32 dim) Appends data to a variable.
  • Append<D>(DataSet ds, Int32 var, D data, String dim) Appends data to a variable.
  • Append<D>(DataSet ds, String var, D data, Int32 dim) Appends data to a variable.
  • Append<D>(DataSet ds, String var, D data, String dim) Appends data to a variable.
GetData methods
  • GetData<D>(DataSet ds, Func<Variable, Boolean>) Gets all data from a variable.
  • GetData<D>(DataSet ds, Int32) Gets all data from a variable.
// Opens a data set:
var ds = DataSet.Open("test.csv?openMode=open");        
// Gets a value from a scalar variable of type double with given id:
int varID = ...;
double val = ds.GetData<double>(varID); 
// Gets an array from a one-dimensional variable of type string:
int var2ID = ...;
string[] strings = ds.GetData<string[]>(var2ID);
  • GetData<D>(DataSet ds, String var) Gets all data from a variable.
  • GetData<D>(DataSet ds, Func<Variable, Boolean> predicate, params Range[] range) Gets a range of values from a variable.
  • GetData<D>(DataSet ds, Func<Variable, Boolean> predicate, params Int32[] indices) Gets a single value from a variable.
  • GetData<D>(DataSet ds, Int32 var, params Range[] range) Gets a range of values from a variable.
// Opens a data set:
var ds = DataSet.Open("test.csv?openMode=open");        
// Gets a value from a scalar variable of type double with given id:
int varID = ...; // id of 3d variables
double[,,] val3d = ds.GetData<double[,,]>(varID); // Gets all data.
double[,] val2d = ds.GetData<double[,]>(varID, 
     DataSet.ReduceDim(0), // First index is 0 and reduced from output array
     DataSet.Range(0, 3, 100), // Takes every third element by 2nd dimension
     DataSet.FromToEnd(100)); // Takes all elements starting with index 100
  • GetData<D>(DataSet ds, Int32 var, params Int32[] indices) Gets a single value from a variable.
  • GetData<D>(DataSet ds, String var, params Range[] range) Gets a range of values from a variable.
  • GetData<D>(DataSet ds, String var, params Int32[] indices) Gets a single value from a variable.
// Opens a data set:
var ds = DataSet.Open("test.csv?openMode=open");        
// Gets a value from a scalar variable named "str" of type string:
string val = ds.GetData<double>("str"); 
// Gets the 3rd (index starts from zero) value from a one-dimensional variable named "int1" of type int:
int data = ds.GetData<int>("int1", 2);
PutAttr methods
  • PutAttr(DataSet ds, Func<Variable, Boolean> predicate, String attr, Object value) Sets a metadata attribute value.
  • PutAttr(DataSet ds, Int32 var, String attr, Object value) Sets a metadata attribute value.
  • PutAttr(DataSet ds, String var, String attr, Object value) Sets a metadata attribute value.
// Opens a data set:
var ds = DataSet.Open("test.csv?openMode=open");        
// Sets attribute "range" of variable "var":
ds.PutAttr("var", "range", new int[] { 0, 100 });
GetAttr methods
  • GetAttr(DataSet ds, Func<Variable, Boolean> predicate, String attr) Gets a metadata attribute value.
  • GetAttr<D>(DataSet ds, Func<Variable, Boolean> predicate, String attr) Gets a metadata attribute value.
  • GetAttr(DataSet ds, Int32 var, String attr) Gets a metadata attribute value.
  • GetAttr<D>(DataSet ds, Int32 var, String attr) Gets a metadata attribute value.
  • GetAttr(DataSet ds, String var, String attr) Gets a metadata attribute value.
// Opens a data set:
var ds = DataSet.Open("test.csv?openMode=open");        
// Gets attribute "range" from variable "var":
object range = ds.GetAttr("var", "range");
  • GetAttr<D>(DataSet ds, String var, String attr) Gets a metadata attribute value.
// Opens a data set:
var ds = DataSet.Open("test.csv?openMode=open");        
// Gets attribute "range" from variable "str":
int[] range = ds.GetAttr<int[]>("str", "range"); 
int min = range[0];
int max = range[1];

Last edited Jul 18, 2010 at 9:35 AM by sberezin, version 22

Comments

RupertHardy Jul 22, 2015 at 11:34 AM 
This is a nice, easy to use library, except for one omission :-

dataSet
.AddVariable<byte>("array", new[] { "dim1", "dim2" })
.PutData(new byte[,] { { 0, 1 } });

...works fine, along with many other types, whereas

dataSet
.AddVariable<char>("array", new[] { "dim1", "dim2" })
.PutData(new char[,] { { 'c', '\0' } });

Throws an exception "Not supported type of data". I'm building files that will be used by a library I don't have a great deal of control over that expects the 'char' type. Is there a work around?