Why do PhotosynQ measurements use Macros?

On PhotosynQ, Macros are used to make calculations after a measurement has been taken. Not every measurement requires post processing (e.g. a simple temperature measurement), but as soon as you want to compare parameters (e.g. ambient temperature vs. leaf temperature), you need a Macro to get results instantly.


How do Macros work

Macros are small snippets of code, which run calculations based on your measurements. They are written in the popular script language JavaScript.

Macros are connected to a Protocol. When you take a measurement, the protocol provides the instructions on how to take the measurement for the instrument (e.g. a MultispeQ). After the instrument has taken the measurement and send the data to the device, the connected Macro will make all the calculations, which then get shown on your device (e.g. your Phone).


Building your first Macro

In order to build your first Macro, make sure you have the Desktop App installed. Further you need a Protocol which output you want to analyze.
1. Take a measurement with your Protocol
2. Save the measurement to your Notebook
3. Select the Macros from the menu and click on + New
4. Select your measurement by searching your Notebook
5. Now you are ready to start coding…


Starting Coding

When you start, your editor already has some code in it, that looks somewhat like this:

//============================================
// Macro for data evaluation on PhotosynQ.org
// created: 11/3/2016
//============================================

//Define the output object here
var output = {};

//Check if the key time exists in json
if (json.time !== undefined){

    //Add key time and value to output
    output["time"] = json.time;
}

//Return data
return output;

Basic Rules:

  • The variable output is needed, as well as the return output statement at the end.
  • Add a new parameter to your Macro output using: output['New Parameter'] = "Hello World"
  • To access parameters from your Measurement use the Variables Menu. Variables selected will look like this: json.variable in the code.
  • Use the Raw Trace in the upper right corner to select a subsection of your trace if available.

Helper Functions
Some functions are needed over and over again, like calculating the average, finding the maximum, etc. Just pick the function you need from the functions menu and it will get inserted at the position of your cursor into your code.

// Calculate the mean from an array
var values = [1,2,3,4,5,6]
output['Mean'] = MathMEAN(values)

Saving your Macro

Select Save from the macro menu. Give the macro a unique title and a description and click on the save button.
To connect your Macro to the Protocol, navigate to the Protocol, edit it, save the Protocol and select your Macro from the dropdown menu.


Order Parameters

Sometimes you have multiple parameters calculated. To show the most important parameters first, select Order Parameters from the functions Menu. It will insert a piece of code like this:

output["order"] = ["P1","P3","P2"];

Just replace P1, P2, etc. with the names of the parameters you want to be ordered and appere on top of the list. Not all parameters need to be listed here.


Show additional Traces

The recorded trace json.data_raw will be shown with a measurement. In case you would like to show some extra traces based on your calculations, just add an array to your output parameters. This array need more than 10 values to be shown as a sparkline.

output["Additional Trace"] = [1,3,4,90,87,50,3,2,1,2,7,…];

Show Colors

Sometimes representing a value as a color is more usefull than a plain number. These three options are available:

  • Hexadecimal: #44bd78
  • RGB (Red, Green, Blue): rgb(68,189,120) (values from 0 to 255)
  • RGBA (Red, Green, Blue, alpha): rgba(68,189,120,0.5) (values from 0 to 255), (alpha 0 to 1)
output['Your Parameter'] = '#44bd78'
output['Your Parameter'] = 'rgb(68,189,120)'
output['Your Parameter'] = 'rgba(68,189,120,0.5)'

Return Feedback

If people take measurements in the field, they might run into quality issues, they cannot identify right away. Based on calculations you can add messages to alert users, that they might have to repeat the measurement. Three types of messages are available:

  • Info: Just let users know that (color:blue)
  • Warning: Give users a warning, that there might be something wrong and they should take a closer look (color: yellow)
  • Danger: Use this message, when you think something went terribly wrong. In the future, measurments containing this message will be flagged as bad datapoints automatically. (color:red)

To add messages, use the Functions menu and select the type of measurement you need. Replace the word message with your message.

info('message',output);
warning('message',output);
danger('message',output);

Basic Guidelines

  • Document your steps inside the code.
  • Test your code with more than one measurement.
  • Make sure that the code is fast and efficient.
  • Output only what is really necessary to not overwhelm others who will use your macro based analysis.

Try to make your code efficient, since can be used to evaluate several thousand measurements in a row.


Restrictions

Some of the functions available in JavaScript are not allowed to be used in macros. All functions that require a user response like alert, confirm and prompt are not allowed. Also defining new functions or overwriting existing functions function(){…} is forbidden, as well as extending the prototype library $.prototype.


You have more Questions?

Check out the forums.

For more PhotosynQ videos

Check out our Youtube Channel.