Skip to content

mihcsme_py.writer#

mihcsme_py.writer #

Write MIHCSME metadata to Excel format.

fill_template(metadata: MIHCSMEMetadata, output_path: Union[Path, BinaryIO], template_path: Union[str, Path, None] = None) -> None #

Write MIHCSME metadata into the official MIHCSME Excel template.

Unlike :func:write_metadata_to_excel, this keeps the full template layout: every field (also empty ones), the descriptions/examples column, the dropdown validations and the ontology reference sheets.

  • Values are written into the Value column of matching (group, key) rows. Value cells of template rows without metadata are cleared.
  • Fields not present in the template are appended below the existing rows.
  • Data collaborators fill the template's collaborator rows in order; extra collaborators are appended.
  • AssayConditions keeps the template columns; extra condition keys are added as new columns and existing data rows are replaced.

:param metadata: MIHCSMEMetadata object to export :param output_path: Path to output Excel file, or a file-like object (e.g., BytesIO) :param template_path: Optional custom template; defaults to the bundled LEI-MIHCSME template

Source code in src/mihcsme_py/writer.py
def fill_template(
    metadata: MIHCSMEMetadata,
    output_path: Union[Path, BinaryIO],
    template_path: Union[str, Path, None] = None,
) -> None:
    """
    Write MIHCSME metadata into the official MIHCSME Excel template.

    Unlike :func:`write_metadata_to_excel`, this keeps the full template layout:
    every field (also empty ones), the descriptions/examples column, the
    dropdown validations and the ontology reference sheets.

    - Values are written into the Value column of matching (group, key) rows.
      Value cells of template rows without metadata are cleared.
    - Fields not present in the template are appended below the existing rows.
    - Data collaborators fill the template's collaborator rows in order; extra
      collaborators are appended.
    - AssayConditions keeps the template columns; extra condition keys are added
      as new columns and existing data rows are replaced.

    :param metadata: MIHCSMEMetadata object to export
    :param output_path: Path to output Excel file, or a file-like object (e.g., BytesIO)
    :param template_path: Optional custom template; defaults to the bundled
        LEI-MIHCSME template
    """
    template = Path(template_path) if template_path else DEFAULT_TEMPLATE_PATH
    wb = load_workbook(template)

    sections = {
        "InvestigationInformation": metadata.investigation_information,
        "StudyInformation": metadata.study_information,
        "AssayInformation": metadata.assay_information,
    }
    for sheet_name, section in sections.items():
        if sheet_name not in wb.sheetnames:
            raise ValueError(f"Template is missing required sheet '{sheet_name}'")
        groups = section.groups if section else {}
        _fill_grouped_sheet(wb[sheet_name], groups)

    if "AssayConditions" not in wb.sheetnames:
        raise ValueError("Template is missing required sheet 'AssayConditions'")
    _fill_assay_conditions(wb["AssayConditions"], metadata.assay_conditions)

    wb.save(output_path)

write_metadata_to_excel(metadata: MIHCSMEMetadata, output_path: Union[Path, BinaryIO]) -> None #

Write MIHCSME metadata to Excel file.

All sheets are always written, even if empty, so the file can be used as a template. The AssayConditions sheet uses default column headers when no conditions are present.

:param metadata: MIHCSMEMetadata object to export :param output_path: Path to output Excel file, or a file-like object (e.g., BytesIO)

Source code in src/mihcsme_py/writer.py
def write_metadata_to_excel(
    metadata: MIHCSMEMetadata, output_path: Union[Path, BinaryIO]
) -> None:
    """
    Write MIHCSME metadata to Excel file.

    All sheets are always written, even if empty, so the file can be used as
    a template. The AssayConditions sheet uses default column headers when no
    conditions are present.

    :param metadata: MIHCSMEMetadata object to export
    :param output_path: Path to output Excel file, or a file-like object (e.g., BytesIO)
    """
    wb = Workbook()
    # Remove default sheet
    if "Sheet" in wb.sheetnames:
        wb.remove(wb["Sheet"])

    # Write Investigation Information (always)
    groups = metadata.investigation_information.groups if metadata.investigation_information else {}
    _write_grouped_sheet(
        wb,
        "InvestigationInformation",
        groups,
        header_comment="# Investigation Information - Metadata about the overall investigation"
    )

    # Write Study Information (always)
    groups = metadata.study_information.groups if metadata.study_information else {}
    _write_grouped_sheet(
        wb,
        "StudyInformation",
        groups,
        header_comment="# Study Information - Metadata about the study design"
    )

    # Write Assay Information (always)
    groups = metadata.assay_information.groups if metadata.assay_information else {}
    _write_grouped_sheet(
        wb,
        "AssayInformation",
        groups,
        header_comment="# Assay Information - Metadata about the assay protocol"
    )

    # Write Assay Conditions (always)
    _write_assay_conditions(wb, metadata.assay_conditions)

    # Write Reference Sheets
    for ref_sheet in metadata.reference_sheets:
        _write_reference_sheet(wb, ref_sheet.name, ref_sheet.data)

    # Save workbook
    wb.save(output_path)