gtagora-connector 0.1.1

The Agora Connector for Python

gtagora-connector

gtagora-connector is a python library to access GyroTools' Agora system.

Installation

Use the package manager pip to install gtagora-connector.

pip install gtagora-connector

Currently gtagora-connector supports python 3.6 and 3.7.

Basic usage

from gtagora import Agora
from gtagora.models.dataset import DatasetType

server = '<AGORA SERVER>'
api_key = '<YOUR_API_KEY>'

agora = Agora.create(server, api_key)

root_folder = agora.get_root_folder()
subfolders = root_folder.get_folders()
for s in subfolders:
    print(f' - {s.name}')

new_folder = root_folder.get_or_create('New Folder')

exams = agora.get_exam_list(filters={'name': 'Wrist'})
if exams:
    exam = exams[0]
    for s in exam.get_series():
        print(f'Series: {s.name}')

        for dataset in s.get_datasets(filters={'type': DatasetType.PHILIPS_RAW}):
            for datafile in dataset.get_datafiles():
                print(f'{datafile.original_filename}')

agora.import_data('/path/to/directroy', new_folder)

Examples

Create an Agora instance

from gtagora import Agora

agora = Agora.create('https://your.agora.domain.com', user='test', password='test')

Since, it is not recommended to ever write down your password in plain text, Agora offers the possibility to connect with an API key. The API key can be activated in your Agora profile, and is a random UUID which can be withdrawn or recreated easily.

from gtagora import Agora

agora = Agora.create('https://your.agora.domain.com', api_key='<YOUR_API_KEY>')

Working with folders

Get the root folder of the current user:

root_folder = agora.get_root_folder()
print(f"Root folder ID: {root_folder.id}")

Get a folder by its ID

folder = agora.get_folder(45)
print(f"Folder with ID {folder.name}")

Get sub folders

subfolders = folder.get_folders()
for f in subfolders:
    print(f" - {f.name}")

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_folder('TestFolder')
print(f"New folder ID: {new_folder.id}")

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.delete()

Get all items of a folder. An item could for example be an exam, series or dataset

items = folder.get_items()
for item in items:
    print(f" - {item}")

Get all exams of a folder. Use the recursive parameter to also get the exams in all subfolders

exams = folder.get_exams(recursive=False)
for exam in exams:
    print(f" - {exam}")

Get the path of a folder within Agora (breadcrumb)

folder = agora.get_folder(45)
breadcrumb = folder.get_breadcrumb()

Working with Agora objects

Get the list of exams

exams = agora.get_exam_list()

Get an exam by ID

exam = agora.get_exam(12)

Link the first Exam to the a folder

exam_item = exam.link_to_folder(folder.id)

Delete the link of an exam (doesn't delete the Exam itself)

exam_item.delete()

Get all series of an exam and then all datasets of the first series

series = exam.get_series()
datasets = series[0].get_datasets()

Get all datasets of an exam

series = exam.get_datasets()

Get a list of all patients

patients = agora.get_patients()

Get a patient by ID

patient = agora.get_patient(15)

Get a series or dataset by ID

series = agora.get_series(76)
dataset = agora.get_dataset(158)

Download data

Download all data from a folder

from pathlib import Path

target = Path("c:/temp")
downloaded_files = folder.download(target, recursive=False)
for f in downloaded_files:
    print(str(f))

Exams, series and datasets also have a download function

downloaded_files = exam.download(target)
downloaded_files = series.download(target)
downloaded_files = dataset.download(target)

Import data

Upload files into a folder

from pathlib import Path

folder = agora.get_folder(45)
file1 = Path('C:/images/test1.jpg')
file2 = Path('C:/images/test2.jpg')
folder.upload([file1, file2])

Upload a whole folder structure

from pathlib import Path

folder = agora.get_folder(45)
data = Path('C:/data/my_folder')
folder.upload([data])

Working with tasks

Get all tasks visible to the current user:

tasks = agora.get_tasks()

Get a task by ID

task = agora.get_task(13)

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

task = agora.get_task(13)
target_folder = agora.get_folder(24)
dataset = agora.get_dataset(57)
taskinfo = task.run{'ds': dataset, 'size': 1024}, target_folder)
taskinfo.join()

Save a task after it has been modified

task = agora.get_task(13)
task.name = 'new_name'
task.save()

Delete a task

task.delete()

Export all tasks into a json file

agora.export_tasks('<output file>.json')

Import tasks from file (Experimental!)

agora.import_tasks('<input file>.json')

Working with parameters

Get a parameter by name

dataset = agora.get_dataset(13)
parameter = dataset.get_parameter('EX_ACQ_echoes')
if not parameter.is_array:
    value = parameter.values[0]
else:
    value = parameter.values

Search for parameters

dataset = agora.get_dataset(13)
parameters = dataset.search_parameter('EX_ACQ_')
print(f'{len(parameters)} parameters found')

Users and sharing

Get the current user

current_user = agora.get_current_user()

Get all users

users = agora.get_users()

Get all user groups

users = agora.get_groups()

Share a folder with a user

from gtagora.models.share import ShareLevel

users = agora.get_users()
folder = agora.get_folder(2417)
response = folder.share(users[0].id, None, ShareLevel.ORGANIZE)

Various

Empty the trash

agora.empty_trash()

Contributing

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.

License

MIT