Build a lab status report for a project
Return a point-in-time lab operations report, rendered as Markdown.
Covers momentum over the trend window, utilization (whole lab, per site,
per program, and against yesterday), channels released in the recent past,
channels forecast to free up soon, the planned measurements queued next,
plans that should already have started, equipment service — channels and
whole cyclers out, calibration falling due, and booked visits — and healthy
channels sitting idle. The response
carries every section as structured data and the whole thing as a
Markdown document in markdown, so a caller can convert it to PDF or
paste it into a message without re-deriving anything.
This endpoint only builds the report; it does not deliver it anywhere.
Path Parameters
Query Parameters
Sections to include. Repeat the parameter for several. Omit for the full report.
The selectable sections of a lab report.
Used both as the sections query parameter on the report endpoint and as
the key for the corresponding field on :class:LabReport.
highlights, utilization, recently_stopped, stopping_soon, past_due, queue, unscheduled_requests, maintenance, idle_channels Lookback for stopped channels
1 <= x <= 2160Forecast window for channels freeing up
1 <= x <= 2160Idle thresholds in days, e.g. 2 and 3. Channels past the lowest are listed; the rest become counts. Defaults to 2 and 3.
1 <= x <= 365Maximum queued measurements to list
1 <= x <= 200How far ahead the queue looks
1 <= x <= 365How far ahead booked service is reported
1 <= x <= 365Length of the momentum trend window
1 <= x <= 90Response
Successful Response
A rendered lab operations report plus the data behind it.
markdown is the whole report as a document (the intended payload for
PDF conversion or messaging); the structured sections are the same content
unformatted, for consumers that want to re-render or post-process it.
Sections not requested are None.
Project the report covers
Server time the report was generated (UTC)
The parameters this report was built with
The full report rendered as Markdown
Project name
Organization the project belongs to
Email of the user the report was generated for
Momentum: what the lab produced over the trend window, and how hard it ran.
Two subjects only — output (channel-hours, tests started and finished)
and the utilization trend — both reconstructed by replaying measurement
intervals. Equipment service lives in :class:MaintenanceSection instead,
beside the channels currently down: repairs are a different subject from
output, and the multi-period repair ladder reaches further back than this
section's window, so presenting it under a "last N days" heading was a
contradiction.
Every point divides by today's channel count, because channels itself
keeps no history: a channel added last week is in the denominator of samples
from before it existed. That makes the shape of the series trustworthy and
its absolute values approximate whenever equipment moved inside the window —
and is why the trend window is capped.
Utilization for the whole project, by site and by program, vs yesterday.
The day-over-day comparison is reconstructed rather than stored: there is no utilization history table, so yesterday's figure is derived by replaying the measurement intervals that were open 24 hours ago. Its denominator is today's channel count, because the equipment tables carry no history either — so a lab that added channels overnight will see a small artificial dip. Over a single day that error is negligible; over months it would not be, which is why nothing here reaches further back than the trend window.
Tests that finished in the lookback window, and what the list left out.
A list rather than a bare count because the useful question is which
channels came free and what was on them. It is capped for the same reason
the other list sections are: recently_stopped_hours reaches back up to
90 days, and a large lab on short protocols finishes thousands of runs in
that time — too many to fetch, hold, or render as one table.
Channels forecast to free up, and what the forecast could not place.
A scheduled release can be missing from the list for two unrelated reasons,
counted separately because they need different responses and would be
uninterpretable summed together: the list hit its cap
(planned_beyond_cap), or the plan has no channel assigned yet
(unassigned_count) and so cannot be attributed to one.
Running tests are bounded by the channel count and so are never capped.
.. note::
Plans that should have started and have not.
Split out of the queue rather than filtered into it. The queue answers "what is coming up", and a plan whose start time has passed is not upcoming work — counting it there both inflates the horizon total and hides the more urgent fact that something slipped. These need a decision (start it, reschedule it, cancel it) rather than a slot.
The near-term queue, with enough context to trust what is missing.
A queue is only meaningful if the reader knows what was left out, so the
section carries its own horizon and totals rather than silently truncating:
total_in_horizon is every plan starting inside the window (not just the
listed ones) and undated_count is the backlog of requests with no date
yet, which have no place in a time-ordered queue but should not vanish.
Bounded on both sides: only plans starting between the report time and the
horizon. A plan whose start time has already passed is not upcoming work and
belongs in :class:PastDueSection.
Requested tests with no slot, longest-waiting first.
Sorted oldest-request-first rather than newest: the point of the section is to surface what has been forgotten, and the request that has waited longest is the one most likely to have been.
Equipment service: what is down, what is due, and what is booked.
Carries the outage list, the repair counts, the calibration schedule, and upcoming visits, because they answer one question together — "are we on top of the equipment?" — and none is much use alone. Six down channels reads very differently next to "eight repaired this week" than next to "none", and a lab that is current on repairs can still be three months overdue on calibration.
Outages are reported at the level the work happens at: a channel-local fault is a channel row, an instrument-level visit is one cycler row carrying its channel count. Without that split, one calibration on a 40-channel cycler would bury every genuine channel fault in the project.
retired_count exists so the section can never silently disagree with the
Lab wall: the wall counts every out-of-commission channel, this section lists
only the ones a repair could return, and without the count the difference
would read as a missing row.
Idle healthy channels, plus a count at each requested threshold.
Rows are every channel past the lowest threshold, longest-idle first; the tier counts then say how many also cross the higher ones (the classic "N idle over 2 days, of which M over 3" phrasing) without listing a channel more than once.