TITLE:: FluidStandardize
summary:: Standardize a FluidDataSet
categories:: FluidManipulation
related:: Classes/FluidDataSet, Classes/FluidStandardize

DESCRIPTION::
Standardize a link::Classes/FluidDataSet::, i.e. rescale using its mean(s) and standard deviation(s) in each dimension.

See http://www.faqs.org/faqs/ai-faq/neural-nets/part2/section-16.html

CLASSMETHODS::

METHOD:: new
Create a new instance
ARGUMENT:: server
The server for this model

INSTANCEMETHODS::

METHOD:: fit
Fit model to a DataSet without applying scaling
ARGUMENT:: dataSet
The link::Classes/FluidDataSet:: to standardize
ARGUMENT:: action
A function to run when processing is complete

METHOD:: transform
Standardize a link::Classes/FluidDataSet::, using the learned statistics from a previous call to link::Classes/FluidStandardize#fit::
ARGUMENT:: sourceDataSet
The link::Classes/FluidDataSet:: to standardize
ARGUMENT:: destDataSet
The link::Classes/FluidDataSet:: to populate with standardized data
ARGUMENT:: action
A function to run when processing is complete

METHOD:: fitTransform
Standardize a link::Classes/FluidDataSet:: into another link::Classes/FluidDataSet::
ARGUMENT:: sourceDataSet
The link::Classes/FluidDataSet:: to standardize
ARGUMENT:: destDataSet
The link::Classes/FluidDataSet:: to populate with standardized data
ARGUMENT:: action
A function to run when processing is complete

METHOD:: transformPoint
Standardize a new data point, using the learned statistics from a previous call to link::Classes/FluidStandardize#fit::
ARGUMENT:: sourceBuffer
A link::Classes/Buffer:: with the new data point
ARGUMENT:: destBuffer
A link::Classes/Buffer:: to contain the standardize value
ARGUMENT:: action
A function to run when processing is complete

EXAMPLES::
code::
s.boot;
//Preliminaries: we want some audio, a couple of FluidDataSets, some Buffers and a FluidStandardize
(
~audiofile = File.realpath(FluidBufPitch.class.filenameSymbol).dirname +/+ "../AudioFiles/Tremblay-ASWINE-ScratchySynth-M.wav";
~raw = FluidDataSet(s,\stand_help_raw);
~stand = FluidDataSet(s,\stand_help_standd);
~audio = Buffer.read(s,~audiofile);
~pitch_feature = Buffer.new(s);
~stats = Buffer.alloc(s, 7, 2);
~standardizer = FluidStandardize(s);
)


// Load audio and run a pitch analysis, which gives us pitch and pitch confidence (so a 2D datum)
(
~audio = Buffer.read(s,~audiofile);
FluidBufPitch.process(s,~audio, features: ~pitch_feature);
)

// Divide the time series in to 10, and take the mean of each segment and add this as a point to
// the 'raw' FluidDataSet
(
{
	var trig = LocalIn.kr(1, 1);
	var buf =  LocalBuf(2, 1);
    var count = PulseCount.kr(trig) - 1;
	var chunkLen = (~pitch_feature.numFrames / 10).asInteger;
	var stats = FluidBufStats.kr(
			source: ~pitch_feature, startFrame: count * chunkLen,
			numFrames: chunkLen, stats: ~stats, trig: trig
	);
	var rd = BufRd.kr(2, ~stats, DC.kr(0), 0, 1);// pick only mean pitch and confidence
	var wr1 = BufWr.kr(rd[0], buf, DC.kr(0));
	var wr2 = BufWr.kr(rd[1], buf, DC.kr(1));
	var dsWr = FluidDataSetWr.kr(\stand_help_raw, buf: buf, trig: Done.kr(stats));
	LocalOut.kr( Done.kr(dsWr));
	FreeSelf.kr(count - 9);
}.play;
)


// Standardize and load to language-side array
(
~rawarray = Array.new(10);
~stdarray= Array.new(10);
~standardizer.fitTransform(~raw,~stand, {
	~raw.dump{|x| 10.do{|i|
		~rawarray.add(x["data"][i.asString])
	}};
	~stand.dump{|x| 10.do{|i|
		~stdarray.add(x["data"][i.asString])
	}};
});
)

(
~rawarray.flatten(1).unlace.plot("Unstandardized",Rect(0,0,400,400),minval:0,maxval:[5000,1]).plotMode=\bars;
~plot2 = ~stdarray.flatten(1).unlace.plot("Standardized",Rect(410,0,400,400)).plotMode=\bars;
)
::

subsection::Server Side Querying

Because FluidStandardize runs in its own link::Classes/Synth:: on the server, communication is done via control-rate link::Classes/Bus:: objects for triggering and link::Classes/Buffer:: objects for passing and retreiving data.

code::
//Setup
(
~tempPoint = Buffer.alloc(s,2);
~predictPoint = Buffer.alloc(s,2);
~avgBuf = Buffer.alloc(s,100,2);
~pitchingBus = Bus.control;
~catchingBus = Bus.control;
)

(
~standardizer.inBus_(~pitchingBus).outBus_(~catchingBus).inBuffer_(~tempPoint).outBuffer_(~predictPoint);
//Pitching (no pun intended): read frames out of buffer and pass to standardize
{
	var audio = BufRd.ar(1,~audio,LFSaw.ar(BufDur.ir(~audio).reciprocal).range(0, BufFrames.ir(~audio)));
	var counter = Stepper.ar(Impulse.ar(ControlRate.ir),max:99);
	var trig = HPZ1.ar(counter) < 0;
	//average 10 frames: one could use the MovingAverage extension here
	var avg;
	BufWr.kr(FluidPitch.kr(audio),~avgBuf,phase:counter);
	avg = Mix.new(BufRd.kr(2, ~avgBuf, phase:100.collect{|x|x})) * 0.01;
	//assemble data point
	BufWr.kr(avg[0],~tempPoint,0);
	BufWr.kr(avg[1],~tempPoint,1);
	Poll.kr(T2K.kr(trig),BufRd.kr(1,~tempPoint,[0,1]),["pitch (raw)", "confidence (raw)"]);
	Out.kr(~pitchingBus.index,[T2K.kr(trig)]);
}.play(~standardizer.synth,addAction:\addBefore);

//catching
{
	Poll.kr(In.kr(~catchingBus.index),BufRd.kr(1,~predictPoint,[0,1]),["pitch (standardized)", "confidence (standardized)"])
}.play(~standardizer.synth,addAction:\addAfter);

)
::