edf2csv 0.8.55 → 0.8.57

package/dist/convert/run.d.ts

@@ -217,6 +217,29 @@ export declare function stdoutRefusal(file: EdfFile, plan: ConversionPlan): Conv
  * on is in the file and the plan, both of which `--info` already has.
  */
 export declare function noSignalFile(file: EdfFile, plan: ConversionPlan): Diagnostic | null;
+/**
+ * The signal table an `--annotations-only` run does not write, taken out of the hints about it.
+ *
+ * That mode writes the event list and nothing else — no signal files at all — and four hints
+ * about record timing describe the rows of one. On a recording whose records run backwards it
+ * printed both of these over an annotations.csv holding its header and no rows:
+ *
+ *     warning: This is a discontinuous (EDF+D) recording: its data records are not
+ *              contiguous in time.
+ *              Each row carries its true recording time, so gaps stay visible instead of
+ *              being closed.
+ *     warning: 2 data records start earlier than the record before them.
+ *              Rows are written in file order, so the time column will not increase
+ *              monotonically.
+ *
+ * There are no rows and no time column. The facts above the hints are about the recording and
+ * stay; what changes is the sentence describing what the conversion will do with them, which
+ * is the same surgery `withTimingPromiseKept` does to the first of these when the record
+ * starts cannot be derived.
+ *
+ * `writesSignals` rather than the option, because the plan is what settles it.
+ */
+export declare function withSignalTableUnwritten(diagnostics: readonly Diagnostic[], writesSignals: boolean): Diagnostic[];
 /**
  * The sidecar files a `--stdout` run does not write, taken out of the sentences about them.
  *

package/dist/convert/run.js

@@ -98,10 +98,10 @@ export async function convert(inputPath, options = {}) {
                 readerHungUp,
                 annotationCount: 0,
                 // Over both lists, because the timing warnings are pushed onto the plan's.
-                diagnostics: withSidecarsNamed([
+                diagnostics: withSignalTableUnwritten(withSidecarsNamed([
                     ...withTimingPromiseKept(withoutFileRateWarning(file.diagnostics), timing.starts !== null),
                     ...plan.diagnostics,
-                ], { toStdout: true, gzip: plan.gzip }),
+                ], { toStdout: true, gzip: plan.gzip }), plan.writeSignals),
                 plan,
                 file,
                 elapsedMs: Date.now() - startedAt,
@@ -199,11 +199,11 @@ export async function convert(inputPath, options = {}) {
             annotationCount: annotationsWritten,
             // The directory path needs it too: `--gzip` changes the names, and two of these
             // sentences are a file name and nothing else. See withSidecarsNamed.
-            diagnostics: withSidecarsNamed([
+            diagnostics: withSignalTableUnwritten(withSidecarsNamed([
                 ...withTimingPromiseKept(withoutFileRateWarning(file.diagnostics), timing.starts !== null),
                 ...plan.diagnostics,
                 ...stale,
-            ], { toStdout: false, gzip: plan.gzip }),
+            ], { toStdout: false, gzip: plan.gzip }), plan.writeSignals),
             plan,
             file,
             elapsedMs: Date.now() - startedAt,
@@ -1500,6 +1500,96 @@ export function noSignalFile(file, plan) {
                     `table --info prints, and in the ${outputCsvName('channels', plan.gzip)} a conversion writes.`,
     };
 }
+/**
+ * The signal table an `--annotations-only` run does not write, taken out of the hints about it.
+ *
+ * That mode writes the event list and nothing else — no signal files at all — and four hints
+ * about record timing describe the rows of one. On a recording whose records run backwards it
+ * printed both of these over an annotations.csv holding its header and no rows:
+ *
+ *     warning: This is a discontinuous (EDF+D) recording: its data records are not
+ *              contiguous in time.
+ *              Each row carries its true recording time, so gaps stay visible instead of
+ *              being closed.
+ *     warning: 2 data records start earlier than the record before them.
+ *              Rows are written in file order, so the time column will not increase
+ *              monotonically.
+ *
+ * There are no rows and no time column. The facts above the hints are about the recording and
+ * stay; what changes is the sentence describing what the conversion will do with them, which
+ * is the same surgery `withTimingPromiseKept` does to the first of these when the record
+ * starts cannot be derived.
+ *
+ * `writesSignals` rather than the option, because the plan is what settles it.
+ */
+export function withSignalTableUnwritten(diagnostics, writesSignals) {
+    if (writesSignals)
+        return [...diagnostics];
+    return diagnostics.map((diagnostic) => {
+        /*
+          And the three calibration warnings, whose hints are about cells.
+    
+          Each describes what a conversion does with a channel whose header cannot map cleanly —
+          leaves the cell empty, fills it with the one value the mapping has, keeps the inversion —
+          and `--annotations-only` converts no samples, so none of it happens:
+    
+              warning: Signal 0 ("flat") has digital minimum equal to digital maximum (0), so its
+                       values cannot be scaled.
+                       Its cells are left empty rather than filled with a value the header cannot
+                       justify.
+    
+          What is wrong with the header is still worth saying, and channels.csv — which that run
+          does write — still carries the calibration. One message also ends in the conversion:
+          "so every sample converts to the same value", over a run converting none.
+        */
+        if (diagnostic.code === 'DEGENERATE_DIGITAL_RANGE') {
+            return {
+                ...diagnostic,
+                hint: 'No samples are converted with --annotations-only, so there are no cells to leave ' +
+                    'empty. channels.csv still records the digital range the header gives.',
+            };
+        }
+        if (diagnostic.code === 'DEGENERATE_PHYSICAL_RANGE') {
+            return {
+                ...diagnostic,
+                message: diagnostic.message.replace('so every sample converts to the same value.', 'so every sample would convert to the same value.'),
+                hint: 'No samples are converted with --annotations-only. channels.csv still records the ' +
+                    'calibration, one point wide.',
+            };
+        }
+        if (diagnostic.code === 'INVERTED_PHYSICAL_RANGE') {
+            return {
+                ...diagnostic,
+                hint: 'No samples are converted with --annotations-only. channels.csv records the ' +
+                    'physical minimum and maximum in the order the header gives them, inversion included.',
+            };
+        }
+        if (diagnostic.code !== 'DISCONTINUOUS' || diagnostic.hint === undefined)
+            return diagnostic;
+        if (diagnostic.hint.startsWith('Each row carries its true recording time')) {
+            return {
+                ...diagnostic,
+                hint: '--annotations-only writes no signal rows, so nothing here is timed from the ' +
+                    "records. annotations.csv carries each event's own onset, and the record it came " +
+                    'from in record_index.',
+            };
+        }
+        if (diagnostic.hint.startsWith('Rows are written in file order')) {
+            return {
+                ...diagnostic,
+                hint: '--annotations-only writes no signal rows, so no time column is affected. ' +
+                    "annotations.csv's record_index still names the record each event came from.",
+            };
+        }
+        if (diagnostic.hint.startsWith('Sample times are written from zero')) {
+            return {
+                ...diagnostic,
+                hint: '--annotations-only writes no signal rows, so no sample times are written at all.',
+            };
+        }
+        return diagnostic;
+    });
+}
 /**
  * The sidecar files a `--stdout` run does not write, taken out of the sentences about them.
  *
@@ -1745,12 +1835,12 @@ bom) {
                 decimals: g.channels.map((c) => c.decimals),
             })),
         },
-        notes: withSidecarsNamed([
+        notes: withSignalTableUnwritten(withSidecarsNamed([
             ...withTimingPromiseKept(withoutFileRateWarning(file.diagnostics), timedFromRecords),
             ...plan.diagnostics,
         ], 
-        // metadata.json is only written into a directory, so this one is never the stdout case.
-        { toStdout: false, gzip: plan.gzip }).map((d) => ({
+        // metadata.json is only written into a directory, so this is never the stdout case.
+        { toStdout: false, gzip: plan.gzip }), plan.writeSignals).map((d) => ({
             code: d.code,
             severity: d.severity,
             message: d.message,