brainstem_api_tutorial.m

% BrainSTEM MATLAB API Tutorial
%
% This script demonstrates the recommended workflows using BrainstemClient.
% The client authenticates once and reuses the token for all subsequent calls.
%
% AUTHENTICATION OPTIONS (choose one):
%
%   Option A - Personal Access Token (recommended for scripts / HPC / automation):
%     Create your token at https://www.brainstem.org/private/users/tokens/
%     Set it as an environment variable once per MATLAB session (the same variable
%     the Python client, brainstem-nwb and the agent skills read):
%       setenv('BRAINSTEM_API_TOKEN','<your_token>')
%       client = BrainstemClient()       % picks it up automatically
%     Or pass it directly:
%       client = BrainstemClient('token','<your_token>');
%
%   Option B - Interactive login (device flow, desktop MATLAB only):
%       client = BrainstemClient();    % opens browser for login

client = BrainstemClient();

%% 1. Loading sessions
%  Preferred: use named client methods (tab-completable, credentials automatic)

% Load sessions using the convenience method (sideloads data acquisitions, behaviors,
% manipulations and epochs by default)
output1 = client.load_session();
session = output1.sessions(1);

% Load ALL sessions across all pages automatically
output1_all = client.load_session('load_all', true);

% Filter by name
output1_1 = client.load_session('name', 'Peters session 2');

% Sort descending by name
output1_2 = client.load_session('sort', {'-name'});

% Fetch a single session by UUID
output1_id = client.load('session', 'id', '<session_uuid>');

% Combine filter + sort + include via the generic load method
output1_6 = client.load('session', ...
    'filter',  {'name.icontains', 'Rat'}, ...
    'sort',    {'-name'}, ...
    'include', {'projects'});

%% 2. Updating a session (partial update — only send changed fields)

session = output1.sessions(1);
patch_data.id          = session.id;
patch_data.description = 'updated description';
output2 = client.save(patch_data, 'session', 'method', 'patch');

% Full replace (PUT) is still available:
% session.description = 'new description';
% session.tags = [];   % tags is required by the API
% output2_put = client.save(session, 'session');

%% 3. Creating a new session

new_session.name        = 'New session 1236567576';
new_session.description = 'new session description';
new_session.projects    = {'<project_uuid>'};
new_session.tags        = [];
output3 = client.save(new_session, 'session');

%% 4. Deleting a record

% output_del = client.delete(output3.id, 'session');

%% 5. Load public projects

output4 = client.load('project', 'portal', 'public');

%% 6. Convenience methods on the client (recommended)
%
% These are the preferred entry points — named, tab-completable, and
% automatically use the client's credentials.

output5_1 = client.load_project('name', 'Peters NYU demo project');
output5_2 = client.load_subject('name', 'Peters subject 2');
output5_3 = client.load_session('name', 'mysession');
output5_4 = client.load_behavior('session', '<session_uuid>');
output5_5 = client.load_dataacquisition('session', '<session_uuid>');
output5_6 = client.load_manipulation('session', '<session_uuid>');
output5_7  = client.load_procedure('subject', '<subject_uuid>');
output5_8  = client.load_collection('name', 'My Collection');
output5_9  = client.load_cohort('name', 'My Cohort');
output5_10 = client.load_subjectlog('subject', '<subject_uuid>');
output5_11 = client.load_procedurelog('procedure', '<procedure_uuid>');
output5_12 = client.load_equipment('setup', '<setup_uuid>');
output5_13 = client.load_consumablestock('inventory', '<inventory_uuid>');

% The package functions are also available directly when you need them:
output5_pkg = brainstem.load_session('name', 'mysession');

%% 7. Using load directly (for models without a convenience method)

% Get all subjects with related procedures
output_subjects = client.load_subject('include', {'procedures'});

% Get all projects with related subjects and sessions
output_projects = client.load_project('include', {'sessions','subjects'});

% Get consumable resources (no convenience loader — use load directly)
output_consumables = client.load('consumable', 'app', 'resources');

% Paginate manually: the API pages with page/per_page. limit is the page size
% (default 100, maximum 500) and offset must be a multiple of it.
output_page1 = client.load_session('limit', 50);                 % page 1
output_page2 = client.load_session('limit', 50, 'offset', 50);   % page 2
fprintf('page %d of %d\n', output_page2.meta.page, output_page2.meta.total_pages);

% Specimen-era models load like any other model (needs a server with the specimen release)
% output_specimens = client.load('specimenset', 'filter', {'projects', '<project_uuid>'}, 'load_all', true);

% Lists read with include hold only the related records you may read. Reload a record
% without include before changing a list field such as projects or behaviors:
% s = client.load('session', 'id', '<session_uuid>'); s = s.session;
% s.projects{end+1} = '<project_uuid>';
% client.save(struct('id', s.id, 'projects', {s.projects}), 'session', 'method', 'patch');

%% 8. Public data without logging in

% An anonymous client sends no token; only the public portal works with it.
public_client = BrainstemClient('anonymous', true);
public_projects = public_client.load('project', 'portal', 'public', 'load_all', true);

%% 9. Exporting a project or a session

% One JSON document (format 2.x) with every record of the project or session you may
% read. 'file' keeps the original JSON (with '.gz' it is compressed) for brainstem-nwb
% and other tools; the returned struct has jsondecode's sanitized field names.
% export = client.export_project('<project_uuid>', 'file', 'project-export.json.gz');
% fprintf('%d records\n', export.export_info.record_count);
% Large projects: 'background', true queues a server job and waits for it.
% session_export = client.export_session('<session_uuid>', 'background', true);

%% 10. The agent reference

% The server describes its own API and data model in Markdown pages, readable
% without a token.
disp(client.agent_reference('index.md'));
% disp(client.agent_reference('resources/session.md'));