MATLAB API tool
Table of contents
- Overview
- Installation
- Authentication
- Loading data
- Filtering
- Sorting
- Including related records
- Creating records
- Updating records
- Troubleshooting
- Next Steps
Overview
The BrainSTEM MATLAB API tool (brainstem_matlab_api_tools
) provides a thin wrapper around the REST endpoints documented in the STEM API reference. This page mirrors the structure of those docs while expanding on hands-on usage. Every snippet below has been tested against the public API; replace placeholders (for example, IDs) with values available to your account.
Helper functions such as get_token
, load_model
, load_project
, load_session
, and save_model
streamline typical MATLAB workflows while mapping their arguments directly onto the underlying HTTP parameters.
Repository & tutorial: Source code and examples live in brainstem-org/brainstem_matlab_api_tools. The repository includes the
brainstem_api_tutorial.m
script that mirrors this guide with runnable sections.
Installation
Clone the MATLAB helper package and add it to your MATLAB path:
git clone https://github.com/brainstem-org/brainstem_matlab_api_tools.git
addpath(genpath('brainstem_matlab_api_tools'))
Authentication
Run get_token
once to create and store an authentication token. Subsequent API calls reuse the cached credentials.
get_token
Tokens expire periodically; re-run get_token
if you see HTTP 401 responses.
Loading data
load_model
mirrors the REST endpoints documented under STEM API. All arguments map directly onto their HTTP counterparts, and the helper infers the correct app
when you omit it.
sessions = load_model('model', 'session');
disp(numel(sessions.sessions))
Convenience wrappers include the correct app
and default include
lists for common models:
load_project
: includessessions
,subjects
,collections
,cohorts
load_subject
: includesprocedures
,subjectlogs
load_session
: includesdataacquisition
,behaviors
,manipulations
,epochs
They expose a small set of shorthand arguments (for example, name
, projects
, tags
) that expand into the appropriate filter entries internally.
project = load_project('name', 'Allen Institute: Visual Coding – Neuropixels');
subject = load_subject('name', 'Mouse');
session = load_session('name', 'Example Session');
Filtering
Filters accept cell arrays of key–value pairs. The modifier syntax (.icontains
, .iexact
, etc.) matches the API documentation.
filtered = load_model(
'model', 'project', ...
'filter', {'name.icontains', 'Allen'});
disp(numel(filtered.projects))
Multiple filter conditions can be specified as pairs in the same cell array:
filtered = load_model(
'model', 'session', ...
'filter', {'name.icontains', 'Rat', 'description.icontains', 'demo'});
The convenience functions also support multiple filter conditions through their shorthand parameters:
% Filter projects by name and tags
project = load_project('name', 'Allen', 'tags', '1');
% Filter subjects by name and sex
subject = load_subject('name', 'Mouse', 'sex', 'M');
Sorting
Pass a cell array of field names in sort
. Prefix with -
for descending order.
descending_sessions = load_model(
'model', 'session', ...
'sort', {'-start_time'});
Including related records
Request related models (for example, projects
, datastorage
, dataacquisition
) in a single call by supplying include
. Each entry automatically expands to <name>.*
, mirroring the REST include syntax.
with_related = load_model(
'model', 'session', ...
'include', {'projects', 'datastorage', 'dataacquisition'});
project_names = arrayfun(@(p) p.name, with_related.projects, 'UniformOutput', false);
Creating records
Use save_model
with the required fields from the STEM API reference. The example below assumes you have contributor access to the project ID provided. Note that tags
is a required field and can be set to an empty array if no tags are needed.
payload = struct();
payload.name = 'Example Session';
payload.description = 'Created via MATLAB API tool';
payload.projects = {'your-project-uuid'};
payload.tags = [];
created = save_model('model', 'session', 'data', payload);
session_id = created.session.id;
Updating records
Update existing records by placing the record ID inside the payload struct. save_model
detects the id
field, switches to PUT
, and replaces the stored record with the data you supply. Remember to include the tags
field even when updating.
update_data = struct(
'id', 'your-session-uuid', ...
'description', 'Updated via MATLAB API tool', ...
'tags', []);
updated = save_model(
'model', 'session', ...
'data', update_data);
Troubleshooting
- 401 Unauthorized: Regenerate your token with
get_token
. - 403 Forbidden: Check that your user or group has the required permissions listed in the STEM API documentation.
- 404 Not Found: Confirm the record exists in the selected portal (public/private).
- Validation errors (400): Ensure your payload matches the field definitions in the API reference. Remember that
tags
is a required field for sessions (can be an empty array). - Delete operations: The MATLAB helpers focus on read and write actions. Use the Python client or direct REST calls if you need to delete records.
The repository ships with brainstem_api_tutorial.m
, a tutorial script demonstrating common workflows.
Next Steps
- Complete Experimental Documentation: Review the Electrophysiology Workflow or Two-Photon Imaging Workflow tutorials to understand how API data access fits into complete experimental workflows
- Cross-Platform Integration: If you work in mixed programming environments, explore the Python API tool tutorial for complementary examples
- Data Management: Learn about Managing Data Storage to keep file locations synchronized with metadata returned by the API