Hire WorkforcePython SDKRequest Demo
Documentation

Custom metadata

Suggest Edits

Create custom fields

To create custom fields:

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
   }
}
 
SAClient.create_custom_fields(
   project = "Medical Annotations",
   fields = custom_fields
)

There are two types of custom fields:

  • Number
  • String

Fields with the number type can have the following field specs and values:

Field specSpec value
minimumany number (int or float)
maximumany number (int or float)
enumlist of numbers (int or float)

❗️

A field can’t have both maximum/minimum and enum field specs.

Fields with the string type can have the following field specs and values:

Field specSpec value
format“email” ([email protected]) or “date” (YYYY-MM-DD)
enumlist of strings

A spec is an additional characteristic that a custom metadata field could have.

📘

Messages

  • If the project type isn’t supported: “Unsupported project type.” Note that this feature works only with Image Projects, Video or Audio Projects, and Text Projects.
  • If the Explore feature isn’t enabled: “You do not have sufficient access to explore.”
  • If the custom field name(s) already exist(s): “Custom field name [field name] is not unique.”
  • You can create up to 25 custom fields. When you exceed the limit: “Maximum number of custom fields is 25. You can only create {25 - currently created active fields} more custom fields.”
  • If the field name already exists: “Field name [field name] is already used.”
  • If a field type is not a number or a string: “Not supported field type for [field name].”
  • If the spec value corresponds to a value or a string: “Spec value type of [field name] is not valid.”
  • “Maximum spec value of [field name] can't be less than minimum value.”
  • “Spec values of [field name] should be unique.”

Get custom fields

To get custom fields:

client = SAClient()
client.get_custom_fields(
	project = “Project 1”
)

Example of an output:

{
      "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
   }
}

Delete custom fields

To delete custom fields:

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

Example of an output:

{
   "study_date": {
       "type": "string",
       "format": "date"
   },
   "patient_id": {
       "type": "string"
   },
   "patient_sex": {
       "type": "string",
       "enum": [
           "male", "female"
       ]
   },
   "medical_specialist": {
       "type": "string",
       "format": "email"
   }
}

📘

Messages

  • If the project type isn’t supported: “Unsupported project type.” Note that this feature works only with Image Projects, Video or Audio Projects, and Text Projects.
  • If the Explore feature isn’t enabled: “You do not have sufficient access to explore.”
  • When the custom fields are deleted: “Matched fields deleted from schema.” You'll also receive this message when you misspell the name of the custom field but in that case, nothing will be deleted.

Upload custom values

To upload custom values:

client = SAClient()
 
items_values = [
   {
       "image_1.png": {
           "study_date": "2021-12-31",
           "patient_id": "62078f8a756ddb2ca9fc9660",
           "patient_sex": "female",
           "medical_specialist": "[email protected]"
       }
   },
   {
       "image_2.png": {
           "study_date": "2021-12-31",
           "patient_id": "62078f8a756ddb2ca9fc9661",
           "patient_sex": "female",
           "medical_specialist": "[email protected]"
       }
   },
   {
       "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
)

Example of a response:

{
   "succeeded": ["image_1.png", "image_2.png"],
   "failed": ["image_3.png"]
}

📘

Messages

  • If the project type isn’t supported: Unsupported project type. Note that this feature works only with Image Projects, Video or Audio Projects, and Text Projects.
  • If the Explore feature isn’t enabled: You do not have sufficient access to explore.
  • Invalid dictionaries aren’t attached to items. These items will be failed and you’ll see this message: The metadata dicts of [number of failed items] items are invalid because they don't match the schema of the custom fields defined for the "{proj_name}" project.
  • If the metadata is being validated: Validating metadata against the schema of the custom fields. Valid metadata will be attached to the specified item.

Overriding custom values

Case 1

If you upload a custom field and update its value, then the field will have the new value you just updated.

# GIVEN

{
  "medical_specialist": "[email protected]"
}

# WHEN

{
  "medical_specialist": "[email protected]"
}

# THEN

{
  "medical_specialist": "[email protected]"
}

Case 2

If you have more than 1 custom field and you update the value of one of them, then only the value of that custom field will be updated.

# GIVEN

{
  "valid_field_1": "value_1",
  "valid_field_2": "value_2"
}

# WHEN

{
    "valid_field_2": "new_value_2"
}

#THEN

{
  "valid_field_1": "value_1",
  "valid_field_2": "new_value_2"
}

Case 3

If you have a custom field then upload another one, then the new custom field will be added.

# GIVEN

{
  "valid_field_1": "value_1",
}

# WHEN

{
    "valid_field_2": "value_2"
}

# THEN

{
  "valid_field_1": "value_1",
  "valid_field_2": "value_2",
}

Delete custom values

To delete the custom values of specific items:

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

📘

Messages

  • If the project type isn’t supported: Unsupported project type. Note that this feature works only with Image Projects, Video or Audio Projects, and Text Projects.
  • If the Explore feature isn’t enabled: You do not have sufficient access to explore.
  • When the custom fields and their corresponding values of specific items are successfully removed: Corresponding fields and their values removed from items.

❗️

If you delete a custom field from the schema, the values associated with the delete field will be removed from all the corresponding items.

Get custom values

To get custom values:

SAClient.get_item_metadata(
   project = "Medical Annotations",
   item_name = "image_1.png",
   include_custom_metadata = True
)

Example of an output:

{
   "name": "image_1.jpeg",
   "path": "Medical Annotations/Study",
   "url": "https://sa-public-files.s3.../image_1.png",
   "annotation_status": "NotStarted",
   "annotator_email": None,
   "qa_email": None,
   "entropy_value": None,
   "createdAt": "2022-02-15T20:46:44.000Z",
   "updatedAt": "2022-02-15T20:46:44.000Z",
   "custom_metadata": {
       "study_date": "2021-12-31",
       "patient_id": "62078f8a756ddb2ca9fc9660",
       "patient_sex": "female",
       "medical_specialist": "[email protected]",
   }
}

If include_custom_metadata is set to False, then the output will be the following:

{
   "name": "image_1.jpeg",
   "path": "Medical Annotations/Study",
   "url": "https://sa-public-files.s3.../image_1.png",
   "annotation_status": "NotStarted",
   "annotator_email": None,
   "qa_email": None,
   "entropy_value": None,
   "createdAt": "2022-02-15T20:46:44.000Z",
   "updatedAt": "2022-02-15T20:46:44.000Z"
}

Updated 11 months ago