Cycles

Cycles, phases and limits

A rule says where a cycle starts and where it ends. A phase rule does the same inside each cycle (Heating from the start of the batch until the temperature reaches 30 °C). Starts and ends are built from these:

Limits flag a cycle or phase without ever dropping it: late (not over within a time from the cycle’s start), too long and too short. Flags show in the tables and can email someone (see Cycles in the collector).

KPIs: a cycle’s duration always, and per tag any of minimum, maximum, mean, integral, first value, last value and change (last minus first). The mean is the plain mean of the samples; the integral is value × seconds, so a flow in kg/s integrates to kg.

Cut any dataset into cycles

1. Load the data: a file, a folder, a live stream, or a recording or history range from Cloud.
2. In Data, click the dataset’s Cycles button. The library on the left lists your rules: Personal ones first, then one group per project. Click a rule to use it, or Create new cycle to write one; it is listed at once as Not saved yet.
3. In Cycle, give it a name and choose what shows beside each cycle: its duration, or a channel’s change, mean, maximum or minimum over the cycle (the energy used, the peak temperature).
4. In Start and End, each condition is a card: a channel changes, starts over, rises or falls through a value, or compares with a value; a fixed time has passed; the next cycle starts. + Add condition adds another, and All hold or Any holds joins them. Held at least keeps a comparison from firing on a blip.
5. Add limits and KPIs if you need them, and + Phase for a phase inside each cycle. The Preview on the right redraws the cycles this data gives as you edit.
6. Click Show N cycles. The cycles appear under the dataset, each with its value and flags; the arrow beside a cycle shows its phases. Tick the ones to plot: each has a Cycle time column (seconds since its start), so set it as X to lay the runs over each other.

The time a rule measures with is the dataset’s own time column (a column named like Time first), so there is nothing to pick. Remove cycles puts the dataset back as one.

A live stream works the same: its Cycles button cuts it as it streams, and each cycle appears under the stream when it ends, with the running one last.

A file whose channel starts over each cycle (a lap distance, a cycle counter) opens a new rule on that channel already filled in.

The library

Save to library keeps the rule, with its phases and the value beside each cycle, in the place chosen under Saved in. A Personal rule is yours alone and follows you to any workbook and any browser. A rule saved in a project is there for everyone in the project (encrypted with the project’s key when the project is end-to-end encrypted): editors and leads save them, and the author or a lead changes or deletes them. Workbooks never keep rules or cycles, so a workbook opened with other data never brings cycles that don’t belong to it. Show N cycles also works without saving, to try a rule out.

Cycles in the collector (24/7)

Cycles that must be cut with no browser open go in the collector’s cycles: section. The collector runs the rules on the stream as it arrives and stores each cycle and phase with its flags as it closes; the app works out the KPIs when you look. Each rule watches one source that records by itself (record: always, the default, or trigger; see Collector: recording).

cycles:
  - source: Customer A DCS         # a source that records by itself (record: always or trigger)
    name: Batch                    # shown in the app; its id is the name in lowercase unless you give id:
    start: BatchNumber changes
    end: next-start
    at_most: 4h                    # longer is flagged "too long"
    phases:                        # optional; each phase lives inside its cycle
      - name: Heating
        start: parent-start
        end: TIC201 >= 30
        expected_within: 15min     # from the cycle's start; later is flagged "late"
      - name: Reaction
        start: {all: [TIC201 >= 80, PIC102 >= 2.0]}
        min_hold: 5min             # both held 5 min before it starts
        end: {any: [TIC201 < 75, parent-end]}

  - source: Customer A DCS
    name: Shift
    start: {at: ["06:00", "14:00", "22:00"]}   # in recording.timezone
    end: next-start

alerts:                            # optional: an email when a cycle or phase misses a limit
  email: shift.lead@customer.example
  # smtp: {host: mail.customer.local, port: 587, user: kymoscope, password: "file:smtp.txt", from: kymoscope@customer.local}

Durations are written 500ms, 30s, 15min, 4h, or a plain number of seconds.

• Restart the collector after changing the section. Its rules appear in Reports & analysis with (collector), and cycles appear as they close.
• In Cloud, the source is listed by cycle instead of by day, with the limits each one missed. Each cycle opens, exports and is kept like a recording. A cycle still open when the source stopped sending is marked unfinished.
• The live stream carries Batch.number, Batch.start (Unix seconds) and, with phases, Batch.phase (1 for the first phase in collector.yaml, 0 between phases), so a chart or an alert can follow the running cycle.
• Cycles are sent once the source’s history is open (within recording.today_every_min, 15 minutes by default, after a new source starts). While they can’t be sent, they wait on the collector host. A cycle open when the collector stops starts again at the next start.
• A source takes at most 50 cycle and phase rules.
• A collector rule changes only in collector.yaml; remove it there to stop storing its cycles.

Alerts

With alerts:, the collector emails when a cycle or phase is flagged, with nobody’s browser open. email takes one address or a list; on picks the flags (late, too-long, too-short; all three by default).

• Through Kymoscope (no smtp): the email names the rule, the flag, the source and the times, never a value. It reaches only addresses of members of the source’s project, at most 120 an hour per source, on Team and Enterprise. The collector’s log names any address that isn’t a member.
• Through your own mail server (smtp: host, port, user, password, from, security: starttls, ssl or none): the collector sends it directly and Kymoscope sees nothing. Write the password as file:smtp.txt or env:SMTP_PASSWORD.

Flags and notes

In Reports & analysis, select cycles and click Mark good, Mark bad… or Exclude… (Clear flag undoes it). Bad and excluded ask for a Reason, so the next reader knows why; hover a flag to read it. Bad and excluded cycles are left out of the control chart’s limits. Missed limits (late, too long, too short) show in the Flags column too.

Kymoscope keeps an audit record of who created, flagged, noted and versioned what, and when. It records that a note changed, never what it says.

Reports & analysis

Reports & analysis, in the bar above the charts, turns the workspace into the place to compare a project’s cycles. Pick the Project, then Cycles: the source (what a collector records into the project), the rule and the range. Back to charts returns.

• Control chart: each point is one cycle. Show picks what is plotted: the duration, each phase’s duration, the rule’s KPIs, or a channel’s maximum, mean or minimum over the cycle or over one phase. The line is the average of the normal cycles and the dashed lines are the control limits (± 3 standard deviations); the normal cycles are those with no missed limit, not flagged bad or excluded, so an odd cycle doesn’t widen its own limits, and one outside them is red. Along picks the horizontal axis: the cycles in order, their start date, or another KPI, which turns the chart into a scatter with its trend and correlation (r), to see whether two KPIs move together.
• Golden cycle: select the best cycle and click ★ Mark as golden. It becomes a Reference: its curve with a tolerance either side. It shows in gold in the table, the charts and the map.
• Reference with a band: select several good cycles and click Make Reference with band: their mean with a band of ± k standard deviations, narrow where the process is steady and wide where it varies (σ is pooled over neighbouring points, so a few cycles give a steady band).
• By phase: a Reference made from a rule with phases keeps them. Each cycle is then compared phase by phase: its heating over the Reference’s heating, its reaction over the reaction, so a longer phase doesn’t shift what comes after it. A cycle whose phases differ is compared on time since its start.
• A Reference’s card: click a Reference to see what it is made from and what counts as a deviation, channel by channel: ± k σ (a Reference of several cycles), ± a value in the channel’s units, or ± % of its scale (the larger of its range and its largest value, the nearest to an instrument’s full scale). The card counts the cycles outside each band as you change it (a cycle is outside when it stays past the band for 10 s). Save as version N keeps the change as a new version; earlier versions stay.
• Several References, one compared live: a rule can have several (one per product or recipe, for example). The starred one, marked LIVE, is the one compared live; Compare live on another’s card switches. The first one you make starts as the live one.
• Overlay vs Reference: the cycles shown are picked above the chart: remove one with ×, add one, or take the Worst 3, the Latest 3, the Flagged or those selected in the table. Align lays them by phase or on time since each started; a red bar marks each stretch outside the band, and each cycle shows its score on the channel picked: how far it is from the Reference on average, in standard deviations (under 1.5 is normal) or, for a golden cycle, in tolerances (over 1 is outside). Hover a score for what it means.
• Deviation map: a row per cycle and a column per phase and channel, each cell the cycle’s score there. Read across a row for where a cycle went wrong, down a column for a channel drifting; cells shade from normal to red (outside the band).
• A cycle’s card: click a cycle anywhere (a point, a row, the map) for the verdict (its worst channel and phase), its phases against the Reference’s, each channel over the band, its KPIs against the golden cycle, its flag and note, and its actions (flag it, mark it golden, import it).
• The analysis reads the newest 200 cycles in range in the background for the channel values, the scores and the map; the rest of the table shows their durations and flags.
• Find with a rule: cuts the source’s data over the range with a rule from your library (or the selected rule again) and saves the cycles to the source, so they open at once next time. The browser reads the raw data day by day at full resolution; finding again keeps the flags and notes already there, and days whose raw data has expired are skipped and named.
• Export CSV: the table with every cycle in range, its flag, reason and KPIs.
• Import to charts: the selected cycles, the selected cycles against a Reference (a Compare worksheet with the channels on top, the band behind them and each channel’s delta below), the golden cycle, or a Reference with its band, ready to lay over live data.
• A Reference keeps its own curve, so it never expires with the raw data; a golden cycle also keeps its cycle’s full-resolution data. Times follow the Cloud window’s Site time / My time choice.

Everyone in the project sees the analysis and imports from it; editors and leads flag cycles, mark golden cycles, make and change References, choose the live one and find cycles.

Live: follow the running cycle

A live stream’s Cycles button cuts it with a rule as it streams, and each cycle appears under the stream when it ends. To see the running cycle against a Reference, import the Reference with its band from Reports & analysis and lay the stream over it.

On any live multi-band chart, Follow the running cycle (Properties → Live streaming) shows only the running cycle when the X signal starts over, over a dataset or the previous cycle.

Automation

Export CSV (Reports & analysis) writes a rule’s cycles in range as CSV: start and end in ISO 8601 UTC, duration_s, flag, reason, then one column per KPI. It reads directly in pandas:

import pandas as pd
t = pd.read_csv("Batch.csv", parse_dates=["start", "end"])   # start, end (UTC), duration_s, flag, reason, KPIs
good = t[t.flag == "good"]
print(good["TIC201 max"].describe())
print(t.groupby(t.start.dt.date)["duration_s"].mean())

Your own web app can cut, align and compare with the SDK, with the same rule language the app and the collector use: CycleSet finds cycles and phases, engine.datasets.findCycles and addCycles do it on an open dataset, alignSegment, buildReference and compareToReference line runs up and compare them.

import { CycleSet, findCycles, cycleTables, readSource, alignSegment, buildReference, compareToReference } from '@kymoscope/sdk'

// The same rule language as the app and the collector: a cycle, and a phase inside it.
const defs = [
  { id: 'batch', parentId: null, rule: { start: { kind: 'change', channel: 'BatchNumber' }, end: { kind: 'next-start' } } },
  { id: 'heat', parentId: 'batch', rule: { start: { kind: 'parent-start' },
    end: { kind: 'compare', channel: 'TIC201', op: '>=', value: 30 }, limits: { expectedWithin_s: 900 } } },
]
// t: Unix seconds; cols: your columns by channel name (Float64Array each).
const found = new CycleSet(defs).feed(t, (c) => cols[c])     // closed cycles and phases: { definitionId, index, tstart, tend, flags }

// Each cycle's samples on one axis (time since start), then a reference from the good ones.
const axis = { kind: 'elapsed' } as const
const aligned = good.map((s) => alignSegment(s.t, s.cols, s.tstart, axis))
const ref = buildReference(aligned, ['TIC201', 'PIC102'], 2000)
const { delta, score, deviations } = compareToReference(alignSegment(n.t, n.cols, n.tstart, axis), ref, 3, 'sigma', 10)

Who can do what

• Viewers of the project read every rule, cycle, note and reference, compare and watch live.
• Editors and leads create rules, find cycles, flag, note, build references and save deviations, and save project rules.
• The author of a rule or reference, or a project lead, edits or archives it.
• The collector’s rules change only in its collector.yaml.
• When the project requires two-step verification or browser approval, saving needs them too.

Privacy

Rule names and settings, KPIs, notes and reference curves of a history are end-to-end encrypted with the history’s key, in the browser or on the collector, before they are stored; project rules of an end-to-end encrypted project with the project’s key. The Kymoscope server sees only the times of each cycle, its flag and counts, never the values. Cycles of a file or a live stream are cut in your browser and never stored.