Metrics

Metrics are global variables you can read/write in your Python logic code. They can also be added to the runtime interface for visual display, logged at certain time points in the trial, and plotted.

A metric can be any python object. This is similar to using the global keyword in Python, except that by storing it as a Pynapse asset you can use the methods below to read and modify it, and all of the logging and display/plotting is taken care of for you.

Give each variable a name and a default value in the Metrics Tab. If Session Controls are enabled, you can assign a metric to trials, blocks, or sessions. You can add up to 50 metrics.

Metrics Tab

Option	Description
Reset*	Reset the metric to 0 after the session event
Log	Determine if and when to log the metric, if User Log File is enabled in the General Tab. See Metric Logging for more information.
Ledger	Show string representation in the runtime UI, if Run-time Ledger Window is enabled. See Ledger below.
Broadcast	Include the metric in the broadcast UDP packet, if UDP Broadcast is enabled on the General Tab. See UDP for more information.
Plotting	Choose the plot shape and color, if Run-time Plot Window is enabled. All metrics in the same scope are plotted together. See Plotting below.

Important

*The metric resets 'on Trial Begin' after the function that calls startTrial exits. In the example below, the MinPress metric will be 0 after s_State_enter finishes and won't have the desired value. When manually setting metrics, turn off the 'Reset' option.

class StartTrial:    # StateID = ?
    def s_State_enter():
        p_Session.startTrial()
        p_Metric.MinPress.write(random.randint(5,10))

Run-time Interface

The Metrics run-time interface can have two elements, the ledger and plot windows. Metrics are organized by scope - Session, Block, Trial, or Global.

Ledger

Metrics Ledger Option

Metrics with the Ledger option selected appear on the ledger. The numbers on the ledger indicate the {SESSION}.{BLOCK}.{TRIAL} for that entry. New blocks / trials are indicated with a -. The Run-time Ledger Window setting organizes the metric panes either vertically or horizontally by default. The layout can be changed at run-time.

Metrics Ledger Interface

Button	Description
	Organize metrics into columns
	Organize metrics into rows
	Organize metric panes horizontally
	Organize metric panes vertically
	Stop metrics from updating, for review
	Resume updating metrics
	Show all Session, Block, and Trial metrics in the Global list as well. There must be at least one Global metric in the ledger to see this button

Plotting

Metrics Plot Option

Enable Run-time Plot Window and choose the plot shape and color. Metrics are organized in the plots by their scope. Darker gray vertical bars represent new sessions. Lighter gray vertical bars represent new blocks.

If you have multiple metrics in the same scope and need two axes to represent the data in a meaningful way, use the Y-axis Left/Right setting to plot metrics on two different axes on the same plot. Each metric has an option to choose which of the two axes to use.

Metrics Plot Interface

Button	Description
	Organize plot panes horizontally, with Global at the bottom
	Organize plot panes vertically
	Stop plots from updating, for review
	Resume updating plots

Adjusting the plots

Hover near the axis you want to change and use the mouse to change the zoom and scale. The mouse cursor will change to a vertical or horizontal axis with a finger pointed in the direction of the axis as you get near.

Left-click and drag to change the axis offset. Hold CTRL + left-click and drag, or move the mouse wheel, to change axis zoom. Here is the full list of cursors and actions:

Cursor	Mouse Action	Description
	None	Bottom axis is currently targeted
	Left-click + drag	Change bottom axis offset
	CTRL + left-click + drag, or mouse wheel	Zoom bottom axis
	None	Left axis is currently targeted
	Left-click + drag	Change left axis offset
	CTRL + left-click + drag, or mouse wheel	Zoom left axis
	None	Right axis is currently targeted
	Left-click + drag	Change right axis offset
	CTRL + left-click + drag, or mouse wheel	Zoom right axis

Methods

All metric methods have the form p_Metric.{METRIC_NAME}.{METHOD}. Type p_ in the Pynapse Code Editor and let the code completion do the work for you.

Status

read

value = p_Metric.varname.read()

Read the current value of a metric variable.

Control

write

p_Metric.varname.write(value)

Write a new value to the metric variable. This can be any python object.

Inputs	Type	Description
value	python object	New value assigned to global variable

inc

p_Metric.varname.inc(delta=1)

Increment the metric value by delta (default is 1).

Inputs	Type	Description
delta	number	Amount to increase variable value (default=1)

dec

p_Metric.varname.dec(delta=1)

Decrement the metric value by delta (default is 1).

Inputs	Type	Description
delta	number	Amount to decrease variable value (default=1)

scale

p_Metric.varname.scale(sf)

Scales the metric value by sf.

Inputs	Type	Description
sf	number	Amount to scale variable value

round

p_Metric.varname.round(ndec)

Rounds the metric to ndec decimal places.

Inputs	Type	Description
ndec	integer	Decimal places

Data Conversion

toFloat

p_Metric.varname.toFloat()

Convert the metric value to a floating point number for math operations

toInt

p_Metric.varname.toInt()

Convert the metric value to an integer number for math operations

toString

p_Metric.varname.toFloat()

Convert the metric value to a string.

toPretty

p_Metric.varname.toPretty()

Convert the metric value to a string containing its name and value. Useful for displaying to the console

Example

p_Metric.varname.write(1)

# prints 'varname=1'
print(p_Metric.varname.toPretty())