Learning center

Neural Coding: trial windows, response units and categorical limits

Prepare spike trains and trial information, then understand response windows and categorical labels. The small worked example illustrates input requirements; it is not a full app demonstration or a decoding-accuracy result.

Prepare spike trains and trial information, then understand response windows and categorical labels. The small worked example illustrates input requirements; it is not a full app demonstration or a decoding-accuracy result.

1. Supply explicit spike trains and usable trials

Preserve per-unit timestamps and the trial table when loading the intended recording. The current NWB reader extracts unit spike times and normalizes the trials table into metadata records. A voltage trace, event-count vector or filename alone does not supply that contract.

Required informationCurrent source contract
Per-unit spike timesUse finite timestamps in seconds, strictly increasing within each unit. Empty trains are skipped; duplicate or reversed timestamps within a nonempty train are refused. The full Neural Coding path requires at least two retained units.
Trial intervalsEach row needs finite start_time and stop_time, with stop greater than start. Keep the actual acquisition intervals and time reference.
Alignment and categoriesRetain the recorded stimulus/cue/event time where available and a repeated categorical field. The adapter selects a supported field; inspect which one was used instead of treating numeric category codes as physical coordinates.
Enough usable trial rowsThe adapter can construct a response from four trials. The full app subsequently requires at least 80 usable rows, after trial selection and removal of rows without a recognized category. Four passing adapter-test trials do not satisfy that app requirement.

The official PyNWB interval guide defines start/stop values as seconds relative to the file’s time reference and supports additional trial columns. Its extracellular electrophysiology guide distinguishes acquired voltage data from stored spike data. Preserve that distinction when preparing the input.

2. Read the common response window

The adapter considers alignment fields in this order: stim_on_time, cue_on_time, event_time, then start_time. A field must be finite and lie within every selected trial: at or after its start and strictly before its stop.

It uses the shortest available pre-alignment duration and shortest available post-alignment duration across the selected trials to create a common window. Longer trials therefore do not automatically contribute their entire duration. The count includes spikes at both response-window endpoints; overlapping windows can count the same spike in more than one trial.

Firing rate is the spike count divided by that common window’s duration in seconds. First-post-event latency is measured from the chosen alignment to the first spike at or after alignment and no later than the window’s right endpoint. An absent post-event spike remains a missing latency, not a zero latency.

For this path, Max samples controls a trial-selection limit, with an effective lower limit of 100 for that control. If more trials are available, the adapter selects an approximately evenly spaced subset in stored row order. This is neither a new recording sample rate nor a claim that selected trials are statistically independent.

3. Keep category labels separate from physical geometry

The source searches recorded fields such as category_name, stimulus, condition and trial_type. A recognized field has 2–32 distinct usable labels, with at least two categories appearing at least twice. Missing or unrecognized row labels receive a negative code and are excluded by the app. Retain the selected field and its label-to-code mapping.

Category codes identify groups. They do not establish angle, position, a continuous target or an ordered stimulus scale. For categorical trial input, the current app returns not_applicable for routes whose required measurements are absent, including orientation, place/head-direction coding, phase coding, Fisher information, population-vector decoding and a declared GLM design.

The same path also refuses a PSTH/raster calculation from its aggregate trial-response representation. A refusal table is a recorded limitation, not a computed zero. Keep its Requirement and GeneratedSurrogate fields with the other results.

4. Understand the small retained adapter example

The historical test fixture contains two named units and four trials with alternating A/B labels. It is an in-memory synthetic adapter input, not a native file-loading or full Neural Coding example. The following values are retained test expectations; they were not recomputed for this lesson.

Retained checkExpected value and scope
Trial responseEach unit contributes one spike in each 0.8-second common trial window. The expected rate is 1.25 Hz in every trial-unit cell.
First post-event latencyThe expected latency is 0.1 s for the first unit and 0.2 s for the second, relative to the recorded stimulus-onset field.
Categorical identityThe retained field is category_name, labels are A/B and codes are 0/1/0/1. A separate test with a unique category on every trial returns no qualifying condition field.
Separate rate-binning testThe requested target is 2 Hz, but minimum and maximum bin counts are both fixed to four. The reported bin width is 0.95 s, with eight spikes across the bins. Use the reported width to interpret rate; the requested target does not override the bin-count bounds.

Another retained test covers unordered spike timestamps and missing trial metadata. These four cases establish their named helper checks only. The four-trial fixture remains below the full app’s 80-usable-row threshold; duplicating trials would not create independent observations or new validation.

5. Check plot units and missing values

The adapter’s trial rates have units of Hz, but the Neural Coding category-response plots use robustly normalized responses and label their vertical axis z. A normalized response height is not an absolute firing rate. The displayed category order is a label encoding, not a physical stimulus trajectory.

The latency adapter stores seconds; the app’s latency distribution and summary fields use milliseconds. The current latency heatmap replaces missing values with zero for display, while the finite-response fraction is reported separately as Responsive. A zero-colored heatmap cell alone cannot distinguish an immediate response from a missing response. Inspect the missing-value scope before drawing a timing conclusion.

Source-defined decoder and correlation summaries are separate from the retained adapter tests. This lesson does not establish generalization accuracy, a biological coding mechanism, a causal relationship or performance on an acquired dataset.

6. Save all published tables without overstating completeness

OutputWhat to retain and what remains outside it
All Tables CSVExport All Tables (CSV) writes the accumulated tables using Table/Metric/Value rows, including available contract and refusal tables. It does not automatically export every per-unit spike timestamp or the internal trial-by-unit response matrix.
Numeric summariesMany app summary values are formatted to six significant digits before reaching the viewer. Saving those strings to CSV preserves that reported precision; it cannot restore an unformatted internal value.
Figures and reportKeep the selected figure exports and report alongside the CSV and run configuration. A plot showing normalized or missing-value-substituted data needs its corresponding units and limitations.
Original input and metadataKeep the original NWB/data file, per-unit spike times, trial table, time reference, condition mapping and selected-trial scope separately. Published summary tables are not a substitute for those inputs.

Worked examples describe particular inputs, methods and recorded results. Check current availability and input requirements before planning an evaluation.

← Back to the learning center