PhotosynQ Documentation

# Provided Functions

PhotosynQ is providing additional functions for building macros to simplify the measurement data analysis. The list includes functions from the native JavaScript Math object. More details on these Helper Functions are available here (opens new window).

# Available Functions

# ArrayNth

Extract every n-th element from an array.

# Parameters

# Examples

ArrayNth( [ 1, 2, 3, 4, 5, 6], 2, 2 );
// returns [3, 5]

Returns (Array (opens new window)<number (opens new window)> | void) Every n-th element.

# ArrayRange

This is a flexible function to generate an array of arithmetic progressions.
All arguments must be integers.

# Parameters

# Examples

ArrayRange(10);
// returns [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

ArrayRange(1,11);
// returns [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

ArrayRange(0, 30, 5);
// returns [0, 5, 10, 15, 20, 25]

ArrayRange(0, 10, 3);
// returns [0, 3, 6, 9]

ArrayRange(0, 10, 3, "x2");
// returns [0, 9, 36, 81]

ArrayRange(0, -10, -1);
// returns [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]

ArrayRange(0);
// returns []

ArrayRange(1,0);
// returns []

Returns (Array (opens new window)<number (opens new window)> | void)

# ArrayUnZip

This function transforms an array of [x, y] pairs into an object with an array of x and an array of y values

# Parameters

# Examples

ArrayUnZip( [ [1, 4], [2, 5], [3, 6] ] );
//returns {x: [1, 2, 3], y: [4, 5, 6]}

Returns (object (opens new window) | void) { x: [x1, x2, ..., xn], y: [y1, y2, ..., yn] }

# ArrayZip

This function transforms two arrays into one array of x,y pairs
Both arrays supplied need to have the same size.

# Parameters

# Examples

var x = [1, 2, 3];
var y = [4, 5, 6];
ArrayZip(x,y)
//returns [ [1, 4], [2, 5], [3, 6] ]

Returns (Array (opens new window)<number (opens new window)> | void) [ [x1,y1], [x2,y2], ..., [xn,yn] ].

# danger

Add a Danger Message for the User. These messages will be shown in the data viewer as well.
Use these messages to indicate a problematic issue that will most likely result in an invalid measurement.

# Parameters

# Examples

danger('Your Danger Message', output);
// output['messages']['info']['Your Danger Message']

Returns object (opens new window) pushes the message into the output object.

# GetIndexByLabel

Find the positions for protocols within a protocol set matching the
provided label. If only one label exists within a set, a number is returned.
When multiple protocols in the set have the same label an array with all
indexes of matching labels is returned.

# Parameters

# Examples

GetIndexByLabel( "PAM", json );
// returns e.g. 1 or [1,2]

GetIndexByLabel( "PAM", json, true );
// returns e.g. [1] or [1,2]

Returns (number (opens new window) | Array (opens new window)<number (opens new window)>) Single index or an array of indexes

# GetLabelLookup

Generate a protocol lookup table for a protocol set.

# Parameters

# Examples

GetLabelLookup(json);
// returns e.g. { "PAM": [0,2], "ECS": [1]}

Returns object (opens new window) Lookup table

# GetProtocolByLabel

Returns the protocol from within the protocol set matching the provided label.
If only one label exists, one protocol object is returned.
When multiple protocols in the set have the same label an array with all
protcol objects of matching labels is returned.

# Parameters

# Examples

GetIndexByLabel( "PAM", json );
// returns e.g. { "label": "PAM", ...} or [{ "label": "PAM", ...}, { "label": "PAM", ...}]

GetIndexByLabel( "PAM", json, true );
// returns e.g. [{ "label": "PAM", ...}] or [{ "label": "PAM", ...}, { "label": "PAM", ...}]

Returns (Object (opens new window) | Array (opens new window)<Object (opens new window)>) Single protocol or an array of protocols

# info

Add an Info Message for the User.
Use these messages to give additional information (if necessary).

# Parameters

# Examples

info('Your Info Message', output);
// output['messages']['info']['Your Info Message']

Returns object (opens new window) pushes the message into the output object.

# Math.abs

Math.abs(x) returns the absolute value of x.

# Parameters

# Examples

Math.abs(4.7);
// returns 5
Math.abs(4.4);
// returns 4;

Returns number (opens new window)

# Math.acos

Math.acos(x) returns the arccosine of x, in radians.

# Parameters

# Examples

Math.acos(0.5);
// returns 1.0471975511965979

Returns number (opens new window)

# Math.asin

Math.asin(x) returns the arcsine of x, in radians.

# Parameters

# Examples

Math.asin(0.5);
// returns 0.5235987755982989

Returns number (opens new window)

# Math.atan

Math.atan(x) returns the arctangent of x as a numeric value between -PI/2 and PI/2 radians.

# Parameters

# Examples

Math.atan(0.5);
// returns 0.4636476090008061

Returns number (opens new window)

# Math.atan2

Math.atan2(y, x) returns the arctangent of the quotient of its arguments.

# Parameters

# Examples

Math.atan2(0.5,2);
// returns 0.24497866312686414

Returns number (opens new window)

# Math.ceil

Math.ceil(x) returns the value of x rounded up to its nearest integer.

# Parameters

# Examples

Math.ceil(4.7);
// returns 5

Returns number (opens new window)

# Math.cos

Math.cos(x) returns the cosine of x (x is in radians).

# Parameters

# Examples

Math.cos(1);
// returns 0.5403023058681398

Returns number (opens new window)

# Math.E

Euler's number (approx. 2.718).

# Examples

Math.E;
// returns 2.718281828459045

Returns number (opens new window) 2.718281828459045

# Math.exp

Math.exp(x) returns the value of Ex.

# Parameters

# Examples

Math.exp(3);
// returns 20.085536923187668

Returns number (opens new window)

# Math.floor

Math.floor(x) returns the value of x rounded down to its nearest integer.

# Parameters

# Examples

Math.floor(4.7);
// returns 4

Returns number (opens new window)

# Math.LN10

Natural logarithm of 10 (approx. 2.302).

# Examples

Math.LN10;
// returns 2.302585092994046

Returns number (opens new window) 2.302585092994046

# Math.LN2

Natural logarithm of 2 (approx. 0.693).

# Examples

Math.LN2;
// returns 0.6931471805599453

Returns number (opens new window) 0.6931471805599453

# Math.log

Math.log(x) returns the natural logarithm (base E) of x.

# Parameters

# Examples

Math.log(4.7);
// returns 1.547562508716013

Returns number (opens new window)

# Math.LOG10E

Base-10 logarithm of E (approx. 0.434).

# Examples

Math.LOG10E;
// returns 0.4342944819032518

Returns number (opens new window) 0.4342944819032518

# Math.LOG2E

Base-2 logarithm of E (approx. 1.442).

# Examples

Math.LOG2E;
// returns 1.4426950408889634

Returns number (opens new window) 1.4426950408889634

# Math.max

Math.max(x, y, z, ..., n) returns the number with the highest value.

# Parameters

# Examples

Math.max(0, 150, 30, 20, -8, -200);
// returns 150

Returns number (opens new window)

# Math.min

Math.min(x, y, z, ..., n) returns the number with the lowest value.

# Parameters

# Examples

Math.min(0, 150, 30, 20, -8, -200);
// returns -200

Returns number (opens new window)

# Math.PI

PI (approx. 3.14)

# Examples

Math.PI;
// returns 3.141592653589793

Returns number (opens new window) 3.141592653589793

# Math.pow

Math.pow(x, y) returns the value of x to the power of y.

# Parameters

# Examples

Math.pow(3,2);
// returns 9

Returns number (opens new window)

# Math.random

Random number

# Examples

Math.random();
// returns a random number

Returns number (opens new window) between 0 and 1

# Math.round

Math.round(x) returns the value of x rounded to its nearest integer.

# Parameters

# Examples

Math.round(4.7);
// returns 5
// Math.round(4.4);
// returns 4

Returns number (opens new window)

# Math.sin

Math.sin(x) returns the sine of x (x is in radians).

# Parameters

# Examples

Math.sin(1);
// returns 0.8414709848078965

Returns number (opens new window)

# Math.sqrt

Math.sqrt(x) returns the square root of x.

# Parameters

# Examples

Math.sqrt(2);
// returns 1.4142135623730951

Returns number (opens new window)

# Math.SQRT1_2

Square root of 1/2 (approx. 0.707).

# Examples

Math.SQRT1_2;
// returns 0.7071067811865476

Returns number (opens new window) 0.7071067811865476

# Math.SQRT2

Square root of 2 (approx. 1.414).

# Examples

Math.SQRT2;
// returns 1.4142135623730951

Returns number (opens new window) 1.4142135623730951

# Math.tan

Math.tan(x) returns the tangent of an angle.

# Parameters

# Examples

Math.tan(1);
// returns 1.5574077246549023

Returns number (opens new window)

# MathEXPINVREG

Fit exponential decay to Y = Y0 + Ae^(-x/t)
A and t are the fitted variables, the provided input array needs to be an array of x,y pairs.

# Parameters

# Examples

MathEXPINVREG( [ [x1,y1], [x2,y2], ..., [xn,yn] ] );
// returns
{
  "points": [ [x1,y1], [x2,y2], ..., [xn,yn] ],
	 "results": [A, t],
	 "error": yError,
  "asymptote": asymptote,
  "rsquared": linReg.rsquared,
  "lifetime": lifetime,
	 "slope": slope
}

Returns object (opens new window) Results from fit including points, values for A and t, error, asymptote, rsquared, lifetime, slope.

# MathLINREG

Function to perform a simple linear regression (y = mx +b), returning slope, y-intercent,
correlation coefficient (R) and coefficient of determination (R²).

# Parameters

# Examples

MathLINREG([60,61,62,63,65], [3.1,3.6,3.8,4,4.1]);
// returns {
// 	"m": 0.188,    // slope
// 	"b": -7.964,   // y intercept
// 	"r": 0.912,    // correlation coefficient
// 	"r2": 0.832    // coefficient of determination
}

Returns object (opens new window) Linear regression results

# MathLN

Returns the natural logarithm (base E) of a number.

# Parameters

# Examples

MathLN(10);
// returns 2.302585092994046

Returns number (opens new window)

# MathLOG

Returns the logarithm (base 10) of a number.

# Parameters

# Examples

MathLOG(10);
// returns 1

Returns number (opens new window)

# MathMAX

Get the maximum value from an array of numbers. The function fails
if the array is empty or has invalid values.

# Parameters

# Examples

MathMAX([1,2,3,4.5]);
// returns 4.5

Returns number (opens new window)

# MathMEAN

Calculate the mean from an array of numbers. The function fails
if the array is empty or has invalid values.

# Parameters

# Examples

MathMEAN([1,2,3,4.5]);
// returns 2.625

Returns number (opens new window)

# MathMEDIAN

Calculate the median from an array of numbers. The function fails
if the array is empty or has invalid values.

# Parameters

# Examples

MathMEDIAN([1,2,3,4.5]);
// returns 2.5

Returns number (opens new window)

# MathMIN

Get the minimum value from an array of numbers. The function fails
if the array is empty or has invalid values.

# Parameters

# Examples

MathMIN([1,2,3,4.5]);
// returns 1

Returns number (opens new window)

# MathMULTREG

Multiple Linear Regression

# Parameters

# Examples

MathEXPINVREG( [ [ [x1,y1], [x2,y2], ..., [xn,yn] ], [ [x1,y1], [x2,y2], ..., [xn,yn] ] ] );
// returns
{
  "rsquared": rSq,
  "slopes": [slope1, ...],
  "points": [ [x1, x2, ..., xn], [y1, y2, ..., yn] ]
}

Returns object (opens new window) Returns rsquared, slopes and points.

# MathPOLYREG

Polynomial fit to y = a0 + a1x + a2x^2 + a3x^3....

# Parameters

# Examples

MathPOLYREG( [ [ [x1,y1], [x2,y2], ..., [xn,yn] ], [ [x1,y1], [x2,y2], ..., [xn,yn] ] ], degree );
// returns
{
  "points": points,
  "slopes": slopes,
  "error": yError
}

Returns object (opens new window) Returns points, slopes and error

# MathROUND

Calculate the variance from an array of numbers. The function fails if the array is empty or has invalid values.

# Parameters

# Examples

MathROUND(1.23456789, 5);
// returns 1.2346

Returns number (opens new window)

# MathSTDERR

Calculate the standard error from an array of numbers. The function fails if the array is empty or has invalid values.

# Parameters

# Examples

MathSTDERR([1,2,3,4.5]);
// returns 0.6465050270492876

Returns number (opens new window)

# MathSTDEV

Calculate the variance from an array of numbers. The function fails if the array is empty or has invalid values.

# Parameters

# Examples

MathSTDEV([1,2,3,4.5]);
// returns 1.2930100540985752

Returns number (opens new window)

# MathSTDEVS

Calculate the variance from an array of numbers. The function fails if the array is empty or has invalid values.

# Parameters

# Examples

MathSTDEVS([1,2,3,4.5]);
// returns 1.4930394055974097

Returns number (opens new window)

# MathSUM

Calculate the sum from an array of numbers. The function fails if the array is empty or has invalid values.

# Parameters

# Examples

MathSum([1,2,3,4.5]);
// returns 10.5

Returns number (opens new window)

# MathVARIANCE

Calculate the variance from an array of numbers. The function fails if the array is empty or has invalid values.

# Parameters

# Examples

MathVARIANCE([1,2,3,4.5]);
// returns 2.2292

Returns number (opens new window)

# NonLinearRegression

Function to perform a non-linear regression.

# Parameters

  • data object (opens new window) Data for the non-linear regression needs to be provided as an array of x,y pairs. [[x1,y1], [x2,y2], ..., [xn,yn]]
  • options object (opens new window)
    • options.equation (string (opens new window) | function (opens new window)) Select preset equation (string) or supply function
    • options.initial Array (opens new window)<number (opens new window)> Array with the initial guesses for parameters in equation [a, b, ..., h]
    • options.iterations number (opens new window) Number of iterations (maximum 2000) (optional, default 200)
    • options.cPts number (opens new window)? Number of datapoints
    • options.cVar number (opens new window) Number of independant variables
    • options.cPar number (opens new window) Number of parameters
    • options.RelaxF number (opens new window) Fractional adjustment factor (Values smaller than 1 will make the covergence slower but more stable) (optional, default 1.0)
    • options.SEy (1 | "Y" | "Sqrt(Y)" | "w" | "Rep") Standard Error associated with the Y variable (Equal 1, Relative Y, Counts Sqrt(Y), Data w, Replicates Rep (optional, default 1)
    • options.yTrans ("Y" | "LN(Y)" | "SQRT(Y)" | "1/Y") Transformation (optional, default "Y")
    • options.x1Trans ("X1" | "LN(X1)" | "SQRT(X1)" | "1/X1") Transformation (optional, default "X1")
    • options.x2Trans ("X2" | "LN(X2)" | "SQRT(X2)" | "1/X2") Transformation (optional, default "X2")
    • options.x3Trans ("X3" | "LN(X3)" | "SQRT(X3)" | "1/X3") Transformation (optional, default "X3")
    • options.x4Trans ("X4" | "LN(X4)" | "SQRT(X4)" | "1/X4") Transformation (optional, default "X4")
    • options.x5Trans ("X5" | "LN(X5)" | "SQRT(X5)" | "1/X5") Transformation (optional, default "X5")
    • options.x6Trans ("X6" | "LN(X6)" | "SQRT(X6)" | "1/X6") Transformation (optional, default "X6")
    • options.x7Trans ("X7" | "LN(X7)" | "SQRT(X7)" | "1/X7") Transformation (optional, default "X7")
    • options.x8Trans ("X8" | "LN(X8)" | "SQRT(X8)" | "1/X8") Transformation (optional, default "X8")
    • options.Centered boolean (opens new window) Centered Approximation to Partial Derivatives (optional, default false)
    • options.LeastAbs boolean (opens new window) Least-Absolute -Value curve fitting (optional, default false)
    • options.cPctile number (opens new window) Percentile (optional, default 50)

# Examples

NonLinearRegression(
 [
	  [x1, y1],
	  [x2, y2],
	  ...,
	  [xn, yn]
 ],
 {
	  equation: "b + a * e(- x / c)",
	  initial: [a, b, c]
 }
)


// Available equations
// "b + a * e(- x / c)"
// "( a - c ) * e( - b * t ) + c"
// "( c + a / ( 1 + b / x ) )"
// "( c + a * a / ( 1 + b / x ) )"


// returns
// {
//   text: <string>,
//   ParameterEstimates: <string>,
//   CovarianceMatrix: <string>,
//   r2: <number>
//   parameters: {
//     name: <string>,
//     value: <number>,
//     sd_error: <number>,
//     p: <number>
//   },
//   RMS_error: <number>,
//   presets: <object>,
//   iterations: <number>,
//   RMS_errors: <array>
// }

// Use a custom fitting function
// The function can contain the following parameters:
// x, t, a, b, c, .. h
// Not all parameters have to be defined and they can
// be in a random order. Use parameter names in alphabetical
// order (e.g. a and b, a and c without b will not work)
var decay = function(x,a,b,c){
return b + a * Math.exp( -x / c );
};

NonLinearRegression(
 [
	  [x1, y1],
	  [x2, y2],
	  ...,
	  [xn, yn]
 ],
 {
	  equation: decay,
	  initial: [a, b, c]
 }
)
// The returned object has the same structure as object in
// in the previous example.

Returns object (opens new window)

# TransformTrace

The function transforms a given array by providing a second same length array, or a single number.

# Parameters

# Examples

TransformTrace('subtract', [1, 2, 3, 4], [0, 1, 2, 1]);
// returns [1, 1, 1, 3]

TransformTrace('add', [1, 2, 3, 4], [0, 1, 2, 1]);
// returns [1, 3, 5, 5]

TransformTrace('add', [1, 2, 3, 4], 5);
// returns [6, 7, 8, 9]

TransformTrace('normToMin', [1.5, 2, 3, 4]);
// returns [1, 1.3333, 2, 2.6665]

TransformTrace('normToMax', [1.5, 2, 3, 4]);
// returns [0.375, 0.5, 0.75, 1]

TransformTrace('normToRange', [1.5, 2, 3, 4]);
// returns [0, 0.2, 0.6, 1]

TransformTrace('normToIdx', [1.5, 2, 3, 4], 1);
// returns [0.75, 1, 1.5, 2]

TransformTrace('normToVal', [1, 2, 3, 4], 2);
// returns [0.75, 1, 1.5, 2]

// Smoothing (ma= Moving average, sgf= Savitzky-Golay filter)

TransformTrace('ma', [1.5, 2, 3, 4]);
// returns [1.6667, 2.1665, 3, 3.6665]

TransformTrace('sgf', [1, 2, 3, 4]);
// returns [6, 7, 8, 9]

// Absorbance (abs) -log(I/I0)

// In case no value is provided, I0 is the fist value from the array
TransformTrace('abs', [1.5, 2, 3, 4]);
// returns [-0, -0.12494, -0.30103, -0.42597]

// The provided value is I0
TransformTrace('abs', [1.5, 2, 3, 4], 1);
// returns [-0.1761, -0.3010, -0.4771, -0.6021]

Returns (Array (opens new window)<number (opens new window)> | void) Transformed array or null

# warning

Add an Warning Message for the User.
Use these messages to indicate a potential issue and direct the user to check the measurement again.

# Parameters

# Examples

warning('Your Warning Message', output);
// output['messages']['warning']['Your Warning Message']

Returns object (opens new window) pushes the message into the output object.

← Overview →