flucoma-sc/release-packaging/HelpSource/Classes/FluidDataSet.schelp

TITLE:: FluidDataSet
summary:: Container for labelled,  multidimensional data
categories:: UGens>FluidManipulation
related:: Classes/FluidLabelSet, Classes/FluidKDTree, Classes/FluidKMeans
​
DESCRIPTION::
A server-side container associating labels with multi-dimensional data. FluidDataSet is identified by its name.

CLASSMETHODS::
​
PRIVATE:: asUGenInput

METHOD:: new
Create a new instance of the DataSet, with the given name. If a DataSet with this name already exists, an exception will be thrown (see link::Classes/FluidDataSet#at:: to access an existant DataSet).

ARGUMENT:: server
The link::Classes/Server:: on which to create the data set.

​
returns:: The new instance

INSTANCEMETHODS::
​
PRIVATE:: init,id,cache

METHOD:: addPoint
Add a new point to the data set. The dimensionality of the DataSet is governed by the size of the first point added.
Will report an error if the label already exists, or if the size of the data does not match the dimensionality of the DataSet.
ARGUMENT:: label
A symbol or string with the label for the new point.
ARGUMENT:: buffer
A link::Classes/Buffer:: with the new data point.
ARGUMENT:: action
A function to run when the point has been added.
​​
METHOD:: updatePoint
Update an existing label's data. Will report an error if the label doesn't exist, or if the size of the data does not match the given dimensionality of the DataSet.

METHOD:: getPoint
Retrieve a point from the data set into a link::Classes/Buffer::. Will report an error if the label or buffer doesn't exist​.

METHOD:: deletePoint
Remove a point from the data set. Will report an error if the label doesn't exist.
​​
METHOD:: clear
Empty the data set.
​
METHOD:: merge
Merge sourceDataSet in the current DataSet. It will update the value of points with the same label if overwrite is set to 1. To add columns instead, see the 'transformJoin' method of link::Classes/FluidDataSetQuery::

METHOD:: free
Destroy the object on the server.

METHOD:: print
Post an abbreviated content of the DataSet in the window by default, but you can supply a custom action instead.

returns:: A link::Classes/Synth::
​
METHOD:: server
The server instance the object uses
​
returns:: A link::Classes/Server::

EXAMPLES::

CODE::
// Create a simple a one-dimensional data set, three ways
// Using routine
s.boot;
(
fork{
	~ds = FluidDataSet.new(s);
	~point = Buffer.alloc(s,1,1);
	s.sync;
	10.do{|i|
        ~point.set(0,i);
        ~ds.addPoint(i.asString,~point,{("addPoint"+i).postln});
        s.sync;
    };
    ~ds.dump;
      s.sync;
    ~ds.free;
};
)

//Using Dictionary
(
d = Dictionary.new;
d.add(\cols -> 1);
d.add(\data -> Dictionary.newFrom(10.collect{|i|[i.asString, [i.asFloat]]}.flatten));
fork{
    ~ds = FluidDataSet.new(s);
    ~ds.load(d); s.sync;
    ~ds.dump; s.sync; ~ds.free;
}
)

// Using a synth
(
~ds = FluidDataSet.new(s);
{
        var trig = Impulse.kr(20);
        var count = PulseCount.kr(trig) - 1;
        var buf = LocalBuf(1);
        BufWr.kr(count, buf);
        FluidDataSetWr.kr(~ds.asUGenInput, buf: buf, trig: trig);
        FreeSelf.kr(count - 8);
}.play.onFree{~ds.dump{|o| o.postln;~ds.free}}
)
::

STRONG:: Merging Datasets::
code::
//this is how to add items between 2 datasets.
//create 2 datasets
(
~dsA = FluidDataSet.new(s);
~dsB = FluidDataSet.new(s);
)

//feed them items with same dimensions but different labels
~dsA.load(Dictionary.newFrom([\cols, 1, \data, Dictionary.newFrom([\one,1,\two,2])]));
~dsB.load(Dictionary.newFrom([\cols, 1, \data, Dictionary.newFrom([\three,3,\four,4])]));
~dsA.print;
~dsB.print;

// merge and check. it works.
~dsB.merge(~dsA)
~dsB.print;

//change the content of the dataset to shared labels
~dsA.load(Dictionary.newFrom([\cols, 1, \data, Dictionary.newFrom([\three,333,\four,444])]));
~dsB.load(Dictionary.newFrom([\cols, 1, \data, Dictionary.newFrom([\three,3,\four,4])]));
~dsA.print;
~dsB.print;

//try to merge, it does not update
~dsB.merge(~dsA)
~dsB.print;

// add the overwrite flag, and it works
~dsB.merge(~dsA,1)
~dsB.print;
::