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.

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

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:

=remote.functionName

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

%% 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

# 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

%% Get monitor color depth
colorDepth = getcolordepth;

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

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

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

%% Get number of dropped frames
droppedFrames = getframesdropped;

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

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

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

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

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

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

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

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

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

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

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

%% Get frame delay
frameDelay = getframedelay;

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

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

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

%% Get network latency
latency = getnetworklatency;

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

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

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

%% Get display orientation
orientation = getdisplayorientation;

# 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

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

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

# Get number of pixels per inch
ppi = api.get_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

%% Get video height
videoHeight = getvideoheightcm;

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

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

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

%% Get video width
videoWidth = getvideowidthcm;

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

# Get video width
videoWidth = get_video_width_cm();

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

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

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

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

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

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

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

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

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.

%% 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");

# 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")