gtagora-connector-matlab is a Matlab library to access GyroTools' Agora system.
Clone the repository and add the cloned directory to Matlab path
server = '<AGORA SERVER>'
api_key = '<YOUR_API_KEY>'
agora = Agora.create(server, api_key);
myagora_project = agora.get_myagora();
root_folder = myagora_project.get_root_folder();
subfolders = root_folder.get_folders();
for i = 1:length(subfolders)
disp([' - ', subfolders(i).name]);
end
new_folder = root_folder.get_or_create('New Folder');
exams = myagora_project.get_exams();
if ~isempty(exams)
exam = exams(1);
series = exam.get_series();
for i = 1:length(series)
disp(['Series: ', series(i).name]);
datasets = series(i).get_datasets();
for j = 1:length(datasets)
disp([' Dataset: ', datasets(j).name]);
datafiles = datasets(j).get_datafiles();
for k = 1:length(datafiles)
disp([' ', datafiles(k).original_filename]);
end
end
end
end
root_folder.upload('/path/to/directory/or/file');agora = Agora.create('https://your.agora.domain.com', '<YOUR_API_KEY>')The API key can be activated in your Agora profile, and is a random UUID which can be withdrawn or recreated easily.
Get a list of projects:
projects = agora.get_projects();
for i = 1:length(projects)
disp(projects(i).name);
endGet a project by ID:
project = agora.get_project(2);
disp(project.name);Get a project by name:
project = agora.get_project('test_project');Get the "My Agora" project:
myagora = agora.get_myagora();Get root folder of a project
project = agora.get_project(2);
root_folder = project.get_root_folder();Get all exams of a project
project = agora.get_project(2);
exams = project.get_exams();Get the members of a project
members = project.get_members();Add a new member to the project
users = agora.get_users();
project.add_member(users(1), 'scientist');Search within a project
project.search('test');Search only for a specific type (datasets in this case)
project.search('test', 'dataset');Empty the trash
project = agora.get_project(2);
project.empty_trash();Get the root folder of the "My Agora" project:
myagora = agora.get_myagora();
root_folder = myagora.get_root_folder();Get a folder by its ID
folder = agora.get_folder(45);Get sub folders
subfolders = folder.get_folders();
for i = 1:length(subfolders)
disp([' - ', subfolders(i).name]);
endGet a subfolder folder by name. None will be returned if the folder does not exist
my_folder = folder.get_folder('my_folder')The get_folder function also takes a relative path.
my_subfolder = folder.get_folder('my_folder/my_subfolder')Create a new folder in the root folder (the new folder object is returned). An exception is thrown if a folder with the same name already exists.
new_folder = root_folder.create('TestFolder');Get a folder or create a new one if it does not exist
new_or_existing_folder = root_folder.get_or_create('TestFolder');Delete a folder. Delete a folder is recursive. It deletes all items. The delete operation does not follow links.
folder.remove()Get all items of a folder. An item could for example be an exam, series or dataset. Please note that the returned items are sorted by their database id.
items = folder.get_items();
for i = 1:length(items)
disp(items(i).content_object.name)
endGet an exam by ID
exam = agora.get_exam(12);Get all series of an exam and then all datasets of the first series
series = exam.get_series();
datasets = series(1).get_datasets();Get all datasets of an exam
datasets = exam.get_datasets();Get a series or dataset by ID
series = agora.get_series(76);
dataset = agora.get_dataset(158);Get the parents of an object
% get parents of a dataset
series = dataset.get_series(); % get series
exam = dataset.get_exam(); % get exam
patient = dataset.get_patient(); % get patient
folders = dataset.get_folders(); % get the folders which contain the dataset
% get parents of a series
exam = series.get_exam(); % get exam
patient = series.get_patient(); % get patient
folders = series.get_folders(); % get the folders which contain the series
% get parents of an series
exam = agora.get_exam(exam_id);
patient = exam.get_patient(); % get patient
folders = exam.get_folders(); % get the folders which contain the seriesFilters can be used to retrieve objects that meet a certain criteria. They can be applied to different object types such as projects, exams, datasets, and series.
In order to filter objects we pass one or more filter classes to the get functions as argument (e.g. get_exams). Every filter class has a value attribute which specifies the criteria to be filtered for and an operator which specifies the filter operation, such as contains, startswith etc.
You can get all the available filters for an object with:
exam_filter_set = agora.get_exam_filters() % filters for exam
series_filter_set = agora.get_series_filters() % filters for series
dataset_filter_set = agora.get_dataset_filters() % filters for datasetThis returns a map where the key is the field name which is filtered and the value is the filter class. You can get the filter for a specific field with:
name_filter = exam_filter_set.get_filter('name'); % gets the filter which filters for the exam nameAfterwards you can set a filter operator according to your needs:
name_filter.operator = 'startswith';To display a list of all operators call:
disp(name_filter.operators)Finally set a filter value and get the objects meeting the filter critera. In this case we would get all studies of a project whose name start with "Study"
name_filter.value = 'Study';
project.get_exams(name_filter);Examples:
% get all exams of a project which start with "study" (case insensitive)
project = agora.get_project(project_id); % get the project
exam_filter_set = agora.get_exam_filters() % get the exam filters
name_filter = exam_filter_set.get_filter('name'); % get the filter for the exam name
name_filter.operator = 'istartswith'; % set the operator
name_filter.value = 'study'; % filter for "study"
project.get_exams(name_filter); % get the filtered exams
% get all Philips raw datasets of an exam which have "FFE" in the name
exam = agora.get_exam(exam_id); % get an exam
types = agora.get_dataset_types(); % get the dataset types
dataset_filter_set = agora.get_dataset_filters() % get all filters for the dataset
type_filter = dataset_filter_set.get_filter('type'); % get the filter for the dataset type
type_filter.value = types.PHILIPS_RAW; % specify to filter for Philips raw files
name_filter = dataset_filter_set.get_filter('name'); % get the filter for the dataset name
name_filter.operator = 'icontains'; % specify the operator
name_filter.value = 'ffe'; % filter for "ffe"
filters(1) = type_filter; % put both filters in an array
filters(2) = name_filter;
datasets = exam.get_datasets(filters); % get the filtered datasets
% get all series of an exam which have "FFE" in the name
series_filter_set = agora.get_series_filters() % get all filters for a series
name_filter = series_filter_set.get_filter('name'); % get the filter for the series name
name_filter.value = 'ffe'; % filter for "ffe" in name
exam.get_series(name_filter); % get the filtered series Get all tags the current user has access to:
tags = agora.get_tags();Get a tag by id or name:
tag1 = agora.get_tag(3);
tag2 = agora.get_tag('good');Tag an agora object:
exam = agora.get_exam(12);
series = agora.get_series(24);
dataset = agora.get_dataset(145);
folder = agora.get_folder(15);
tag_instance1 = exam.tag(tag1);
tag_instance2 = series.tag(tag1);
tag_instance3 = dataset.tag(tag1);
tag_instance4 = folder.tag(tag1);Get all objects for a specific tag:
% get tags for a project
project_id = 3;
project = agora.get_project(project_id);
tags = project.get_tags();
% get exams, series, datasets, patients for a tag
tag = tags(1);
exams = project.get_exams_for_tag(tag);
series = project.get_series_for_tag(tag);
datasets = project.get_datasets_for_tag(tag);
patients = project.get_patients_for_tag(tag);Download all data from a folder
target = '/data/downloads';
downloaded_files = folder.download(target);Exams, series and datasets also have a download function
downloaded_files = exam.download(target);
downloaded_files = series.download(target);
downloaded_files = dataset.download(target);By default, the data from each Study, Series, Dataset, etc., is downloaded to its own subfolder. However, it is possible to disable this behavior and download everything into a single flat folder by using the 'flat' option:
downloaded_files = series.download(target, 'flat', true);The download can be further customized by filtering the datasets based on their type or by using a regular expression to match the filenames:
% filtered by dataset types
t = agora.get_dataset_types();
downloaded_files = series.download(target, 'dataset_types', [t.PHILIPS_RAW, t.PHILIPS_SINFILE]);
% filtered by regex (downloads all files with extension .log)
downloaded_files = series.download(target, 'regex', '\.log');Upload a file or directory into a folder
folder = agora.get_folder(45);
dir = '/data/images/';
file = '/data/logfile.txt';
folder.upload(dir);
folder.upload(file);The advanced upload functionality creates an upload session for transferring files to Agora. It tracks the upload process, enables the users to resume an interrupted upload and ensures data integrity.
To create an upload session use the following syntax:
files = {'C:/data/raw/rawfile.raw', 'C:/data/raw/rawfile.lab', 'C:/data/log/logfile.txt'};
progress_file = 'C:/data/progress.json';
target_folder_id = 45;
session = agora.create_upload_session(files, target_folder_id, progress_file);After creating the session start the upload with:
session.start()If an upload was interrupted or stopped, the session can be recreated and resumed using the progress_file:
session = agora.create_upload_session(progress_file)
session.start()Furthermore, the advanced upload will verify the data integrity of the uploaded files by comparing file hashes. It also waits for the data import to finish before returning and checks if all uploaded files are imported successfully.
Get all tasks of a project:
project = agora.get_myagora();
tasks = project.get_tasks();Get a task by ID or name
task = project.get_task(4);
task = project.get_task('my_task');Run a task:
In this example the task has 2 inputs:
- A dataset with key "ds"
- An integer number with key "size"
The last line in the code sample waits for the task to finish
project = agora.get_myagora();
task = project.get_task('my_task');
target_folder = agora.get_folder(24)
dataset = agora.get_dataset(57)
timeline = task.run(target_folder, 'ds', dataset, 'size', 13);
timeline.join()Search in the entire Agora
results = agora.search('test');Search only for a certain type (studies in this case)
results = agora.search('test', 'study');Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.