Package: gtagora-connector
gtagora-connectorgtagora-connector is a python library to access GyroTools' Agora system.InstallationUse the package managerpipto install gtagora-connector.pipinstallgtagora-connectorCurrently gtagora-connector supports python 3.6 and 3.7.Basic usagefromgtagoraimportAgorafromgtagora.models.datasetimportDatasetTypeserver='<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()forsinsubfolders:print(f' -{s.name}')new_folder=root_folder.get_or_create('New Folder')exams=myagora_project.get_exams(filters={'name':'Wrist'})ifexams:exam=exams[0]forsinexam.get_series():print(f'Series:{s.name}')fordatasetins.get_datasets(filters={'type':DatasetType.PHILIPS_RAW}):fordatafileindataset.get_datafiles():print(f'{datafile.original_filename}')agora.import_data('/path/to/directroy',new_folder)ExamplesCreate an Agora instancefromgtagoraimportAgoraagora=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.fromgtagoraimportAgoraagora=Agora.create('https://your.agora.domain.com',api_key='<YOUR_API_KEY>')Working with projectsGet a list of projects:projects=agora.get_projects()forpinprojects:print(f" -{p.display_name}")Get a project by ID:project=agora.get_project(2)print(f" -{project.display_name}")Get the "My Agora" project:myagora=agora.get_myagora()Get root folder of a projectproject=agora.get_project(2)root_folder=project.get_root_folder()Get all exams of a projectproject=agora.get_project(2)exams=project.get_exams()Empty the trashproject=agora.get_project(2)project.empty_trash()Working with foldersGet the root folder of the "My Agora" project:myagora=agora.get_myagora()root_folder=myagora.get_root_folder()print(f"Root folder ID:{root_folder.id}")Get a folder by its IDfolder=agora.get_folder(45)print(f"Folder with ID{folder.name}")Get sub folderssubfolders=folder.get_folders()forfinsubfolders:print(f" -{f.name}")Get a subfolder folder by name. None will be returned if the folder does not existmy_folder=folder.get_folder('my_folder')The get_folder function also takes a relative path.my_folder=folder.get_folder('../../data/my_folder')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 existnew_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 datasetitems=folder.get_items()foriteminitems:print(f" -{item}")Get all exams of a folder. Use the recursive parameter to also get the exams in all subfoldersexams=folder.get_exams(recursive=False)forexaminexams:print(f" -{exam}")Get all datasets of a folder. Use the recursive parameter to also get the exams in all subfoldersdatasets=folder.get_datasets(recursive=False)Get a dataset by name. None is returned if the dataset does not existdataset=folder.get_dataset('my_dataset')Get the path of a folder within Agora (breadcrumb)folder=agora.get_folder(45)breadcrumb=folder.get_breadcrumb()Working with Agora objectsGet the list of examsexams=agora.get_exam_list()Get an exam by IDexam=agora.get_exam(12)Link the first Exam to the a folderexam_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 seriesseries=exam.get_series()datasets=series[0].get_datasets()Get all datasets of an examseries=exam.get_datasets()Get a list of all patientspatients=agora.get_patients()Get a patient by IDpatient=agora.get_patient(15)Get a series or dataset by IDseries=agora.get_series(76)dataset=agora.get_dataset(158)Tag ObjectsGet all tags the current user has access to:tags=agora.get_tags()Get a tag by id or name:tag1=agora.get_tag(id=3)tag2=agora.get_tag(name='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)patient=agora.get_patient(2)tag_instance1=exam.tag(tag1)tag_instance2=series.tag(tag1)tag_instance3=dataset.tag(tag1)tag_instance4=folder.tag(tag1)tag_instance5=patient.tag(tag1)Download dataDownload all data from a folderfrompathlibimportPathtarget=Path("c:/temp")downloaded_files=folder.download(target,recursive=False)forfindownloaded_files:print(str(f))Exams, series and datasets also have a download functiondownloaded_files=exam.download(target)downloaded_files=series.download(target)downloaded_files=dataset.download(target)Import dataUpload files into a folderfrompathlibimportPathfolder=agora.get_folder(45)file1=Path('C:/images/test1.jpg')file2=Path('C:/images/test2.jpg')folder.upload([file1,file2])Upload a whole folder structurefrompathlibimportPathfolder=agora.get_folder(45)data=Path('C:/data/my_folder')folder.upload([data])Upload (and import) a rawfile and add an additional file to the the created series (Agora version > 6.3.0):In this example a scanner rawfile and a textfile is uploaded. The rawfile will be imported into Agora and a Study and Series
will be created. We can add the additional text file to the created Series by specifying the "relations" attribute in the
upload function. The "relations" attribute is a dictionary whose key is the path to the rawfile and the value is a list
of additional files which will be added to the created series:folder=agora.get_folder(45)files=[Path('C:/data/raw/rawfile.raw'),Path('C:/data/raw/rawfile.lab'),Path('C:/data/log/logfile.txt'),]relations={'C:/data/raw/rawfile.raw':['C:/data/log/logfile.txt']}folder.upload(files,relations=relations)This also works when uploading a whole directory:folder=agora.get_folder(45)dir=[Path('C:/data/')]relations={'C:/data/raw/rawfile.raw':['C:/data/log/logfile.txt']}folder.upload(dir,relations=relations)Advanced UploadThe 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=[Path('C:/data/raw/rawfile.raw'),Path('C:/data/raw/rawfile.lab'),Path('C:/data/log/logfile.txt')]progress_file=Path('C:/data/progress.json')session=agora.create_upload_session(files,progress_file=progress_file,target_folder_id=45,verbose=True)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:progress_file=Path('C:/data/progress.json')session=agora.create_upload_session(progress_file=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.Working with tasksGet all tasks visible to the current user:tasks=agora.get_tasks()Get a task by IDtask=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 finishtask=agora.get_task(13)target_folder=agora.get_folder(24)dataset=agora.get_dataset(57)taskinfo=task.run(target=target_folder,ds=dataset,size=1024)taskinfo.join()alternatively only the ID's of the Agora objects can be given as argument:taskinfo=task.run(target=target_folder,ds=23,size=1024)the syntax to run the task can be printed to the console with the syntax function:task.syntax()Save a task after it has been modifiedtask=agora.get_task(13)task.name='new_name'task.save()Delete a tasktask.delete()Export all tasks into a json fileagora.export_tasks('<output file>.json')Import tasks from file (Experimental!)agora.import_tasks('<input file>.json')Working with parametersGet a parameter by namedataset=agora.get_dataset(13)parameter=dataset.get_parameter('EX_ACQ_echoes')ifnotparameter.is_array:value=parameter.values[0]else:value=parameter.valuesSearch for parametersdataset=agora.get_dataset(13)parameters=dataset.search_parameter('EX_ACQ_')print(f'{len(parameters)}parameters found')Users and sharingGet the current usercurrent_user=agora.get_current_user()Get all usersusers=agora.get_users()Get all user groupsusers=agora.get_groups()VariousThe members of any Agora object can be printed to the console with the display functionexam=agora.get_exam(22)exam.display()folder=agora.get_folder(15)folder.display()ContributingPull 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.LicenseMIT