nexusLIMS.builder.record_builder

Build Nexus records from metadata and datasets.

Builds NexusLIMS records.

ivar XSD_PATH:

A string containing the path to the Nexus Experiment schema file, which is used to validate XML records built by this module

Module Contents

Classes

RecordBuildResult

Result of building a NexusLIMS XML record.

Functions

build_record	Build a NexusLIMS XML record of an Experiment.
get_reservation_event	Get a ReservationEvent representation of a Session.
build_acq_activities	Build an XML string representation of each AcquisitionActivity for a session.
get_files	Get files under a path that were last modified between the two given timestamps.
dump_record	Dump a record to an XML file.
validate_record	Validate an .xml record against the Nexus schema.
build_new_session_records	Build records for new sessions from the database.
process_new_records	Process new records (this is the main entrypoint to the record builder).
dry_run_file_find	Get the files that would be included for a record built for the supplied session.

Data

XSD_PATH

API

nexusLIMS.builder.record_builder.XSD_PATH

Type: pathlib.Path

class nexusLIMS.builder.record_builder.RecordBuildResult

Result of building a NexusLIMS XML record.

Parameters:

• xml_text – The serialized XML record string

• activities – The AcquisitionActivity objects built during record construction

• reservation_event – The ReservationEvent used to populate the record header

xml_text

Type: str

activities

‘field(…)’

Type: typing.List[nexusLIMS.schemas.activity.AcquisitionActivity]

reservation_event

Type: nexusLIMS.harvesters.reservation_event.ReservationEvent | None

nexusLIMS.builder.record_builder.build_record(session: Session, sample_id: str | None = None, *, generate_previews: bool = True) → RecordBuildResult

Build a NexusLIMS XML record of an Experiment.

Construct an XML document conforming to the NexusLIMS schema from a directory containing microscopy data files. Accepts either a Session object or an Instrument and date range (for backwards compatibility). For calendar parsing, currently no logic is implemented for a query that returns multiple records.

Parameters:

• session – A Session or None. If a value is provided, instrument, dt_from, dt_to and user will be ignored, and the values from the Session object will be used instead

• sample_id – A unique identifier pointing to a sample identifier for data collected in this record. If None, a UUIDv4 will be generated

• generate_previews – Whether to create the preview thumbnail images

Returns:

result – A RecordBuildResult containing the XML string, activities, and reservation event

Return type:

RecordBuildResult

nexusLIMS.builder.record_builder.get_reservation_event(session: Session) → ReservationEvent

Get a ReservationEvent representation of a Session.

Handles the abstraction of choosing the right “version” of the res_event_from_session method from the harvester specified in the instrument database. This allows for one consistent function name to call a different method depending on which harvester is specified for each instrument (currently just NEMO).

Parameters:

session – The Session for which to fetch a matching ReservationEvent from the relevant harvester

Returns:

res_event – A ReservationEvent representation of a reservation that matches the instrument and timespan specified in session.

Return type:

ReservationEvent

nexusLIMS.builder.record_builder.build_acq_activities(instrument, dt_from, dt_to, generate_previews)

Build an XML string representation of each AcquisitionActivity for a session.

This includes setup parameters and metadata associated with each dataset obtained during a microscopy session. Unique AcquisitionActivities are delimited via clustering of file collection time to detect “long” breaks during a session.

Parameters:

• instrument (Instrument) – One of the NexusLIMS instruments contained in the instrument_db database. Controls what instrument calendar is used to get events.

• dt_from (datetime) – The starting timestamp that will be used to determine which files go in this record

• dt_to (datetime) – The ending timestamp used to determine the last point in time for which files should be associated with this record

• generate_previews (bool) – Whether or not to create the preview thumbnail images

Returns:

• activities (list of)

• AcquisitionActivity – The list of AcquisitionActivity objects generated for the record

nexusLIMS.builder.record_builder.get_files(path: Path, dt_from: datetime, dt_to: datetime) → List[Path]

Get files under a path that were last modified between the two given timestamps.

Parameters:

• path – The file path in which to search for files

• dt_from (datetime) – The starting timestamp that will be used to determine which files go in this record

• dt_to (datetime) – The ending timestamp used to determine the last point in time for which files should be associated with this record

Returns:

files – A list of the files that have modification times within the time range provided (sorted by modification time)

Return type:

List[Path]

nexusLIMS.builder.record_builder.dump_record(session: Session, filename: Path | None = None, *, generate_previews: bool = True) → Path

Dump a record to an XML file.

Writes an XML record for a Session composed of information pulled from the appropriate reservation system as well as metadata extracted from the microscope data (e.g. dm3 or other files).

Parameters:

• session (Session) – A Session object representing a unit of time on one of the instruments known to NexusLIMS

• filename (Optional[Path]) – The filename of the dumped xml file to write. If None, a default name will be generated from the other parameters

• generate_previews (bool) – Whether or not to create the preview thumbnail images

Returns:

filename – The name of the created record that was returned

Return type:

Path

nexusLIMS.builder.record_builder.validate_record(xml_filename)

Validate an .xml record against the Nexus schema.

Parameters:

xml_filename (str or StringIO or BytesIO) – The path to the xml file to be validated (can also be a file-like object like StringIO or BytesIO)

Returns:

validates – Whether the record validates against the Nexus schema

Return type:

bool

nexusLIMS.builder.record_builder.build_new_session_records(generate_previews: bool = True) → tuple[List[Path], List[Session], List[List[AcquisitionActivity]], List[ReservationEvent | None]]

Build records for new sessions from the database.

Uses get_sessions_to_build()) and builds those records using build_record() (saving to the NexusLIMS folder), and returns a list of resulting .xml files to be uploaded to CDCS.

Returns:

• xml_files (typing.List[pathlib.Path]) – A list of record files that were successfully built and saved to centralized storage

• sessions_built (typing.List[Session]) – Corresponding Session objects for each built XML file (same length and order)

• activities_built (typing.List[typing.List[AcquisitionActivity]]) – Corresponding AcquisitionActivity lists for each built session

• res_events_built (typing.List[ReservationEvent | None]) – Corresponding ReservationEvent for each built session

nexusLIMS.builder.record_builder.process_new_records(*, dry_run: bool = False, dt_from: datetime | None = None, dt_to: datetime | None = None)

Process new records (this is the main entrypoint to the record builder).

Using build_new_session_records(), process new records, save them to disk, and upload them to the NexusLIMS CDCS instance.

Parameters:

• dry_run – Controls whether or not records will actually be built. If True, session harvesting and file finding will be performed, but no preview images or records will be built. Can be used to see what would happen if dry_run is set to False.

• dt_from – The point in time after which sessions will be fetched. If None, no date filtering will be performed. This parameter currently only has an effect for the NEMO harvester.

• dt_to – The point in time before which sessions will be fetched. If None, no date filtering will be performed. This parameter currently only has an effect for the NEMO harvester.

nexusLIMS.builder.record_builder.dry_run_file_find(s: Session) → List[Path]

Get the files that would be included for a record built for the supplied session.

Parameters:

s (Session) – A session read from the database

Returns:

files – A list of Paths containing the files that would be included for the record of this session (if it were not a dry run)

Return type:

List[Path]