Python Library¶
The QuAAC project includes a Python library that can be used to interact with YAML and JSON QuAAC documents. It is not required to use the library to interact with QuAAC documents, but it can be useful for reading and writing QuAAC documents.
Installation¶
To install the quaac package, you must have Python installed. If you do not have Python installed, you can download it from
Python’s website.
Once you have Python installed, you can install the quaac package using pip. Open a terminal and run the following command:
pip install quaac
Versioning¶
The Python library uses semantic versioning and the major and minor versions will always be versioned to match the QuAAC version it will process. The patch version will be incremented for bug fixes and minor changes. E.g. QuAAC specification 1.0.0 will be processed by the Python library 1.0.x versions.
Model API¶
- pydantic model quaac.models.DataPoint¶
Bases:
HashModelA singular measurement of a quality assurance session.
Show JSON schema
{ "title": "DataPoint", "description": "A singular measurement of a quality assurance session.", "type": "object", "properties": { "from_file_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The original hash of the entry. Only populates when loading from JSON/YAML.", "title": "From File Hash" }, "name": { "description": "The name of the datapoint.", "examples": [ "Temperature", "6MV Output", "CBCT Spotlight Uniformity Center" ], "title": "Name", "type": "string" }, "perform datetime": { "description": "The date and time the measurement was performed. Must be in ISO 8601 format.", "examples": [ "2021-08-01T12:00:00" ], "format": "date-time", "title": "Perform Datetime", "type": "string" }, "measurement value": { "description": "The value of the measurement.", "examples": [ 1, 1.0, "1", "1.0" ], "title": "Measurement Value" }, "measurement unit": { "description": "The unit of the measurement.", "examples": [ "cGy", "Celsius", "mm", "nC", "cm" ], "title": "Measurement Unit", "type": "string" }, "reference value": { "anyOf": [ {}, { "type": "null" } ], "default": null, "description": "The reference value of the measurement.", "examples": [ 1, 1.0, "1", "1.0" ], "title": "Reference Value" }, "description": { "default": "", "description": "A description of the measurement. This can reference any specific equations or algorithms used.", "examples": [ "Based on TG-51 eqn 8" ], "title": "Description", "type": "string" }, "procedure": { "default": "", "description": "The instructions used to perform the measurement.", "examples": [ "Use blocks A and D on the couch with 10x10cm field size. SSD=100 to top of block A" ], "title": "Procedure", "type": "string" }, "performer": { "allOf": [ { "$ref": "#/$defs/User" } ], "description": "The user who performed the measurement.", "examples": [ "1" ], "title": "Performer", "type": "string" }, "performer comment": { "default": "", "description": "Any comments the performer has about the measurement.", "examples": [ "The temperature was 22C" ], "title": "Performer Comment", "type": "string" }, "primary equipment": { "allOf": [ { "$ref": "#/$defs/Equipment" } ], "description": "The equipment used to perform the measurement.", "examples": [ "1" ], "title": "Primary Equipment", "type": "string" }, "reviewer": { "anyOf": [ { "$ref": "#/$defs/User" }, { "type": "null" } ], "default": null, "description": "The user who reviewed the data point.", "examples": [ "1" ], "title": "Reviewer", "type": "string" }, "parameters": { "description": "Any parameters used to perform the measurement.", "examples": [ { "field_size": "10x10cm", "ssd": "100cm" } ], "title": "Parameters", "type": "object" }, "ancillary equipment": { "description": "The internal IDs of any ancillary equipment used to perform the measurement.", "examples": [ "1" ], "items": { "$ref": "#/$defs/Equipment" }, "title": "Ancillary Equipment", "type": "string" }, "attachments": { "description": "The files associated with the measurement.", "examples": [ "1" ], "items": { "$ref": "#/$defs/Attachment" }, "title": "Attachments", "type": "string" } }, "$defs": { "Attachment": { "additionalProperties": true, "description": "A binary file that relates to a data point. This could be a screenshot, DICOM data set, or a PDF.", "properties": { "from_file_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The original hash of the entry. Only populates when loading from JSON/YAML.", "title": "From File Hash" }, "name": { "description": "The name of the file.", "examples": [ "catphan.zip", "screenshot.png" ], "title": "Name", "type": "string" }, "comment": { "default": "", "description": "A comment about the file.", "examples": [ "This is the screenshot of the CBCT" ], "title": "Comment", "type": "string" }, "encoding": { "default": "base64", "description": "The encoding of the file.", "examples": [ "base64" ], "title": "Encoding", "type": "string" }, "compression": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "gzip", "description": "The compression of the file.", "examples": [ "gzip" ], "title": "Compression" }, "content": { "description": "The content of the file.", "examples": [ "b'H4sIAAAAAAAAA...'" ], "format": "binary", "title": "Content", "type": "string" } }, "required": [ "name", "content" ], "title": "Attachment", "type": "object" }, "Equipment": { "additionalProperties": true, "description": "A peice of equipment. This could be primary equipment such as a linac or ancillary equipment such as a phantom or chamber.", "properties": { "from_file_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The original hash of the entry. Only populates when loading from JSON/YAML.", "title": "From File Hash" }, "name": { "description": "The name of the equipment.", "examples": [ "TrueBeam 1", "Basement 600" ], "title": "Name", "type": "string" }, "type": { "description": "The type of the equipment.", "examples": [ "L", "CT scanner" ], "title": "Type", "type": "string" }, "serial number": { "description": "The serial number of the equipment.", "examples": [ "12345", "H192311" ], "title": "Serial Number", "type": "string" }, "manufacturer": { "description": "The manufacturer of the equipment.", "examples": [ "Varian", "Siemens" ], "title": "Manufacturer", "type": "string" }, "model": { "description": "The model of the equipment.", "examples": [ "TrueBeam", "Artiste" ], "title": "Model", "type": "string" } }, "required": [ "name", "type", "serial number", "manufacturer", "model" ], "title": "Equipment", "type": "object" }, "User": { "additionalProperties": true, "description": "A user. This could be the performer or reviewer of a data point.", "properties": { "from_file_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The original hash of the entry. Only populates when loading from JSON/YAML.", "title": "From File Hash" }, "name": { "description": "The name of the user.", "examples": [ "John Doe", "Jane Smith" ], "title": "Name", "type": "string" }, "email": { "description": "The email of the user.", "examples": [ "john@clinic.com", "jane@satellite.com" ], "format": "email", "title": "Email", "type": "string" } }, "required": [ "name", "email" ], "title": "User", "type": "object" } }, "additionalProperties": true, "required": [ "name", "perform datetime", "measurement value", "measurement unit", "performer", "primary equipment" ] }
- Fields:
- field ancillary_equipment: list[Equipment] [Optional] (alias 'ancillary equipment')¶
The internal IDs of any ancillary equipment used to perform the measurement.
- Validated by:
check_hashsave_original_hash_key
- field attachments: list[Attachment] [Optional]¶
The files associated with the measurement.
- Validated by:
check_hashsave_original_hash_key
- field description: str = ''¶
A description of the measurement. This can reference any specific equations or algorithms used.
- Validated by:
check_hashsave_original_hash_key
- field measurement_unit: str [Required] (alias 'measurement unit')¶
The unit of the measurement.
- Validated by:
check_hashsave_original_hash_key
- field measurement_value: Any [Required] (alias 'measurement value')¶
The value of the measurement.
- Validated by:
check_hashsave_original_hash_key
- field name: str [Required]¶
The name of the datapoint.
- Validated by:
check_hashsave_original_hash_key
- field parameters: dict[str, Any] [Optional]¶
Any parameters used to perform the measurement.
- Validated by:
check_hashsave_original_hash_key
- field perform_datetime: datetime [Required] (alias 'perform datetime')¶
The date and time the measurement was performed. Must be in ISO 8601 format.
- Validated by:
check_hashsave_original_hash_key
- field performer: User [Required]¶
The user who performed the measurement.
- Validated by:
check_hashsave_original_hash_key
- field performer_comment: str = '' (alias 'performer comment')¶
Any comments the performer has about the measurement.
- Validated by:
check_hashsave_original_hash_key
- field primary_equipment: Equipment [Required] (alias 'primary equipment')¶
The equipment used to perform the measurement.
- Validated by:
check_hashsave_original_hash_key
- field procedure: str = ''¶
The instructions used to perform the measurement.
- Validated by:
check_hashsave_original_hash_key
- field reference_value: Any | None = None (alias 'reference value')¶
The reference value of the measurement.
- Validated by:
check_hashsave_original_hash_key
- pydantic model quaac.models.Document¶
Bases:
HashModelThe top-level model for QuAAC. Contains data points.
Show JSON schema
{ "title": "Document", "description": "The top-level model for QuAAC. Contains data points.", "type": "object", "properties": { "from_file_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The original hash of the entry. Only populates when loading from JSON/YAML.", "title": "From File Hash" }, "version": { "const": "1.0", "default": "1.0", "description": "The version of the QuAAC document.", "enum": [ "1.0" ], "title": "Version", "type": "string" }, "datapoints": { "description": "The data points in the document.", "items": { "$ref": "#/$defs/DataPoint" }, "title": "Data Points", "type": "array" } }, "$defs": { "Attachment": { "additionalProperties": true, "description": "A binary file that relates to a data point. This could be a screenshot, DICOM data set, or a PDF.", "properties": { "from_file_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The original hash of the entry. Only populates when loading from JSON/YAML.", "title": "From File Hash" }, "name": { "description": "The name of the file.", "examples": [ "catphan.zip", "screenshot.png" ], "title": "Name", "type": "string" }, "comment": { "default": "", "description": "A comment about the file.", "examples": [ "This is the screenshot of the CBCT" ], "title": "Comment", "type": "string" }, "encoding": { "default": "base64", "description": "The encoding of the file.", "examples": [ "base64" ], "title": "Encoding", "type": "string" }, "compression": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "gzip", "description": "The compression of the file.", "examples": [ "gzip" ], "title": "Compression" }, "content": { "description": "The content of the file.", "examples": [ "b'H4sIAAAAAAAAA...'" ], "format": "binary", "title": "Content", "type": "string" } }, "required": [ "name", "content" ], "title": "Attachment", "type": "object" }, "DataPoint": { "additionalProperties": true, "description": "A singular measurement of a quality assurance session.", "properties": { "from_file_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The original hash of the entry. Only populates when loading from JSON/YAML.", "title": "From File Hash" }, "name": { "description": "The name of the datapoint.", "examples": [ "Temperature", "6MV Output", "CBCT Spotlight Uniformity Center" ], "title": "Name", "type": "string" }, "perform datetime": { "description": "The date and time the measurement was performed. Must be in ISO 8601 format.", "examples": [ "2021-08-01T12:00:00" ], "format": "date-time", "title": "Perform Datetime", "type": "string" }, "measurement value": { "description": "The value of the measurement.", "examples": [ 1, 1.0, "1", "1.0" ], "title": "Measurement Value" }, "measurement unit": { "description": "The unit of the measurement.", "examples": [ "cGy", "Celsius", "mm", "nC", "cm" ], "title": "Measurement Unit", "type": "string" }, "reference value": { "anyOf": [ {}, { "type": "null" } ], "default": null, "description": "The reference value of the measurement.", "examples": [ 1, 1.0, "1", "1.0" ], "title": "Reference Value" }, "description": { "default": "", "description": "A description of the measurement. This can reference any specific equations or algorithms used.", "examples": [ "Based on TG-51 eqn 8" ], "title": "Description", "type": "string" }, "procedure": { "default": "", "description": "The instructions used to perform the measurement.", "examples": [ "Use blocks A and D on the couch with 10x10cm field size. SSD=100 to top of block A" ], "title": "Procedure", "type": "string" }, "performer": { "allOf": [ { "$ref": "#/$defs/User" } ], "description": "The user who performed the measurement.", "examples": [ "1" ], "title": "Performer", "type": "string" }, "performer comment": { "default": "", "description": "Any comments the performer has about the measurement.", "examples": [ "The temperature was 22C" ], "title": "Performer Comment", "type": "string" }, "primary equipment": { "allOf": [ { "$ref": "#/$defs/Equipment" } ], "description": "The equipment used to perform the measurement.", "examples": [ "1" ], "title": "Primary Equipment", "type": "string" }, "reviewer": { "anyOf": [ { "$ref": "#/$defs/User" }, { "type": "null" } ], "default": null, "description": "The user who reviewed the data point.", "examples": [ "1" ], "title": "Reviewer", "type": "string" }, "parameters": { "description": "Any parameters used to perform the measurement.", "examples": [ { "field_size": "10x10cm", "ssd": "100cm" } ], "title": "Parameters", "type": "object" }, "ancillary equipment": { "description": "The internal IDs of any ancillary equipment used to perform the measurement.", "examples": [ "1" ], "items": { "$ref": "#/$defs/Equipment" }, "title": "Ancillary Equipment", "type": "string" }, "attachments": { "description": "The files associated with the measurement.", "examples": [ "1" ], "items": { "$ref": "#/$defs/Attachment" }, "title": "Attachments", "type": "string" } }, "required": [ "name", "perform datetime", "measurement value", "measurement unit", "performer", "primary equipment" ], "title": "DataPoint", "type": "object" }, "Equipment": { "additionalProperties": true, "description": "A peice of equipment. This could be primary equipment such as a linac or ancillary equipment such as a phantom or chamber.", "properties": { "from_file_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The original hash of the entry. Only populates when loading from JSON/YAML.", "title": "From File Hash" }, "name": { "description": "The name of the equipment.", "examples": [ "TrueBeam 1", "Basement 600" ], "title": "Name", "type": "string" }, "type": { "description": "The type of the equipment.", "examples": [ "L", "CT scanner" ], "title": "Type", "type": "string" }, "serial number": { "description": "The serial number of the equipment.", "examples": [ "12345", "H192311" ], "title": "Serial Number", "type": "string" }, "manufacturer": { "description": "The manufacturer of the equipment.", "examples": [ "Varian", "Siemens" ], "title": "Manufacturer", "type": "string" }, "model": { "description": "The model of the equipment.", "examples": [ "TrueBeam", "Artiste" ], "title": "Model", "type": "string" } }, "required": [ "name", "type", "serial number", "manufacturer", "model" ], "title": "Equipment", "type": "object" }, "User": { "additionalProperties": true, "description": "A user. This could be the performer or reviewer of a data point.", "properties": { "from_file_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The original hash of the entry. Only populates when loading from JSON/YAML.", "title": "From File Hash" }, "name": { "description": "The name of the user.", "examples": [ "John Doe", "Jane Smith" ], "title": "Name", "type": "string" }, "email": { "description": "The email of the user.", "examples": [ "john@clinic.com", "jane@satellite.com" ], "format": "email", "title": "Email", "type": "string" } }, "required": [ "name", "email" ], "title": "User", "type": "object" } }, "additionalProperties": true, "required": [ "datapoints" ] }
- field datapoints: list[DataPoint] [Required]¶
The data points in the document.
- Validated by:
check_hashreplace_hash_keyssave_original_hash_key
- field version: Literal['1.0'] = '1.0'¶
The version of the QuAAC document.
- Validated by:
check_hashreplace_hash_keyssave_original_hash_key
- classmethod from_json_file(path: str, check_hash: bool = True) Document¶
Load a document from a JSON file.
Parameters¶
- pathstr
The path to the JSON file.
- check_hashbool
Whether to check the hash of the file. This is True by default. If the file has been edited since it was created, an error will be raised.
- classmethod from_yaml_file(path: str, check_hash: bool = True) Document¶
Load a document from a YAML file.
- to_json_file(path: str, indent: int = 4) None¶
Write the document to a JSON file.
- to_yaml_file(path: str) None¶
Write the document to a YAML file.
- property attachments: set[Attachment]¶
The unique attachments from the datapoints.
- pydantic model quaac.models.Equipment¶
Bases:
HashModelA peice of equipment. This could be primary equipment such as a linac or ancillary equipment such as a phantom or chamber.
Show JSON schema
{ "title": "Equipment", "description": "A peice of equipment. This could be primary equipment such as a linac or ancillary equipment such as a phantom or chamber.", "type": "object", "properties": { "from_file_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The original hash of the entry. Only populates when loading from JSON/YAML.", "title": "From File Hash" }, "name": { "description": "The name of the equipment.", "examples": [ "TrueBeam 1", "Basement 600" ], "title": "Name", "type": "string" }, "type": { "description": "The type of the equipment.", "examples": [ "L", "CT scanner" ], "title": "Type", "type": "string" }, "serial number": { "description": "The serial number of the equipment.", "examples": [ "12345", "H192311" ], "title": "Serial Number", "type": "string" }, "manufacturer": { "description": "The manufacturer of the equipment.", "examples": [ "Varian", "Siemens" ], "title": "Manufacturer", "type": "string" }, "model": { "description": "The model of the equipment.", "examples": [ "TrueBeam", "Artiste" ], "title": "Model", "type": "string" } }, "additionalProperties": true, "required": [ "name", "type", "serial number", "manufacturer", "model" ] }
- field manufacturer: str [Required]¶
The manufacturer of the equipment.
- Validated by:
check_hashsave_original_hash_key
- field model: str [Required]¶
The model of the equipment.
- Validated by:
check_hashsave_original_hash_key
- field name: str [Required]¶
The name of the equipment.
- Validated by:
check_hashsave_original_hash_key
- field serial_number: str [Required] (alias 'serial number')¶
The serial number of the equipment.
- Validated by:
check_hashsave_original_hash_key
- field type: str [Required]¶
The type of the equipment.
- Validated by:
check_hashsave_original_hash_key
- pydantic model quaac.models.User¶
Bases:
HashModelA user. This could be the performer or reviewer of a data point.
Show JSON schema
{ "title": "User", "description": "A user. This could be the performer or reviewer of a data point.", "type": "object", "properties": { "from_file_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The original hash of the entry. Only populates when loading from JSON/YAML.", "title": "From File Hash" }, "name": { "description": "The name of the user.", "examples": [ "John Doe", "Jane Smith" ], "title": "Name", "type": "string" }, "email": { "description": "The email of the user.", "examples": [ "john@clinic.com", "jane@satellite.com" ], "format": "email", "title": "Email", "type": "string" } }, "additionalProperties": true, "required": [ "name", "email" ] }
- field email: EmailStr [Required]¶
The email of the user.
- Validated by:
check_hashsave_original_hash_key
- field name: str [Required]¶
The name of the user.
- Validated by:
check_hashsave_original_hash_key
Attachment Options API¶
- class quaac.attachments.Compression¶
Compression algorithms supported by QuAACS.
GZIP: Gzip compression. NONE: No compression.
- class quaac.attachments.Encoding¶
Encoding algorithms supported by QuAACS.
BASE64: Base64 encoding.