Records a run as a citable run record (or as plain CSV). More...
| Import Statement: | import Clayground.Lab |
Recording starts and stops with recording. On stop the run is written to destination as a run record: a self-describing text file holding the lab id, scenario, seed, every parameter value, the per-probe series with their summaries, and the command that regenerates it. That file is what a paper cites - see plugins/clay_lab/record.js for the format and why it is shaped that way.
Records belong in labs/<lab>/records/ and are committed: they are small diffable text, and a record with no wall-clock field in it means two runs of the same seed produce the same bytes, so "does the paper still hold?" is a diff.
A .csv destination still writes the flat table it always did - the spreadsheet escape hatch - but a CSV cannot be cited, because it carries no provenance.
Example usage:
import Clayground.Lab DataRecorder { id: rec lab: "sensor-fusion-101" destination: "labs/sensor-fusion-101/records/open-sky-42.labrec" command: "labs/sensor-fusion-101/records/make.sh open-sky" } // rec.recording = true ... rec.recording = false -> the record is written
command : string |
The command that regenerates this record, written into it.
Empty is allowed and produces a record nobody can reproduce, which the recorder warns about rather than hiding.
destination : string |
Output path. A .csv suffix selects the flat CSV table; anything else (by convention .labrec) writes a run record.
Relative paths resolve against the process working directory, so a lab gives an explicit one - a bare default once littered the repo root.
error : string |
Why the last write failed ("" if it did not).
format : string |
"auto" (from the suffix), "record" or "csv".
lab : string |
Lab id written into the record; defaults to the destination's parent-of-records directory when it can be read off the path.
lastFile : string |
Path of the most recently written file ("" if none).
maxBytes : int |
Size above which the sample table is thinned instead of written in full (the record stays committable; summaries stay over all samples).
probes : var |
Probe names to record (empty = all registered probes).
recordId : string |
Id a paper cites this record by; defaults to the file's base name.
Deliberately an INPUT rather than something generated: a record carries no wall clock, so its id has to come from outside if it is to name a particular run.
recording : bool |
Toggle to start/stop; stopping writes the file.
rows : int |
Sample ticks recorded in the current/last run.
stepSize : real |
Sim seconds per step, for the record's provenance.
0 falls back to SimClock.fixedStep. A driver that steps the clock itself (the headless record runs do) has to say so here, because a clock advanced from outside does not know how big the steps were.
steps : int |
Fixed steps the run advanced, for the record's provenance (0 = unknown, e.g. a live dojo recording).
written(string path, int rows) |
Emitted after a successful write.
Note: The corresponding handler is onWritten.
var record() |
The record object for what has been captured so far, without writing it - the shape record.js serializes.