Safety and interlocks

Cause and Effect Matrix <smart-cause-effect-matrix>

CauseEffectMatrix displays the cause and effect chart of a safety instrumented system as a live matrix.

<smart-cause-effect-matrix> · 8 properties, 4 methods, 4 events · source/modules/smart.causeeffectmatrix.js

Usage in JavaScript

The component is a custom element: its properties are set on the element, its events are DOM CustomEvents with the data in event.detail, and its methods are called on the element. The properties can also be written as attributes in kebab case (precision-digits="1").

const causeEffectMatrix = document.querySelector('smart-cause-effect-matrix');

causeEffectMatrix.label = 'Unit 200 SIS';
causeEffectMatrix.addEventListener('selectionChange', (event) => console.log(event.detail));
causeEffectMatrix.linksFor('value');

Properties

Property	Type, default	Description
causes	array	Sets or gets the rows: { id, tag, label, active, bypassed, activeSince }. An active cause tints its row; a bypassed one is marked and does not count towards an expected trip. active and bypassed written as the text "false", "0", "no" or "off" are false. activeSince (a Date, epoch milliseconds or ISO text) is when the cause became active, used for timed trips; without it the component counts from when it first saw the cause active. Entries that are not objects are ignored. Assign a new array to update the component; the keyboard stays on the same cell across an update.
effects	array	Sets or gets the columns: { id, tag, label, tripped }. A tripped effect tints its column. tripped written as the text "false", "0", "no" or "off" is false.
matrix	array	Sets or gets the links: { cause, effect, mark, delay, note }. mark is X, T, P, A or any short text the marks property explains; delay is the seconds of a timed trip: a tripping link with a delay is expected only once its cause has been active that long, and until then the effect is shown as 'timed trip due in N s' (a dashed outline), not as a discrepancy; the component redraws itself when the trip falls due. note is read with the cell.
marks	object?	Sets or gets the meaning of the marks: { X: { label, trips } }, where trips says whether the mark means the effect is expected when the cause is active. Null is the standard set: X trip, T timed trip, P permissive, A alarm only. An object replaces the standard set; a mark it does not list, or an entry without trips: false, counts as a trip.
selected	object?	Sets or gets the selected cell as { cause, effect }, or null.
label	string	Sets or gets the name of the system, part of the accessible name.
showLegend	boolean true	Sets or gets whether the marks in use and the three states are explained under the chart.
highlightActive	boolean true	Sets or gets whether the rows of active causes and the columns of tripped effects are tinted.

Methods

Method	Description
linksFor(causeId) returns any[]	Returns the links of a cause, as given, each with its effect id. causeId string The cause's id.
causesOf(effectId) returns any[]	Returns the links to an effect, as given, each with its cause id. effectId string The effect's id.
expected(effectId) returns boolean	Returns whether an effect is expected to be tripped now: an active, unbypassed cause links to it with a mark that trips, and, for a link with a delay, the cause has been active for at least that delay. effectId string The effect's id.
discrepancies() returns any[]	Returns the effects whose state does not match the chart, as [{ effect, expected, tripped }]: expected to trip but not tripped, or tripped with no active cause. An effect whose timed trip is still counting down is not a discrepancy.

Events

The data of an event is in event.detail. The cause and effect matrix sets selected when the operator clicks or focuses a cell and then raises selectionChange. cellClick, causeClick and effectClick report what was clicked and change nothing.

Event	Description and detail
selectionChange	This event is triggered when a different cell is selected by a click or by keyboard focus. Setting the selected property does not raise it. cause string The cause's id. effect string The effect's id. mark string The link's mark, or null where there is no link. link object The link as it was given, or null.
cellClick	This event is triggered when a cell is clicked, or Enter or Space is pressed on it. cause string The cause's id. effect string The effect's id. mark string The link's mark, or null where there is no link. link object The link as it was given, or null.
causeClick	This event is triggered when a cause's header is clicked. cause string The cause's id. links any[] Its links, each with its effect id.
effectClick	This event is triggered when an effect's header is clicked. effect string The effect's id. causes any[] The links to it, each with its cause id. expected boolean Whether the chart expects it to be tripped now.

CSS variables

The component declares 13 CSS variables; the CSS page shows how to set them.

--smart-cem-cell-size --smart-cem-cause-width --smart-cem-cause-max --smart-cem-effect-height --smart-cem-effect-max --smart-cem-gap --smart-cem-active --smart-cem-tripped --smart-cem-ok --smart-cem-panel --smart-cem-header --smart-cem-border --smart-cem-line