Custom Metadata#

SAClient.create_custom_fields(project, fields)#

Create custom fields for items in a project in addition to built-in metadata. Using this function again with a different schema won’t override the existing fields, but add new ones. Use the upload_custom_values() function to fill them with values for each item.

Parameters:

  • project (str) – project name (e.g., “project1”)

  • fields (dict) – dictionary describing the fields and their specifications added to the project. You can see the schema structure <here>.

Returns:

custom fields actual schema of the project

Return type:

dict

Supported Types:

number

field spec

spec value

minimum

any number (int or float)

maximum

any number (int or float)

enum

list of numbers (int or float)

string

field spec

spec value

format

“email” (user@example.com) or “date” (YYYY-MM-DD)

enum

list of strings

 
custom_fields = {
   "study_date": {
       "type": "string",
       "format": "date"
   },
   "patient_id": {
       "type": "string"
   },
   "patient_sex": {
       "type": "string",
       "enum": [
           "male", "female"
       ]
   },
   "patient_age": {
       "type": "number"
   },
   "medical_specialist": {
       "type": "string",
       "format": "email"
   },
   "duration": {
       "type": "number",
       "minimum": 10
   }
}

client = SAClient()
client.create_custom_fields(
   project="Medical Annotations",
   fields=custom_fields
)
SAClient.get_custom_fields(project)#

Get the schema of the custom fields defined for the project

Parameters:

project (str) – project name (e.g., “project1”)

Returns:

custom fields actual schema of the project

Return type:

dict

Response Example:

{
   "study_date": {
       "type": "string",
       "format": "date"
   },
   "patient_id": {
       "type": "string"
   },
   "patient_sex": {
       "type": "string",
       "enum": [
           "male", "female"
       ]
   },
   "patient_age": {
       "type": "number"
   },
   "medical_specialist": {
       "type": "string",
       "format": "email"
   },
   "duration": {
       "type": "number",
       "minimum": 10
   }
}
SAClient.delete_custom_fields(project, fields)#

Remove custom fields from a project’s custom metadata schema.

Parameters:

  • project (str) – project name (e.g., “project1”)

  • fields (list of strs) – list of field names to remove

Returns:

custom fields actual schema of the project

Return type:

dict

Request Example:

client = SAClient()
client.delete_custom_fields(
   project = "Medical Annotations",
   fields = ["duration", patient_age]
)

Response Example:

{
    "study_date": {
       "type": "string",
       "format": "date"
    },
    "patient_id": {
       "type": "string"
    },
    "patient_sex": {
       "type": "string",
       "enum": [
           "male", "female"
       ]
    },
    "medical_specialist": {
       "type": "string",
       "format": "email"
    }
}
SAClient.upload_custom_values(project, items)#

Attach custom metadata to items. SAClient.get_item_metadata(), SAClient.search_items(), SAClient.query() methods will return the item metadata and custom metadata.

Parameters:

  • project (str) – project name or folder path (e.g., “project1/folder1”)

  • items (list of dicts) – list of name-data pairs. The key of each dict indicates an existing item name and the value represents the custom metadata dict. The values for the corresponding keys will be added to an item or will be overridden.

Returns:

dictionary with succeeded and failed item names.

Return type:

dict

Request Example:

client = SAClient()

items_values = [
   {
       "image_1.png": {
           "study_date": "2021-12-31",
           "patient_id": "62078f8a756ddb2ca9fc9660",
           "patient_sex": "female",
           "medical_specialist": "robertboxer@ms.com"
       }
   },
   {
       "image_2.png": {
           "study_date": "2021-12-31",
           "patient_id": "62078f8a756ddb2ca9fc9661",
           "patient_sex": "female",
           "medical_specialist": "robertboxer@ms.com"
       }
   },
   {
       "image_3.png": {
           "study_date": "2011-10-05T14:48:00.000Z",
           "patient_": "62078f8a756ddb2ca9fc9660",
           "patient_sex": "female",
           "medical_specialist": "robertboxer"
       }
   }
]

client.upload_custom_values(
   project = "Medical Annotations",
   items = items_values
)

Response Example:

{
   "successful_items_count": 2,
   "failed_items_names": ["image_3.png"]
}
SAClient.delete_custom_values(project, items)#

Remove custom data from items

Parameters:

  • project (str) – project name or folder path (e.g., “project1/folder1”)

  • items (list of dicts) – list of name-custom data dicts. The key of each dict element indicates an existing item in the project root or folder. The value should be the list of fields to be removed from the given item. Please note, that the function removes pointed metadata from a given item. To delete metadata for all items you should delete it from the custom metadata schema. To override values for existing fields, use SAClient.upload_custom_values()

Request Example:

client.delete_custom_values(
    project = "Medical Annotations",
    items = [
       {"image_1.png": ["study_date", "patient_sex"]},
       {"image_2.png": ["study_date", "patient_sex"]}
    ]
)