Tutorial¶

1. Login to your account¶

Create an instance of your account with your user and password and list your current projects:

import qmenta.client

# Create a connection (logins automatically)
account = qmenta.client.Account("user", "password")

Check your existing projects by listing them from your account:

print(account.projects)

Output:

[{'id': 80, 'name': 'Nunc interdum lacus sit'},
 {'id': 43, 'name': 'Test Project'}]

2.a Create a project¶

You can create a new project:

# Add a new project
project = account.add_project('parkinson', 'Parkinson')

The variable project is an instance of :py:class:Project.

2.b Get an already existing project¶

# List the projects from the current account:
account.projects
# Sample output:
# [ { 'name': 'project1', 'id': 1 },
#   { 'name': 'project2', 'id': 2 }
# ]
#

# Retrieve a project, using the project id
project = qmenta.client.Project(account, 1)

The variable project is an instance of Project.

3. Create a Subject¶

All the data uploaded to the platform should be treated as the data of a subject. To upload data using the API, you should first create an instance of that subject and then upload the data related to it. If the subject already exists go to #4.

# You can check all the subjects:
all_subjects = project.subjects

# Or create a new one by instantiating a Subject object
new_subject = qmenta.client.Subject('name')
# In this case remember to add it to the project!
project.add_subject(new_subject):

4. Get an existing subject¶

If you want to add data, metadata or a result to a existing user, use the Project.get_subject() function instead of creating a new one. If you want you can list the existing subjects using Project.subjects.

subject = project.get_subject('A025')

# Returns a Subject Object
<qmenta.client.Subject.Subject at 0x10f0df7f0>

5. Check the metadata from a subject¶

You can check metadata for a given subject using the attribute Subject.parameters(). Each subject can have different timepoints, which are identified by the SSID (session identificator). The method Subject.parameters() returns a dictionary whose keys are the SSIDs. The values are dictionaries, with the metadata contained under the key ‘metadata’.

parameters_all_sessions = subject.parameters
# parameters_all_session is a dictionary:
#    { ssid: { metadata: { param_name: param_value, ...},
#              tags: [...] }
#      ssid2: ..., }
parameters_ssid_1 = subject.parameters[1]
print(parameters_ssid_1)

{'date': {'$date': 1441152000000},
'date_birth': {'$date': -723772800000},
'family': 'None',
'gender': 'male',
'tremor': 'None'}

6. Add new parameters to a project¶

As the metadata fields are share along the subjects in a project, if you want to add a new parameter to your subjects, you must create it in the project first. Then, you can edit that parameter for each subject. All subjects share the default value of None for nondefined parameters.

# List the parameters of this project [NOT WORKING YET]
project.metadata_parameters

# Add a new parameter to the project [NOT WORKING]
project.add_metadata_parameter("myparameter", param_id="X", param_type="string", visible=True)

7. Modify the value of a parameter for a given subject¶

In order to modify the value of a given parameter, we must first retrieve the parameters from a subject. This will yield a dictionary that we must save, modify, and use to update the parameters. Let’s say that we want to modify the parameters of a subject, but only those of the session 1.

# Get the parameters:
parameters_ssid_1 = subject.parameters[1]

# Edit a certain parameter
parameters_ssid_1["my_parameter"] = 42

# Update them. "1" refers to the ssid (the session that we want to update).
subject.set_parameters(1, parameters_ssid_1)

6. Upload data¶

Depending the type of data you want to upload the function differs, but all share the same workflow. The functions are: Subject.upload_mri() and Subject.upload_parkinson(). Right know you must give the path a zip file that will be uploaded.

import os
mri_file = os.path.abspath("t1andt2.zip")
subject.upload_mri(mri_file)

7. Start an analysis¶

The function Project.start_analysis() can be used to start an analysis, which will process a set of uploaded files. The platform needs to know two things:

Which kind of analysis to perform. This is, one of:
‘morphology’, ‘morphology_new’, ‘3d_wires’, ‘dti_fa_files’, ‘2d_wires’, ‘morphology_infant’
The id of the container which holds the files to analyze.

# given a user, see the containers (one container = one session of
# uploaded files).
print(subject.input_containers)
# sample output:
#  [{'container_id': 2149, 'container_name': 'T1_33.zip'},
#   {'container_id': 2135, 'container_name': 'T1_34.zip'}]

# start analysis using the files from container T1_33.zip (id 2149):
project.start_analysis(script_name='morphology', version='1.0',
                       in_container_id=2149,
                       analysis_name='morphology of subject 33',
                       analysis_description='morphology of subject 33 for project blablabla')

8. Upload a result¶

If you want to upload an already processed file, you should first put it into a zip:

import os
surfaces_file = os.path.abspath("surfaces.zip")
subject.upload_result(surfaces_file)