Skip to main content
Version: Next

Calibration

Version: v3.1.0 Status: Normative (text), Illustrative (diagrams only) Scope: Assay calibration lifecycle management within Config Mode Domain: CALIB

Statement​

The system shall provide a complete calibration management interface within Config Mode, enabling authorized users to perform target-specific calibration workflows including run selection, interactive chart visualization (2D/3D), observation management, calibration record lifecycle operations (create, activate, cancel, delete), recalibration from historical data, and real-time status updates via WebSocket events.

Calibration is a specialized configuration domain introduced in v3.1.0 under BT-2456. It provides the tooling for laboratory personnel to set and maintain classification boundaries (positivity ranges defined by min/max Dilution Factor values) using historical run observation data visualized in interactive Plotly.js scatter plots. The calibration lifecycle is event-driven: background calibration jobs broadcast progress via WebSocket, and failure notifications are delivered in-app and via email.

Behavior Overview (Illustrative)​

This diagram illustrates the high-level calibration workflow. It does not specify UI layout, styling, or interaction details.

Definitions​

TermDefinition
CalibrationThe process of setting classification boundaries (positivity range) for a target using historical run observation data
Calibration RecordA persistent record of a calibration attempt, tracking status (CALIBRATING, CALIBRATED, FAILED, CANCELLED), observations used, and resulting BSON file
Active CalibrationThe currently active calibration for a target; its BSON file is stored in S3 and referenced by the target's calibration_file_path
DF (Dilution Factor)A computed value used to define the positivity range; min_df and max_df together define the classification boundary
ObservationA data point from a calibrated run, representing a single well/target measurement plotted on the calibration chart
RecalibrationCreating a new calibration using observations from a previous calibration, excluding manually excluded observations
Calibratable RunA run that has not yet been used in a calibration for the selected target and is eligible for new calibration
Plotly.jsJavaScript charting library used for rendering 2D and 3D scatter plot visualizations
WebSocket ChannelRun.Calibrate Laravel Echo channel used for real-time calibration event broadcasting

Functional Requirements​

Calibration Tab Navigation (REQ-CALIB-001)​

FR-CALIB-001 Provide Calibration Tab in Config Mode Navigation​

The system shall provide a Calibration tab as the last item in the Config Mode hierarchical tab navigation, accessible when a mix is selected.

Acceptance Criteria:

  • Display "Calibration" as the last tab in the hierarchical tab list (top-level, no nesting)
  • Render the Calibration page content in the right (2/3) panel when the tab is selected
  • Require a mix to be selected before displaying the Calibration tab content

Trace: Source: 3.1.0-Calibration Page (Row 1) | Jira: BT-2456 | Tests: See REQ-CALIB-001 Tests

Target Selection (REQ-CALIB-002, REQ-CALIB-003)​

FR-CALIB-002 Provide Target Selector for Calibration​

The system shall provide a target selector dropdown on the Calibration page to choose the PCR target for calibration operations.

Acceptance Criteria:

  • Display a target dropdown listing all targets from the currently selected mix(es)
  • Display a yellow warning "Please select a target using the filter" when no target is selected
  • Disable the "Select runs for Generate chart" and "Select runs for Calibrate" buttons when no target is selected

Trace: Source: 3.1.0-Calibration Page (Row 2) | Jira: BT-2456 | Tests: See REQ-CALIB-002 Tests

FR-CALIB-003 Provide Targets Summary Widget​

The system shall provide a collapsible "Targets Summary" widget panel displaying all site targets with their calibration statuses.

Acceptance Criteria:

  • Display a "Targets Summary" tab button that toggles a collapsible panel
  • Show all site targets with their calibration status (NON_CALIBRATED, CALIBRATING, CALIBRATED)
  • Support expanding each target row to show individual calibration records with active status, name, completion date, and status badge
  • Allow clicking a calibration record in the Targets Summary to load that calibration's observation data into the chart

Trace: Source: 3.1.0-Calibration Page (Row 3) | Jira: BT-2456 | Tests: See REQ-CALIB-003 Tests

Run Selection (REQ-CALIB-004, REQ-CALIB-005)​

FR-CALIB-004 Select Runs for Chart Generation​

The system shall allow users to select previously calibrated runs for visualization on the calibration chart.

Acceptance Criteria:

  • Provide a "Select runs for Generate chart" button that opens a modal listing calibrated runs for the selected target
  • Display runs with checkboxes for multi-selection
  • Render observations from only the selected runs on the chart when "Generate chart" is clicked
  • Disable the button when no target is selected

Trace: Source: 3.1.0-Calibration Page (Row 4) | Jira: BT-2456 | Tests: See REQ-CALIB-004 Tests

FR-CALIB-005 Select Runs for Calibration​

The system shall allow users to select runs and initiate a new calibration or recalibration process.

Acceptance Criteria:

New Calibration:

  • Provide a "Select runs for Calibrate" button that opens a modal listing calibratable (not-yet-calibrated) runs with checkboxes
  • Provide a calibration name field auto-generated as calibration_YYYY_MM_DD_hh_mm_ss (editable, max 255 characters)
  • Provide a "Use machine results to calibrate" checkbox option
  • Provide a "Hide invert sigmoid" checkbox option
  • Require confirmation dialog before dispatching the calibration job
  • Display a toast notification "calibration started" upon successful dispatch
  • Create a new calibration record with status CALIBRATING in the Calibrations table

Button State:

  • Disable the "Select runs for Calibrate" button when no target is selected

Trace: Source: 3.1.0-Calibration Page (Row 5) | Jira: BT-2456 | Tests: See REQ-CALIB-005 Tests

Calibration Chart (REQ-CALIB-006, REQ-CALIB-007, REQ-CALIB-008)​

FR-CALIB-006 Display Calibration Chart​

The system shall display calibration observations in an interactive 2D scatter plot using Plotly.js, with an optional 3D mode.

Acceptance Criteria:

  • Render a 2D scatter plot as the default chart mode showing calibration observations from selected runs
  • Support toggling to a 3D scatter plot visualization
  • Display a yellow message "No calibrated runs for selected target" when no calibrated runs exist for the selected target
  • Support interactive data point selection for observation exclusion (REQ-CALIB-008)

Trace: Source: 3.1.0-Calibration Page (Row 6) | Jira: BT-2456 | Tests: See REQ-CALIB-006 Tests

FR-CALIB-007 Provide Draggable DF Lines for Positivity Range Adjustment​

The system shall provide draggable min/max DF (Dilution Factor) lines on the 2D chart to allow users to adjust the positivity range and persist changes.

Acceptance Criteria:

  • Display two vertical draggable lines representing min_df and max_df on the 2D chart
  • Show a save/discard control (PositivityChangeHandler) when DF values are changed by dragging
  • Persist min/max DF changes to the target via PUT targets/{target_id} API when the user clicks "Persist"
  • Discard DF changes and revert lines to original positions when the user clicks "Discard"
  • Display the message "To change Positivity Range switch to 2D mode" when the chart is in 3D mode; DF lines shall not be draggable in 3D mode

Trace: Source: 3.1.0-Calibration Page (Row 7) | Jira: BT-2456 | Tests: See REQ-CALIB-007 Tests

FR-CALIB-008 Exclude Observations from Calibration​

The system shall allow users to exclude individual observations from calibration by clicking data points on the chart.

Acceptance Criteria:

  • Display a confirmation dialog "Do you need to remove this observation from Calibration?" when a data point is clicked
  • Remove the excluded observation from the chart visualization and from subsequent recalibration calculations upon confirmation
  • Automatically exclude observations with inverted sigmoid curves when "Hide invert sigmoid" is enabled in the calibration modal

Trace: Source: 3.1.0-Calibration Page (Row 8) | Jira: BT-2456 | Tests: See REQ-CALIB-008 Tests

Chart Settings (REQ-CALIB-009)​

FR-CALIB-009 Provide Chart Settings Panel​

The system shall provide a settings panel for configuring calibration chart display options including axis representation, run highlighting, and legend controls.

Acceptance Criteria:

Axis Configuration:

  • Provide X axis and Y axis representation selectors
  • Provide a Z axis representation selector when in 3D mode
  • Enforce that each axis option can only be used once (selecting an option for one axis makes it unavailable for other axes)
  • Support axis options: Positivity (f_x), PcrAi CT, F[y], PcrAi RFU, Machine RFU, Machine CT, F[z], DF

Chart Controls:

  • Provide a Run Highlighter to highlight specific runs in the chart
  • Provide a CLS Discrepancy toggle
  • Provide a Chart Legend display
  • Re-render the chart when any setting is changed

Trace: Source: 3.1.0-Calibration Page (Row 9) | Jira: BT-2456 | Tests: See REQ-CALIB-009 Tests

Outdated Calibration Warning (REQ-CALIB-010)​

FR-CALIB-010 Display Outdated Calibration Warning​

The system shall display a warning banner when the user is viewing a historical calibration that is neither the active nor the latest calibration for the target.

Acceptance Criteria:

  • Display a yellow banner with text "Outdated calibration data is showing !" when the selected calibration is neither the active calibration nor the latest calibration
  • Provide a "Show up-to-date calibration" button that resets the chart to display the latest calibration data
  • Provide a "Recalibrate" button that opens the calibration modal in recalibration mode (see REQ-CALIB-019)

Trace: Source: 3.1.0-Calibration Page (Row 10) | Jira: BT-2456 | Tests: See REQ-CALIB-010 Tests

Calibrations Table (REQ-CALIB-011)​

FR-CALIB-011 Display Calibrations Table​

The system shall display a table listing all calibration records for the selected target, supporting record management operations.

Acceptance Criteria:

Display:

  • Display all calibration records for the selected target ordered newest first (by created_at descending)
  • Display columns: Active (checkmark icon), Calibration Name, Calibrated At, Status (color-coded dot + label), Actions
  • Display "No records available." when no calibration records exist for the selected target

Status Badges:

  • Display CALIBRATING status with a blue dot indicator
  • Display CALIBRATED status with a green dot indicator
  • Display FAILED status with a red dot indicator
  • Display CANCELLED status with a yellow dot indicator

Trace: Source: 3.1.0-Calibration Page (Row 11, Row 12) | Jira: BT-2456 | Tests: See REQ-CALIB-011 Tests

Calibration Record Operations (REQ-CALIB-013, REQ-CALIB-014, REQ-CALIB-015, REQ-CALIB-016)​

FR-CALIB-013 Activate Calibration​

The system shall allow users to activate a completed calibration, setting it as the active calibration for the target.

Acceptance Criteria:

  • Allow activation by clicking the active status icon on a CALIBRATED calibration row
  • Mark the selected calibration as active and deactivate all other calibrations for the target
  • Move the calibration BSON file from local storage to S3 (s3-calibration disk, os/ folder) and update the target's calibration_file_path to the S3 URL
  • Invoke POST activate-calibration API endpoint

Trace: Source: 3.1.0-Calibration Page (Row 13) | Jira: BT-2456 | Tests: See REQ-CALIB-013 Tests

FR-CALIB-014 Cancel In-Progress Calibration​

The system shall allow users to cancel a calibration that is currently in progress.

Acceptance Criteria:

  • Display a cancel (X) icon button only on rows with status CALIBRATING
  • Cancel the calibration process and change the status to CANCELLED upon clicking
  • Invoke DELETE assay-calibration-processes/{processId} API endpoint
  • Hide the cancel button for calibrations with status CALIBRATED, FAILED, or CANCELLED

Trace: Source: 3.1.0-Calibration Page (Row 14) | Jira: BT-2456 | Tests: See REQ-CALIB-014 Tests

FR-CALIB-015 Delete Non-Active Calibration Records​

The system shall allow users to delete calibration records that are neither active nor in-progress.

Acceptance Criteria:

  • Display a delete (trash) icon button for non-active, non-in-progress calibration rows
  • Display a confirmation dialog "This will remove the calibration." with OK/Cancel options before deletion
  • Soft-delete the calibration record and remove it from the table upon confirmation
  • Hide the delete button for active calibrations and in-progress calibrations

Trace: Source: 3.1.0-Calibration Page (Row 15) | Jira: BT-2456 | Tests: See REQ-CALIB-015 Tests

FR-CALIB-016 Load Historical Calibration Data on Row Click​

The system shall load a calibration's observation data into the chart when the user clicks a calibration row in the Calibrations table.

Acceptance Criteria:

  • Update the chart to display observation data from the selected calibration when a row is clicked
  • Visually highlight the selected row in the table
  • Update the chart when a different calibration row is selected

Trace: Source: 3.1.0-Calibration Page (Row 16) | Jira: BT-2456 | Tests: See REQ-CALIB-016 Tests

Real-Time Updates (REQ-CALIB-017, REQ-CALIB-018)​

FR-CALIB-017 Receive Real-Time WebSocket Calibration Updates​

The system shall receive real-time calibration status updates via WebSocket events on the Run.Calibrate channel and refresh the UI accordingly.

Acceptance Criteria:

  • Listen for AssayCalibrationStarted events and refresh target statuses
  • Listen for AssayCalibrationCompleted events and refresh target statuses, calibrated runs, calibratable runs, and target details
  • Listen for AssayCalibrationUpdated events and refresh target statuses
  • Listen for AssayCalibrationCanceled events and refresh target statuses
  • Refresh the Calibrations table and chart data automatically without requiring page reload

Trace: Source: 3.1.0-Calibration Page (Row 17) | Jira: BT-2456 | Tests: See REQ-CALIB-017 Tests

FR-CALIB-018 Send Failed Calibration Notification​

The system shall notify the user when a calibration job fails, via both in-app notification and email.

Acceptance Criteria:

  • Send an in-app notification (AssayCalibrationFailed) when a calibration process fails
  • Send an email notification (AssayCalibrationFailedMail) to the user who initiated the calibration
  • Update the calibration record status to FAILED in the Calibrations table

Trace: Source: 3.1.0-Calibration Page (Row 18) | Jira: BT-2456 | Tests: See REQ-CALIB-018 Tests

Recalibration (REQ-CALIB-019)​

FR-CALIB-019 Support Recalibration from Historical Observations​

The system shall allow users to create a new calibration using observations from a previous calibration, excluding manually excluded observations.

Acceptance Criteria:

  • Allow recalibration via the "Recalibrate" button on the outdated calibration warning banner
  • Open the calibration modal in recalibration mode, pre-populated with observation IDs from the selected calibration (excluding manually excluded observations)
  • Dispatch a new calibration job via POST recalibrate-runs with the observation_ids array
  • Create a new calibration record in the Calibrations table upon dispatch

Trace: Source: 3.1.0-Calibration Page (Row 19) | Jira: BT-2456 | Tests: See REQ-CALIB-019 Tests

Help Data (REQ-CALIB-020)​

FR-CALIB-020 Provide Help Data Toggle​

The system shall provide a "Help Data" toggle button on the Calibration page when the help_items feature flag is enabled.

Acceptance Criteria:

  • Display a Help Data button (PushIconButton with help icon) when the help_items feature flag is enabled
  • Toggle the HelpWidget component for the "Assay Calibrations" page on click
  • Hide the Help Data button when the help_items feature flag is disabled

Trace: Source: 3.1.0-Calibration Page (Row 20) | Jira: BT-2456 | Tests: See REQ-CALIB-020 Tests

Configuration Options​

OptionDefaultDescriptionAffects
help_itemsfalseEnable/disable the Help Data toggle buttonREQ-CALIB-020
calibration_file_pathnullS3 URI for the active calibration BSON file (per target)REQ-CALIB-013

Assumptions​

  • Users accessing the Calibration tab require SUPER_ADMIN or CLIENT_CONFIG role (Config Mode access control)
  • A mix must be selected in the Config Mode sidebar before the Calibration tab displays content
  • A target must be selected from the dropdown before chart generation or calibration operations can proceed
  • The Run.Calibrate WebSocket channel is available and connected for real-time updates
  • S3 storage (s3-calibration disk) is configured and accessible for calibration file persistence
  • Plotly.js is bundled with the frontend application for chart rendering
  • Background calibration jobs run asynchronously and broadcast status events via Laravel Echo
  • Email delivery is configured for failed calibration notifications (AssayCalibrationFailedMail)

UI Notes (Illustrative)​

FR-CALIB-001 UI Specifications​

  • Calibration is the last tab in the Config Mode hierarchical tree (no sub-tabs)
  • The AssayCalibration.vue component is rendered inside ConfigHome.vue

FR-CALIB-003 UI Specifications​

  • Targets Summary panel uses CalibrationWidgetsList component with pin/unpin toggle
  • CalibrationTargetsTable shows expandable rows per target

FR-CALIB-006 UI Specifications​

  • Chart minimum height: 572px
  • Background: transparent blue (light/dark mode aware)
  • 2D uses Plotly2D, 3D uses Plotly3D components
  • Toggle between 2D and 3D via a mode switch control

FR-CALIB-007 UI Specifications​

  • DF lines are vertical draggable lines on the 2D chart
  • PositivityChangeHandler widget appears with "Discard" and "Persist" buttons when DF values change

FR-CALIB-009 UI Specifications​

  • Settings panel accessible via a cog icon button positioned absolute top-right of chart
  • CalibrationChartSettings component contains axis selectors, run highlighter, CLS toggle, and legend

FR-CALIB-011 UI Specifications​

  • Table title: "CALIBRATIONS" (uppercase, centered)
  • OngoingCalibrationTable component renders below the chart
  • Status badges use colored dots: blue (CALIBRATING), green (CALIBRATED), red (FAILED), yellow (CANCELLED)

Implementation (Illustrative)​

ComponentTypePathRequirements
AssayCalibrationVue Viewresources/frontend/src/views/AssayCalibration.vueREQ-CALIB-001 through REQ-CALIB-020
CalibrationChartVue Componentresources/frontend/src/components/calibrations/CalibrationChart.vueREQ-CALIB-006, REQ-CALIB-007, REQ-CALIB-008
CalibrationChartSettingsVue Componentresources/frontend/src/components/calibrations/CalibrationChartSettings.vueREQ-CALIB-009
OngoingCalibrationTableVue Componentresources/frontend/src/components/calibrations/OngoingCalibrationTable.vueREQ-CALIB-011, REQ-CALIB-013, REQ-CALIB-014, REQ-CALIB-015, REQ-CALIB-016
CalibrationTargetsTableVue Componentresources/frontend/src/components/calibrations/CalibrationTargetsTable.vueREQ-CALIB-003
CalibrationWidgetsListVue Componentresources/frontend/src/components/calibrations/CalibrationWidgetsList.vueREQ-CALIB-003
PositivityChangeHandlerVue Componentresources/frontend/src/components/calibrations/PositivityChangeHandler.vueREQ-CALIB-007
RunsModelVue Componentresources/frontend/src/components/calibrations/RunsModel.vueREQ-CALIB-004
CalibrationModelVue Componentresources/frontend/src/components/calibrations/CalibrationModel.vueREQ-CALIB-005, REQ-CALIB-019
AssayCalibrateableRunsControllerControllerapp/Http/Controllers/AssayCalibrations/AssayCalibrateableRunsController.phpREQ-CALIB-004, REQ-CALIB-005
AssayCalibrationProcessesControllerControllerapp/Http/Controllers/AssayCalibrations/AssayCalibrationProcessesController.phpREQ-CALIB-014
AssayCalibrationFailedNotificationapp/Notifications/AssayCalibrationFailed.phpREQ-CALIB-018
AssayCalibrationFailedMailMailableapp/Mail/AssayCalibrationFailedMail.phpREQ-CALIB-018

Traceability Matrix​

RequirementTitleVerificationImplementationTest CasesStatus
REQ-CALIB-001Calibration Tab in Config ModeTestAssayCalibration.vue[Pending]Draft
REQ-CALIB-002Target Selector DropdownTestAssayCalibration.vue[Pending]Draft
REQ-CALIB-003Targets Summary WidgetTestCalibrationTargetsTable, CalibrationWidgetsList[Pending]Draft
REQ-CALIB-004Select Runs for ChartTestRunsModel, AssayCalibrateableRunsController[Pending]Draft
REQ-CALIB-005Select Runs for CalibrationTestCalibrationModel, AssayCalibrateableRunsController[Pending]Draft
REQ-CALIB-006Calibration Chart (2D/3D)TestCalibrationChart[Pending]Draft
REQ-CALIB-007Draggable DF LinesTestCalibrationChart, PositivityChangeHandler[Pending]Draft
REQ-CALIB-008Exclude ObservationsTestCalibrationChart[Pending]Draft
REQ-CALIB-009Chart Settings PanelTestCalibrationChartSettings[Pending]Draft
REQ-CALIB-010Outdated Calibration WarningTestAssayCalibration.vue[Pending]Draft
REQ-CALIB-011Calibrations TableTestOngoingCalibrationTable[Pending]Draft
REQ-CALIB-013Activate CalibrationTestOngoingCalibrationTable[Pending]Draft
REQ-CALIB-014Cancel CalibrationTestAssayCalibrationProcessesController[Pending]Draft
REQ-CALIB-015Delete Calibration RecordTestOngoingCalibrationTable[Pending]Draft
REQ-CALIB-016Load Historical CalibrationTestOngoingCalibrationTable[Pending]Draft
REQ-CALIB-017WebSocket Real-Time UpdatesTestAssayCalibration.vue (Echo listener)[Pending]Draft
REQ-CALIB-018Failed Calibration NotificationTestAssayCalibrationFailed, AssayCalibrationFailedMail[Pending]Draft
REQ-CALIB-019RecalibrationTestCalibrationModel[Pending]Draft
REQ-CALIB-020Help Data ToggleTestAssayCalibration.vue[Pending]Draft
note

REQ-CALIB-012 (Calibration status badges) from the inventory was classified as UI_DETAIL and folded into REQ-CALIB-011 as an acceptance criterion of the Calibrations table. This follows the OQ-004 design decision.

Notes​

  • The REQ-CALIB ID sequence skips REQ-CALIB-012. Row 12 from the source inventory (calibration status badges with color-coded indicators) was classified as UI_DETAIL per design decision OQ-004 and incorporated as acceptance criteria of REQ-CALIB-011 (Calibrations Table). The ID gap is intentional and preserved for traceability to the source inventory.
  • Calibration BSON files are initially stored locally during calibration processing, then moved to S3 upon activation (REQ-CALIB-013).
  • The WebSocket event names follow the pattern AssayCalibration* (Started, Completed, Updated, Canceled) on the Run.Calibrate channel.
  • The "Hide invert sigmoid" option in the calibration modal (REQ-CALIB-005) automatically excludes certain observations from the chart (REQ-CALIB-008), providing a shortcut for filtering anomalous data.
  • The chart settings axis constraint (each option used only once) is enforced client-side.

Open Questions​

None at this time.

Acceptance Tests​

Test: REQ-CALIB-001​

Back to requirement

Test: Calibration tab visibility and navigation

Given: User is in Config Mode with a mix selected
When: User views the tab list in the left panel
Then: "Calibration" appears as the last tab in the hierarchical tree
When: User clicks the "Calibration" tab
Then: The Calibration page content is displayed in the right (2/3) panel

Test: REQ-CALIB-002​

Back to requirement

Test: Target selector and warning display

Given: User is on the Calibration tab with a mix selected
When: No target is selected
Then: A yellow warning "Please select a target using the filter" is displayed
And: "Select runs for Generate chart" button is disabled
And: "Select runs for Calibrate" button is disabled
When: User selects a target from the dropdown
Then: The warning is dismissed and both buttons become enabled

Test: REQ-CALIB-003​

Back to requirement

Test: Targets Summary widget interaction

Given: User is on the Calibration tab
When: User clicks the "Targets Summary" tab button
Then: A collapsible panel opens showing all targets with their calibration statuses
When: User expands a target row
Then: Individual calibration records are displayed with active status, name, completion date, and status badge
When: User clicks on a calibration record in the Targets Summary
Then: The chart updates to display that calibration's observation data

Test: REQ-CALIB-004​

Back to requirement

Test: Select runs and generate chart

Given: User has a target selected
When: User clicks "Select runs for Generate chart"
Then: A modal opens listing all calibrated runs for the selected target with checkboxes
When: User selects specific runs and clicks "Generate chart"
Then: The chart renders observations from only the selected runs

Test: REQ-CALIB-005​

Back to requirement

Test: Start new calibration process

Given: User has a target selected
When: User clicks "Select runs for Calibrate"
Then: A modal opens listing calibratable runs with checkboxes, a calibration name field, "Use machine results" and "Hide invert sigmoid" options
When: User selects runs and clicks "Calibrate"
And: User confirms in the confirmation dialog
Then: A toast notification "calibration started" appears
And: A new calibration record appears in the Calibrations table with status CALIBRATING

Test: REQ-CALIB-006​

Back to requirement

Test: Chart rendering in 2D and 3D modes

Given: User has a target selected and calibrated runs are available
When: The chart is rendered
Then: A 2D scatter plot is displayed showing calibration observations
When: User toggles "3D Mode" on
Then: The chart switches to a 3D scatter plot visualization
Given: No calibrated runs exist for the selected target
When: The chart area is rendered
Then: A yellow message "No calibrated runs for selected target" is displayed

Test: REQ-CALIB-007​

Back to requirement

Test: DF line adjustment and persistence

Given: User is viewing the 2D chart
When: User drags the min DF or max DF line to a new position
Then: A save/discard control appears
When: User clicks "Persist"
Then: The target's min/max DF values are updated and the chart reflects the new positivity range
Given: User is in 3D mode
When: The chart is displayed
Then: A message "To change Positivity Range switch to 2D mode" is shown and DF lines are not draggable

Test: REQ-CALIB-008​

Back to requirement

Test: Observation exclusion workflow

Given: User clicks on a data point in the calibration chart
When: A confirmation dialog appears
Then: User can confirm to exclude the observation or cancel
When: User confirms the exclusion
Then: The observation is removed from the chart and from subsequent recalibration calculations

Test: REQ-CALIB-009​

Back to requirement

Test: Chart settings axis configuration

Given: User clicks the cog icon button on the chart
When: The settings panel opens
Then: X axis, Y axis selectors, Run Highlighter, CLS Discrepancy toggle, and Chart Legend are displayed
When: User changes the X axis to "PcrAi CT"
Then: The chart re-renders with the new X axis and "PcrAi CT" is unavailable in Y/Z axis selectors
Given: User is in 3D mode
When: The settings panel is open
Then: A Z axis representation selector is additionally displayed

Test: REQ-CALIB-010​

Back to requirement

Test: Outdated calibration banner and actions

Given: User selects an older calibration from the Calibrations table
When: The selected calibration is not the active or latest one
Then: A yellow banner "Outdated calibration data is showing !" is displayed
And: "Show up-to-date calibration" and "Recalibrate" buttons are available
When: User clicks "Show up-to-date calibration"
Then: The chart resets to display the latest calibration data

Test: REQ-CALIB-011​

Back to requirement

Test: Calibrations table display and status badges

Given: User has a target selected with multiple calibration records
When: The Calibrations table is rendered
Then: All calibration records are listed newest first with Active, Name, Calibrated At, Status, and Actions columns
And: Status badges display colored dots: blue for CALIBRATING, green for CALIBRATED, red for FAILED, yellow for CANCELLED
Given: No calibration records exist
When: The table area is rendered
Then: "No records available." is displayed

Test: REQ-CALIB-013​

Back to requirement

Test: Activate a completed calibration

Given: A calibration record has status CALIBRATED
When: User clicks the active status button on the row
Then: The selected calibration is marked as active
And: The previously active calibration loses its active status
And: The calibration file is stored to S3 and the target's calibration file path is updated

Test: REQ-CALIB-014​

Back to requirement

Test: Cancel an in-progress calibration

Given: A calibration has status CALIBRATING
When: User clicks the cancel (X) icon on the row
Then: The calibration process is cancelled and the status changes to CANCELLED
Given: A calibration has status CALIBRATED or FAILED or CANCELLED
When: User views the actions column
Then: The cancel button is not visible

Test: REQ-CALIB-015​

Back to requirement

Test: Delete a calibration record

Given: User clicks the delete icon on a non-active, non-in-progress calibration
When: Confirmation dialog appears and user clicks "OK"
Then: The calibration record is soft-deleted and removed from the table
Given: A calibration is active or in-progress
When: User views the actions column
Then: The delete button is not visible

Test: REQ-CALIB-016​

Back to requirement

Test: Load historical calibration from table

Given: User clicks on a calibration row in the Calibrations table
When: The calibration is selected
Then: The chart updates to display observation data from that calibration
And: The row is visually highlighted
When: User clicks a different calibration row
Then: The chart updates to reflect the newly selected calibration's data

Test: REQ-CALIB-017​

Back to requirement

Test: Real-time calibration event handling

Given: User is on the Calibration tab
When: A calibration job completes in the background
And: The AssayCalibrationCompleted event is broadcast
Then: The Calibrations table, chart data, and target statuses are automatically refreshed without page reload
When: A calibration is started by another user
And: The AssayCalibrationStarted event is broadcast
Then: The Calibrations table reflects the new in-progress calibration in real-time

Test: REQ-CALIB-018​

Back to requirement

Test: Failed calibration notification delivery

Given: A calibration process fails in the background
When: The failure is detected by the backend
Then: The user receives an in-app notification about the failed calibration
And: The user receives an email notification about the failed calibration
And: The calibration row in the Calibrations table shows a red "FAILED" status badge

Test: REQ-CALIB-019​

Back to requirement

Test: Recalibration from historical data

Given: User is viewing a historical calibration and clicks "Recalibrate" on the warning banner
When: The recalibration is initiated
Then: A new calibration job is dispatched using existing observations minus excluded ones
And: A new calibration record appears in the Calibrations table
Given: User has excluded some observations from the chart before recalibrating
When: Recalibration is triggered
Then: Excluded observations are not included in the recalibration input data

Test: REQ-CALIB-020​

Back to requirement

Test: Help Data toggle visibility

Given: The help_items feature is enabled
When: User is on the Calibration tab
Then: A "Help Data" button is visible
When: User clicks the "Help Data" button
Then: The Help Widget is displayed for the "Assay Calibrations" page
Given: The help_items feature is disabled
When: User views the Calibration tab
Then: The "Help Data" button is not visible
DocumentRelevant Sections
Run View Calibration ChartREQ-RUNRPT-029 through REQ-RUNRPT-037: Run-view calibration chart widget, target selector, current run highlighting, 2D/3D chart, settings panel, draggable DF lines
Config ModeConfig Mode layout, sidebar, and tab navigation that hosts the Calibration tab
Kit ConfigurationREQ-KITCFG-020 through REQ-KITCFG-023: Legacy calibration requirements from v3.0.0
Run View Calibration Chart

The Run View Calibration Chart (9 requirements: REQ-RUNRPT-029 through REQ-RUNRPT-037) is documented in runfile-report.md because it is a Run View widget, not a Config Mode page. Those requirements use the REQ-RUNRPT prefix matching their host document and live in the run file report SRS as their operational context is run analysis, not configuration.

Appendix: Process Artifacts​

Completion Checklist​

  • Statement section present (1-2 paragraphs)
  • Mermaid diagram present and renders without errors
  • Diagram marked as (Illustrative)
  • No "non-normative" text anywhere
  • All REQ-CALIB-* IDs assigned (19 requirements: 001-011, 013-020; 012 folded as UI_DETAIL)
  • All ACs preserved with blank lines before bullet lists
  • All Trace references preserved (Source, Jira, Tests)
  • Error handling documented where applicable
  • Config options have Affects column
  • Tests at end with back-links
  • UI Notes marked (Illustrative)
  • Implementation marked (Illustrative)
  • Appendix has Completion Checklist and Reviewer Notes
  • Related Documentation section includes run-view calibration cross-reference

Reviewer Notes​

Initial Creation -- v3.1.0

This document was created as a new SRS domain file for v3.1.0, sourced from the Confluence export 3.1.0-Calibration Page (BT-2456, 20 rows).

Classification Decisions:

  1. REQ-CALIB-012 (Calibration status badges): Classified as UI_DETAIL per OQ-004 design decision. Color-coded status badges are presentation details, not independently testable behavior. Folded into REQ-CALIB-011 (Calibrations Table) as acceptance criteria for status display. The REQ-CALIB-012 ID is intentionally skipped to maintain traceability to the source inventory row numbering.

Relationship to Legacy Requirements:

The v3.0.0 SRS documented calibration under kitcfg.md as REQ-KITCFG-020 through REQ-KITCFG-023. The v3.1.0 calibration domain (this file) is a complete rewrite of the calibration UI within Config Mode, replacing the legacy Assay Configurations-based calibration interface. The legacy REQ-KITCFG-020 through REQ-KITCFG-023 requirements describe the underlying calibration analysis and boundary management behavior which remains valid; this document describes the new Config Mode UI and workflow layered on top.

Version History:

VersionDateDescription
v3.1.02026-03-06Initial creation -- 19 requirements from BT-2456 Confluence export