Pack&Go API

From Version 13.0 onwards, Pack&Go now features an API that enables scientists to retrieve information about study participants, facilitating dynamic choices within the experiment flow. This API is available for MATLAB, Python, and LabMaestro experiments (version 11 and later).

Downloading and Using the API in your Experiment

To prepare your experiments, mock versions of the API can be downloaded.

With Matlab

When running a MATLAB experiment, the Pack&Go server has access to all API functions. As such, it is not necessary to pack the Pack&Go API with your experiment. Call the functions by their name, and they will be usable.

You can download the MATLAB mock API here.

With Python

If you wish to use the Pack&Go API when running a Python experiment, you must import the Pack&Go API as a library. You can do so with the line of code below;

PY

# Import Pack&Go API
import packngo_api.api as api;

API functions can then be called from the api object. You do not need to pack the API with your experiment, as the latest version is hosted on the Pack&Go servers.

You can download the PYTHON mock API package here.

With LabMaestro

When running a LabMaestro experiment, you can call the Pack&Go API from the remote object. API functions are available as properties of this object, following the syntax below:

CODE

=remote.functionName

Calling the Pack&Go API from LabMaestro (Ver. 1.11.0)

The API functions can also be used offline in LabMaestro; no additional setup is required.

End Experiment:

Description

Use this function to end the experiment with a defined exit code. This function enables alternative return paths based on various conditions within your experiments. For more information on alternate return paths, see this page.

Input

exitcode (String). The exit code returned to Pack&Go. If this exit code is tied to a return path, the participant will be redirected to this URL.

Syntax

Matlab

MATLAB

%% Using endexperiment for alternate return links; 
% showConsent and runExperiment are hyopthetical functions

% Show consent form to participant
consent = showConsent;

% Run or cancel experiment depending on consent
if consent;
  runExperiment;
else
  endexperiment("WithdrewConsent")
end

Python

PY

# Import Pack&Go API
import packngo_api.api as api;

# Using endexperiment for alternate return links; 
# showConsent and runExperiment are hyopthetical functions

# Show consent form to participant
consent = showConsent()

# Run or cancel experiment depending on consent
if (consent)
  runExperiment()
else
  api.end_experiment("WithdrewConsent")

Color Depth:

Description

Use this function to obtain the color depth of the participant’s monitor.

Output

result (Integer). The color depth of the participant’s monitor. If the server cannot be reached, the result will be equal to 0.

Syntax

Matlab

MATLAB

%% Get monitor color depth
colorDepth = getcolordepth;

Python

PY

# Import Pack&Go API
import packngo_api.api as api;

# Get monitor color depth
colorDepth = api.get_color_depth();

LabMaestro

MATLAB

%% Get monitor color depth
=remote.colordepth

Frames Dropped:

Description

Use this function to get the number of dropped frames from the beginning of the experiment.

Output

result (Integer). The number of dropped frames. If the server cannot be reached, the result will be equal to 0.

Syntax

Matlab

MATLAB

%% Get number of dropped frames
droppedFrames = getframesdropped;

Python

PY

# Import Pack&Go API
import packngo_api.api as api;

# Get number of dropped frames
droppedFrames = api.get_frames_dropped();

LabMaestro

MATLAB

%% Get number of dropped frames
=remote.framesdropped

Height (cm):

Description

Use this function to get the participant monitor’s height in centimeters.

Output

result (Real). The monitor height in centimeters. If the server cannot be reached, the result will be equal to 0.

Syntax

Matlab

MATLAB

%% Get monitor height (cm)
heightCM = getheightcm;

Python

PY

# Import Pack&Go API
import packngo_api.api as api;

# Get monitor height (cm)
heightCM = get_height_cm();

LabMaestro

MATLAB

%% Get monitor height (cm)
=remote.heightcm

Height (px):

Description

Use this function to get the participant monitor’s height in pixels.

Output

result (Real). The monitor width in pixels. If the server cannot be reached, the result will be equal to 0.

Syntax

Matlab

MATLAB

%% Get monitor height (px)
heightPX = getheightpx;

Python

PY

# Import Pack&Go API
import packngo_api.api as api;

# Get monitor height (px)
heightPX = api.get_heigth_px();

LabMaestro

MATLAB

%% Get monitor height (px)
=remote.widthpx

Last Frame Delay:

Description

Use this function to get the delay between the last two frames.

Output

result (Real). The frame delay in seconds. If the server cannot be reached, the result will be equal to 0.

Syntax

Matlab

MATLAB

%% Get frame delay
frameDelay = getframedelay;

Python

PY

# Import Pack&Go API
import packngo_api.api as api;

# Get frame delay
frameDelay = api.get_frame_delay();

LabMaestro

MATLAB

%% Get frame delay
=remote.lastframedelay

Network Latency:

Description

Use this function to get the current network latency for your participant. This function returns the latency at the precise moment the function is called.

Output

result (Real). The network latency in seconds. If the server cannot be reached, the result will be equal to 0.

Syntax

Matlab

MATLAB

%% Get network latency
latency = getnetworklatency;

Python

PY

# Import Pack&Go API
import packngo_api.api as api;

# Get network latency
latency = api.get_network_latency();

LabMaestro

MATLAB

%% Get network latency
=remote.networklatency

Orientation:

Description

Use this function to retrieve the orientation of the participant’s display, which can be either “Landscape” or “Portrait”.

Output

result (String). The display orientation. The returned values can either be “Landscape” or “Portrait”. If the server cannot be reached, the result will be equal to 0.

Syntax

Matlab

MATLAB

%% Get display orientation
orientation = getdisplayorientation;

Python

PY

# Import Pack&Go API
import packngo_api.api as api;

# Get display orientation
orientation = api.get_display_orientation();

Pixels per Inch (ppi):

Description

Use this function to get the number of pixels per inch of the participant’s display.

Output

result (Real). The number of pixels per inch. If the server cannot be reached, the result will be equal to 0.

Syntax

Matlab

MATLAB

%% Get number of pixels per inches
ppi = getppi;

Python

PY

# Import Pack&Go API
import packngo_api.api as api;

# Get number of pixels per inch
ppi = api.get_ppi();

LabMaestro

MATLAB

%% Get number of pixels per inches
=remote.ppi

Video Height (cm):

Description

Use this function to get the height of the Pack&Go experiment video feed on the participant’s monitor, in centimeters.

Output

result (Real). The height of the video feed, in centimeters. If the server cannot be reached, the result will be equal to 0.

Syntax

Matlab

MATLAB

%% Get video height
videoHeight = getvideoheightcm;

Python

PY

# Import Pack&Go API
import packngo_api.api as api;

# Get video height
videoHeight = api.get_video_height_cm();

LabMaestro

MATLAB

%% Get video height
=remote.videoheightcm

Video Width (cm):

Description

Use this function to get the width of the Pack&Go experiment video feed on the participant’s monitor, in centimeters.

Output

result (Real). The width of the video feed, in centimeters. If the server cannot be reached, the result will be equal to 0.

Syntax

Matlab

MATLAB

%% Get video width
videoWidth = getvideowidthcm;

Python

PY

# Import Pack&Go API
import packngo_api.api as api;

# Get video width
videoWidth = get_video_width_cm();

LabMaestro

MATLAB

%% Get video width
=remote.videowidthcm

Width (cm):

Description

Use this function to get the participant monitor’s width in centimeters.

Output

result (Real). The monitor width in centimeters. If the server cannot be reached, the result will be equal to 0.

Syntax

Matlab

MATLAB

%% Get monitor width (cm)
widthCM = getwidthcm;

Python

PY

# Import Pack&Go API
import packngo_api.api as api;

# Get monitor width (cm)
widthCM = api.get_width_cm();

LabMaestro

MATLAB

%% Get monitor width (cm)
=remote.widthcm

Width (px):

Description

Use this function to get the participant monitor’s width in pixels.

Output

result (Real). The monitor width in pixels. If the server cannot be reached, the result will be equal to 0.

Syntax

Matlab

MATLAB

%% Get monitor width (px)
widthPX = getwidthpx;

Python

PY

# Import Pack&Go API
import packngo_api.api as api;

# Get monitor width (px)
widthPX = api.get_width_px();

LabMaestro

MATLAB

%% Get monitor width (px)
=remote.widthpx

API Demo

The following code block demonstrates an experiment that runs for approximately 2 minutes, utilizing the API to retrieve information on the user’s display and network connection every second and print it to the console.

Matlab

MATLAB

%% Communicating with the Pack&Go API
timer = 0;
while timer < 120
    fprintf("Color depth: %f \n", getcolordepth);
    fprintf("Frame Dropped: %f \n", getframesdropped);
    fprintf("Height cm: %f \n", getheightcm);
    fprintf("Height px: %f \n", getheightpx);
    fprintf("Last frame delay: %f \n", getlastframedelay);
    fprintf("Network Latency: %f \n", getnetworklatency);
    fprintf("Orientation: %s \n", getorientation);
    fprintf("PPI: %f \n", getppi);
    fprintf("Video height cm: %f \n", getvideoheightcm);
    fprintf("Video width cm: %f \n", getvideowidthcm);
    fprintf("Width cm: %f \n", getwidthcm);
    fprintf("Width px: %f \n", getwidthpx);
    timer = timer+1;
    WaitSecs(1);
end
endexperiment("END");

Python

PY

# Calling the Pack&Go API in a Python experiment
import time
import packngo_api.api as api; # Import API functions
timer = 0
while (timer < 120):
    print("Color depth: %f \n" % api.get_color_depth())
    print("Frame Dropped: %f \n" % api.get_frames_dropped())
    print("Height cm: %f \n" % api.get_height_cm())
    print("Height px: %f \n" % api.get_height_px())
    print("Last frame delay: %f \n" % api.get_last_frame_delay())
    print("Network Latency: " + str(api.get_network_latency()) + "\n") # Returns NONE if no latency, otherwise returns an int. Converting output to string ensures no issues regardless of result.
    print("Orientation: %s \n" % api.get_orientation())
    print("PPI: %f \n" % api.get_ppi())
    print("Video height cm: %f \n" % api.get_video_height_cm())
    print("Video width cm: %f \n" % api.get_video_width_cm())
    print("Width cm: %f \n" % api.get_width_cm())
    print("Width px: %f \n" % api.get_width_px())
    timer = timer+1
    time.sleep(1)

api.end_experiment("END")