Echo PlateSurvey (Medman/”Echo Liquid Handler”) format

PlateSurveyXML: base file

pydantic model kithairon.surveys.platesurvey.EchoPlateSurveyXML

A platesurvey XML model for files generated by the Medman / ‘Echo Liquid Handler’ software.

Show JSON schema

{
   "title": "EchoPlateSurveyXML",
   "description": "A platesurvey XML model for files generated by the Medman / 'Echo Liquid Handler' software.",
   "type": "object",
   "properties": {
      "plate_type": {
         "title": "Plate Type",
         "type": "string"
      },
      "plate_barcode": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "title": "Plate Barcode"
      },
      "timestamp": {
         "format": "date-time",
         "title": "Timestamp",
         "type": "string"
      },
      "instrument_serial_number": {
         "title": "Instrument Serial Number",
         "type": "string"
      },
      "vtl": {
         "title": "Vtl",
         "type": "integer"
      },
      "original": {
         "title": "Original",
         "type": "integer"
      },
      "data_format_version": {
         "title": "Data Format Version",
         "type": "integer"
      },
      "survey_rows": {
         "description": "Number of rows in the survey",
         "title": "Survey Rows",
         "type": "integer"
      },
      "survey_columns": {
         "description": "Number of columns in the survey",
         "title": "Survey Columns",
         "type": "integer"
      },
      "survey_total_wells": {
         "title": "Survey Total Wells",
         "type": "integer"
      },
      "wells": {
         "items": {
            "$ref": "#/$defs/WellSurvey"
         },
         "title": "Wells",
         "type": "array"
      },
      "plate_name": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Plate Name"
      },
      "comment": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Comment"
      }
   },
   "$defs": {
      "EchoSignal": {
         "description": "Echo signal information for a well.  `e` element.",
         "properties": {
            "signal_type": {
               "title": "Signal Type",
               "type": "string"
            },
            "transducer_x": {
               "title": "Transducer X",
               "type": "number"
            },
            "transducer_y": {
               "title": "Transducer Y",
               "type": "number"
            },
            "transducer_z": {
               "title": "Transducer Z",
               "type": "number"
            },
            "features": {
               "items": {
                  "$ref": "#/$defs/SignalFeature"
               },
               "title": "Features",
               "type": "array"
            }
         },
         "required": [
            "signal_type",
            "transducer_x",
            "transducer_y",
            "transducer_z",
            "features"
         ],
         "title": "EchoSignal",
         "type": "object"
      },
      "SignalFeature": {
         "description": "Single feature of an echo signal.  `f` element.",
         "properties": {
            "feature_type": {
               "title": "Feature Type",
               "type": "string"
            },
            "tof": {
               "title": "Tof",
               "type": "number"
            },
            "vpp": {
               "title": "Vpp",
               "type": "number"
            }
         },
         "required": [
            "feature_type",
            "tof",
            "vpp"
         ],
         "title": "SignalFeature",
         "type": "object"
      },
      "WellSurvey": {
         "description": "Survey information for a single well. `w` element.",
         "properties": {
            "row": {
               "minimum": 0,
               "title": "Row",
               "type": "integer"
            },
            "column": {
               "minimum": 0,
               "title": "Column",
               "type": "integer"
            },
            "well": {
               "title": "Well",
               "type": "string"
            },
            "volume": {
               "anyOf": [
                  {
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "title": "Volume"
            },
            "current_volume": {
               "anyOf": [
                  {
                     "type": "number"
                  },
                  {
                     "type": "null"
                  }
               ],
               "title": "Current Volume"
            },
            "status": {
               "title": "Status",
               "type": "string"
            },
            "fluid": {
               "title": "Fluid",
               "type": "string"
            },
            "fluid_units": {
               "title": "Fluid Units",
               "type": "string"
            },
            "meniscus_x": {
               "title": "Meniscus X",
               "type": "number"
            },
            "meniscus_y": {
               "title": "Meniscus Y",
               "type": "number"
            },
            "fluid_composition": {
               "title": "Fluid Composition",
               "type": "number"
            },
            "dmso_homogeneous": {
               "title": "Dmso Homogeneous",
               "type": "number"
            },
            "dmso_inhomogeneous": {
               "title": "Dmso Inhomogeneous",
               "type": "number"
            },
            "fluid_thickness": {
               "title": "Fluid Thickness",
               "type": "number"
            },
            "current_fluid_thickness": {
               "title": "Current Fluid Thickness",
               "type": "number"
            },
            "bottom_thickness": {
               "title": "Bottom Thickness",
               "type": "number"
            },
            "fluid_thickness_homogeneous": {
               "title": "Fluid Thickness Homogeneous",
               "type": "number"
            },
            "fluid_thickness_imhomogeneous": {
               "title": "Fluid Thickness Imhomogeneous",
               "type": "number"
            },
            "outlier": {
               "title": "Outlier",
               "type": "number"
            },
            "corrective_action": {
               "title": "Corrective Action",
               "type": "string"
            },
            "echo_signal": {
               "$ref": "#/$defs/EchoSignal"
            }
         },
         "required": [
            "row",
            "column",
            "well",
            "volume",
            "current_volume",
            "status",
            "fluid",
            "fluid_units",
            "meniscus_x",
            "meniscus_y",
            "fluid_composition",
            "dmso_homogeneous",
            "dmso_inhomogeneous",
            "fluid_thickness",
            "current_fluid_thickness",
            "bottom_thickness",
            "fluid_thickness_homogeneous",
            "fluid_thickness_imhomogeneous",
            "outlier",
            "corrective_action",
            "echo_signal"
         ],
         "title": "WellSurvey",
         "type": "object"
      }
   },
   "required": [
      "plate_type",
      "plate_barcode",
      "timestamp",
      "instrument_serial_number",
      "vtl",
      "original",
      "data_format_version",
      "survey_rows",
      "survey_columns",
      "survey_total_wells",
      "wells"
   ]
}

Fields:

• comment (str | None)

• data_format_version (int)

• instrument_serial_number (str)

• original (int)

• plate_barcode (str | None)

• plate_name (str | None)

• plate_type (str)

• survey_columns (int)

• survey_rows (int)

• survey_total_wells (int)

• timestamp (datetime.datetime)

• vtl (int)

• wells (list[kithairon.surveys.platesurvey.WellSurvey])

Validators:

• check_data_format_version » all fields

• check_number_of_wells » all fields

field comment: str | None = None

Comment. Additional attribute, added by kithairon.

Validated by:

• check_data_format_version

• check_number_of_wells

field data_format_version: int [Required]

Version of data format. Only 1 is known to be used.

Validated by:

• check_data_format_version

• check_number_of_wells

field instrument_serial_number: str [Required]

Instrument serial number. serial_number attribute.

Validated by:

• check_data_format_version

• check_number_of_wells

field original: int [Required]

Validated by:

• check_data_format_version

• check_number_of_wells

field plate_barcode: <lambda>, json_schema_input_type=PydanticUndefined)] [Required]

Plate barcode, if present, or None, represented in XML as "UnknownBarCode". barcode attribute.

Constraints:

• func = <function <lambda> at 0x7d12f8e2fba0>

• return_type = PydanticUndefined

• when_used = unless-none

• json_schema_input_type = PydanticUndefined

Validated by:

• check_data_format_version

• check_number_of_wells

field plate_name: str | None = None

Plate name. Additional attribute, added by kithairon.

Validated by:

• check_data_format_version

• check_number_of_wells

field plate_type: str [Required]

The name attribute. Practically appears to always be the plate type.

Validated by:

• check_data_format_version

• check_number_of_wells

field survey_columns: int [Required]

Number of columns in the survey. cols attribute.

Number of columns in the survey

Validated by:

• check_data_format_version

• check_number_of_wells

field survey_rows: int [Required]

Number of rows in the survey. rows attribute.

Number of rows in the survey

Validated by:

• check_data_format_version

• check_number_of_wells

field survey_total_wells: int [Required]

Total number of wells in the survey. totalWells attribute.

Validated by:

• check_data_format_version

• check_number_of_wells

field timestamp: datetime [Required]

Timestamp of the survey. date attribute.

Validated by:

• check_data_format_version

• check_number_of_wells

field vtl: int [Required]

Currently unknown attribute (FIXME).

Validated by:

• check_data_format_version

• check_number_of_wells

field wells: list[WellSurvey] [Required]

List of wells. w elements.

Validated by:

• check_data_format_version

• check_number_of_wells

validator check_data_format_version  »  all fields

Ensure that the data format version is 1.

validator check_number_of_wells  »  all fields

Check that the number of wells matches the number of rows and columns.

classmethod read_xml(path: PathLike | str) → Self

Read a platesurvey XML file.

Returns:

EchoPlateSurveyXML

to_surveydata() → SurveyData

Convert the EchoPlateSurveyXML to a SurveyData containing a single survey.

Returns:

SurveyData

write_xml(

path: PathLike[str] | str | Callable[[Self], str],

path_str_format: bool = True,

**kwargs: dict[str, Any],

) → str | PathLike[str]

Write a platesurvey XML file.

Parameters:

pathos.PathLike[str] | str | Callable[[Self], str]

The path to write to. If a callable is provided, it will be called with the model as the argument.

path_str_formatbool

Whether to format the path string with the model dump (a nested dict of the plate survey’s contents, excluding the ‘wells’ key). Only used if path is a string. Default True.

Returns:

str | os.PathLike[str]

The (formatted) path to the file.

WellSurvey: individual well data

pydantic model kithairon.surveys.platesurvey.WellSurvey

Survey information for a single well. w element.

Show JSON schema

{
   "title": "WellSurvey",
   "description": "Survey information for a single well. `w` element.",
   "type": "object",
   "properties": {
      "row": {
         "minimum": 0,
         "title": "Row",
         "type": "integer"
      },
      "column": {
         "minimum": 0,
         "title": "Column",
         "type": "integer"
      },
      "well": {
         "title": "Well",
         "type": "string"
      },
      "volume": {
         "anyOf": [
            {
               "type": "number"
            },
            {
               "type": "null"
            }
         ],
         "title": "Volume"
      },
      "current_volume": {
         "anyOf": [
            {
               "type": "number"
            },
            {
               "type": "null"
            }
         ],
         "title": "Current Volume"
      },
      "status": {
         "title": "Status",
         "type": "string"
      },
      "fluid": {
         "title": "Fluid",
         "type": "string"
      },
      "fluid_units": {
         "title": "Fluid Units",
         "type": "string"
      },
      "meniscus_x": {
         "title": "Meniscus X",
         "type": "number"
      },
      "meniscus_y": {
         "title": "Meniscus Y",
         "type": "number"
      },
      "fluid_composition": {
         "title": "Fluid Composition",
         "type": "number"
      },
      "dmso_homogeneous": {
         "title": "Dmso Homogeneous",
         "type": "number"
      },
      "dmso_inhomogeneous": {
         "title": "Dmso Inhomogeneous",
         "type": "number"
      },
      "fluid_thickness": {
         "title": "Fluid Thickness",
         "type": "number"
      },
      "current_fluid_thickness": {
         "title": "Current Fluid Thickness",
         "type": "number"
      },
      "bottom_thickness": {
         "title": "Bottom Thickness",
         "type": "number"
      },
      "fluid_thickness_homogeneous": {
         "title": "Fluid Thickness Homogeneous",
         "type": "number"
      },
      "fluid_thickness_imhomogeneous": {
         "title": "Fluid Thickness Imhomogeneous",
         "type": "number"
      },
      "outlier": {
         "title": "Outlier",
         "type": "number"
      },
      "corrective_action": {
         "title": "Corrective Action",
         "type": "string"
      },
      "echo_signal": {
         "$ref": "#/$defs/EchoSignal"
      }
   },
   "$defs": {
      "EchoSignal": {
         "description": "Echo signal information for a well.  `e` element.",
         "properties": {
            "signal_type": {
               "title": "Signal Type",
               "type": "string"
            },
            "transducer_x": {
               "title": "Transducer X",
               "type": "number"
            },
            "transducer_y": {
               "title": "Transducer Y",
               "type": "number"
            },
            "transducer_z": {
               "title": "Transducer Z",
               "type": "number"
            },
            "features": {
               "items": {
                  "$ref": "#/$defs/SignalFeature"
               },
               "title": "Features",
               "type": "array"
            }
         },
         "required": [
            "signal_type",
            "transducer_x",
            "transducer_y",
            "transducer_z",
            "features"
         ],
         "title": "EchoSignal",
         "type": "object"
      },
      "SignalFeature": {
         "description": "Single feature of an echo signal.  `f` element.",
         "properties": {
            "feature_type": {
               "title": "Feature Type",
               "type": "string"
            },
            "tof": {
               "title": "Tof",
               "type": "number"
            },
            "vpp": {
               "title": "Vpp",
               "type": "number"
            }
         },
         "required": [
            "feature_type",
            "tof",
            "vpp"
         ],
         "title": "SignalFeature",
         "type": "object"
      }
   },
   "required": [
      "row",
      "column",
      "well",
      "volume",
      "current_volume",
      "status",
      "fluid",
      "fluid_units",
      "meniscus_x",
      "meniscus_y",
      "fluid_composition",
      "dmso_homogeneous",
      "dmso_inhomogeneous",
      "fluid_thickness",
      "current_fluid_thickness",
      "bottom_thickness",
      "fluid_thickness_homogeneous",
      "fluid_thickness_imhomogeneous",
      "outlier",
      "corrective_action",
      "echo_signal"
   ]
}

Fields:

• bottom_thickness (float)

• column (int)

• corrective_action (str)

• current_fluid_thickness (float)

• current_volume (float | None)

• dmso_homogeneous (float)

• dmso_inhomogeneous (float)

• echo_signal (kithairon.surveys.platesurvey.EchoSignal)

• fluid (str)

• fluid_composition (float)

• fluid_thickness (float)

• fluid_thickness_homogeneous (float)

• fluid_thickness_imhomogeneous (float)

• fluid_units (str)

• meniscus_x (float)

• meniscus_y (float)

• outlier (float)

• row (int)

• status (str)

• volume (float | None)

• well (str)

field bottom_thickness: float [Required]

Thickness measurement of plate bottom, in µs (FIXME). b attribute.

field column: Annotated[int, Ge(ge=0)] [Required]

Column number. 0-indexed to top-left well of plate, not of survey. c attribute.

Constraints:

• ge = 0

field corrective_action: str [Required]

field current_fluid_thickness: float [Required]

field current_volume: <lambda>, return_type=PydanticUndefined, when_used=unless-none)] [Required]

Constraints:

• func = <function <lambda> at 0x7d12f8e2fce0>

• json_schema_input_type = PydanticUndefined

• return_type = PydanticUndefined

• when_used = unless-none

field dmso_homogeneous: float [Required]

field dmso_inhomogeneous: float [Required]

field echo_signal: EchoSignal [Required]

field fluid: str [Required]

field fluid_composition: float [Required]

field fluid_thickness: float [Required]

field fluid_thickness_homogeneous: float [Required]

field fluid_thickness_imhomogeneous: float [Required]

field fluid_units: str [Required]

field meniscus_x: float [Required]

field meniscus_y: float [Required]

field outlier: float [Required]

field row: Annotated[int, Ge(ge=0)] [Required]

Row number. 0-indexed to top-left well of plate, not of survey. r attribute.

Constraints:

• ge = 0

field status: str [Required]

Status message. Blank if well survey was successful (FIXME: in every case we have seen). Error description if unsuccessful.

field volume: <lambda>, return_type=PydanticUndefined, when_used=unless-none)] [Required]

Calculated well volume, in µL. None if the volume could not be calculated (0 in XML). vl attribute.

Constraints:

• func = <function <lambda> at 0x7d12f8e2fce0>

• json_schema_input_type = PydanticUndefined

• return_type = PydanticUndefined

• when_used = unless-none

field well: str [Required]

Well position name, in standard unpadded format (eg, “A1” and “D12”). n attribute.

EchoSignal and SignalFeature

pydantic model kithairon.surveys.platesurvey.EchoSignal

Echo signal information for a well. e element.

Show JSON schema

{
   "title": "EchoSignal",
   "description": "Echo signal information for a well.  `e` element.",
   "type": "object",
   "properties": {
      "signal_type": {
         "title": "Signal Type",
         "type": "string"
      },
      "transducer_x": {
         "title": "Transducer X",
         "type": "number"
      },
      "transducer_y": {
         "title": "Transducer Y",
         "type": "number"
      },
      "transducer_z": {
         "title": "Transducer Z",
         "type": "number"
      },
      "features": {
         "items": {
            "$ref": "#/$defs/SignalFeature"
         },
         "title": "Features",
         "type": "array"
      }
   },
   "$defs": {
      "SignalFeature": {
         "description": "Single feature of an echo signal.  `f` element.",
         "properties": {
            "feature_type": {
               "title": "Feature Type",
               "type": "string"
            },
            "tof": {
               "title": "Tof",
               "type": "number"
            },
            "vpp": {
               "title": "Vpp",
               "type": "number"
            }
         },
         "required": [
            "feature_type",
            "tof",
            "vpp"
         ],
         "title": "SignalFeature",
         "type": "object"
      }
   },
   "required": [
      "signal_type",
      "transducer_x",
      "transducer_y",
      "transducer_z",
      "features"
   ]
}

Fields:

• features (list[kithairon.surveys.platesurvey.SignalFeature])

• signal_type (str)

• transducer_x (float)

• transducer_y (float)

• transducer_z (float)

field features: list[SignalFeature] [Required]

field signal_type: str [Required]

field transducer_x: float [Required]

field transducer_y: float [Required]

field transducer_z: float [Required]

pydantic model kithairon.surveys.platesurvey.SignalFeature

Single feature of an echo signal. f element.

Show JSON schema

{
   "title": "SignalFeature",
   "description": "Single feature of an echo signal.  `f` element.",
   "type": "object",
   "properties": {
      "feature_type": {
         "title": "Feature Type",
         "type": "string"
      },
      "tof": {
         "title": "Tof",
         "type": "number"
      },
      "vpp": {
         "title": "Vpp",
         "type": "number"
      }
   },
   "required": [
      "feature_type",
      "tof",
      "vpp"
   ]
}

Fields:

• feature_type (str)

• tof (float)

• vpp (float)

field feature_type: str [Required]

field tof: float [Required]

field vpp: float [Required]