About the Analysis Suite

Analysis is the module between Preprocessing and ML Suite. Preprocessing conditions the raw recording; the Analysis Suite turns that conditioned signal into the thing a decoder is actually trained on, one reviewable step at a time. Eleven steps run in it, grouped into two sections in the module sidebar: Prepare, which cleans the recording and cuts it into trials, and Reduce & Extract, which narrows those trials down to a labelled design matrix.

Nothing here is a black box and nothing here is destructive. Each step reads a named stage, writes a named stage, and records the parameters it ran with. Your original recording is never modified, and every intermediate result stays inspectable, exportable, and re-runnable.

View and Apply

Every step opens as two tabs. View is the interactive workspace: pick one file, set the parameters, run it, and read the result. Apply is the batch tab: take exactly the settings currently in View and run them across many files at once. The two produce identical outputs, because Apply calls the same code path with the same payload, not a parallel implementation.

The working habit the suite is built around is preview on one file, then batch the rest. Ten of the eleven steps have a working Apply tab; Activation Maps is view-only because it renders figures rather than writing a stage.

Step Order & Reordering

The sidebar order shown above is the conventional BCI preparation order, but it is a default, not a constraint. The seven Prepare steps can be dragged into a different order and the app remembers it across restarts, which matters because there is no single correct sequence: some labs screen channels before ICA, others after; some normalise before epoching, others after.

Reordering is presentational only. Nothing about a step's identity, output name, or dependency rules moves with it, so a reordered sidebar cannot cause one step's result to be written under another step's name. Draggable steps show an open-hand cursor on hover; fixed steps do not.

Stages & Dependencies

A processed result in BCILattice is a stage, not a loose file. Every stage for one subject and one experiment lives inside that subject's .bltdcontainer, alongside the raw recording and the parameters, timestamp, and input hash of the run that produced it. You will see filename-shaped handles likesub01_filtered_epochs_exp2.csv in pickers and logs. Those are readablekeys, not paths, nothing is written at that location.

An experiment holds exactly one live output per stage. Re-running a step overwrites its stage, which is what branching an experiment is for, so there is no _v2 ladder to keep track of. Stage resolution is experiment-aware: a step loads the active experiment's stage, or the parent it inherits from, never a sibling experiment's.

What Each Step Writes

The method you chose is recorded in the stage's parameters, never in its name. One Channel Selection stage exists per experiment whether you ran Fisher Score or CSP, so trying a second method does not litter the container with a file per attempt.

Which Input Each Step Accepts

Each step's Source dropdown lists only the stages that operation is allowed to consume. These rules are enforced centrally rather than being a per-page convention, so the dropdown and the engine can never disagree about what is legal.

The absences in that table are deliberate, and each has a reason:

• Augmentation, Time-Frequency and Activation Maps refuse continuous stages. There are no trials in a continuous recording to augment, to average an ERSP over, or to draw a per-condition topography from.
• Channel Quality refuses normalized input. Bad-channel detection is amplitude and variance based, and normalisation removes exactly the scale those metrics read. Offering it would produce a confident, meaningless verdict.
• Data Projection refuses a feature table. GAF, MTF and recurrence plots all assume temporal ordering; a feature table's columns are unordered summary statistics.

Controls Every Step Shares

The distinction between the last-run card and the on-screen controls matters. A control can be nudged after a run without re-running, at which point it no longer describes the output in the container. The card always describes what actually executed.

Part 1, Prepare

Seven steps that take a filtered recording and produce clean, labelled trials. This section is user-reorderable; the order below is the default.

1. ICA Review

Independent Component Analysis separates the recording into statistically independent sources. Blinks, muscle tension, and heartbeat tend to concentrate into their own components, so zeroing those and reconstructing gives you the neural signal without them. The point of this page is that the decision stays yours: nothing is rejected until you label it and apply.

Results arrive as a card per component, showing a waveform snippet, its power spectrum, and its spatial weights. Each card carries a label dropdown: Keep,Eye, Muscle, Cardiac, orOther. Running counts per category sit above the grid.

Suggest Labels

A heuristic classifier proposes a label for every component from its spectral shape, beat regularity, kurtosis and topographic focality. It is a proposal you review, not an action, and each suggestion carries the reason it was made. Applying rejection is always a separate, explicit click.

Diagnostics tab

The numbers behind the cards, one row per component:

Apply Rejection zeroes the labelled components, reconstructs the signal, and writes the ica_cleaned stage. The rejected component indices are recorded with it.

2. Channel Quality

Scores every channel against the rest of the montage and flags the ones that look dead, railing, or noise-dominated. Screening channels before ICA is standard practice, a dead or railing channel otherwise consumes a whole component on its own.

Every method produces one composite robust z-score per channel (median + MAD scoring, so a few extreme channels cannot drag the threshold with them). A channel is flaggedBad when its score reaches the sensitivity threshold k (1.0–10.0, default 3.5), Warn above 60% of k, and Good below that. A flat-line channel is force-flagged Bad under every method regardless of what its chosen metric says.

Three result tabs: Overview (per-channel score bars), Channels(the scored table, with a Keep/Drop checkbox per channel that defaults to the automatic flag and is yours to override), and Waveforms (what the flagged channels actually look like). Apply Channel Drop removes the unchecked channels and writes thechannel_quality stage.

3. Epoching

Turns a continuous recording into a trial tensor: one labelled epoch per event. Everything downstream that talks about trials, ERSP, CSP, per-trial features, depends on this step.

Event detection

Three event sources:

• Label column, an event/label/class column already in the file.
• MNE stim channel, a hardware trigger channel.
• NeuralFlow, the compiled paradigm you designed in the Neural Flow module.

Sync pulls events from the selected source so you can sanity-check the count and onset times before extracting. Extraction runs detection automatically if you skip it.

Window, baseline and rejection

Automatic rejection adapts to the recording; the fixed threshold is for when you have a lab convention to hold to. Both drop trials contaminated by motion or artifact so a handful of bad epochs cannot skew the average.

Result tabs

• Preview, the epoched signal per channel, with export.
• Rejection, which trials were dropped and why.
• Statistics, trial counts and per-class balance.
• Artifacts, what the rejection criterion actually caught.
• Quality, an overall read on the epoch set.

Compare Runs puts two epoching attempts side by side, which is the fastest way to see what a window or rejection change actually cost you in trials.

4. Normalization

Rescales the signal. Eight scalers, each mirroring its scikit-learn counterpart:

Scope is either Per-channel (each channel gets its own statistics) orWhole recording (one set of statistics for everything).

Three result tabs: Preview (before and after), Scale Factors(the offsets and scales actually applied, per channel), and Distribution (what the transform did to the amplitude distribution). Writes the normalized stage.

5. Augmentation

Synthesises additional trials from the ones you have. Sources are Epochs orNormalized (normalisation preserves its input's shape, so normalised epochs are still epochs). Nine augmentations, chainable into a pipeline, with a fixed random seed for reproducibility:

Every parameter carries its real range and unit rather than a generic numeric field, so an SNR cannot be set to a value that means nothing and a probability cannot go negative.

6. Activation Maps

Where the activity is, drawn from epoched data. This step renders figures and writes no stage, so it has no Apply tab.

Activation Maps tab (2D)

The sensor map above the generated topographies shows electrode or optode positions with mean activation, so you can confirm the montage is right before reading anything into the maps.

3D Brain tab

Projects the same data onto a cortical surface. Requires the Researcher plan or above.

• BCI Metric: Mean (abs), Std Dev, RMS, Peak-to-Peak, Max (abs), SNR (dB), or band power for Alpha (8–12 Hz), Beta (13–30 Hz), Theta (4–7 Hz), Delta (0.5–3.5 Hz), Gamma (30–80 Hz).
• Hemisphere: Left, Right, Both.
• View: Lateral, Medial, Dorsal, Ventral, Frontal, Posterior.
• Colormap: plasma, viridis, inferno, magma, RdBu_r, YlOrRd, cool, hot, jet.
• Show Names toggles channel labels; Screenshot saves the viewport.

The 3D view renders only when you press Apply / Refresh. Every control on the sidebar is read at that moment, so working down the sidebar does not trigger a surface projection per change.

7. Time-Frequency

Event-related spectral perturbation (ERSP) and inter-trial coherence (ITC): how power and phase consistency change over time, per frequency, relative to baseline. This is the step that tells you whether your paradigm produces the effect you designed it to produce.

The decomposition is computed once and cached. Channel, class, band preset, response window, and significance masking are view controls: changing them redraws from the cache without recomputing, and only the visible tab draws.

The seven views

Mask non-significant outlines the time-frequency bins belonging to a significant cluster (one-sample cluster-permutation test against 0 dB, p < 0.05), computed on demand on a background thread.

Band presets are shared with Feature Extraction, so "alpha" means the same range on both pages. Available montages for the topography view include standard_1020, standard_1005, biosemi16/32/64, easycap-M1, GSN-HydroCel-32 and -64, mgh60, and the fNIRS artinis-octamon and artinis-brite23 layouts. If your channel names do not match the montage, the map falls back to a labelled ring, which is a signal that the montage is wrong, not a scalp map.

The saved time_frequency stage holds the per-trial ERSP tensor as its primary data, with grand and per-class averages beside it, so the result is trainable rather than being only a picture.

Part 2, Reduce & Extract

Four steps that narrow a clean, trial-structured recording down to something a model can train on. The heavy computation for these runs in the local service on your machine; the pages resolve and read the source file themselves before sending anything, so the step you selected is the step that gets analysed.

8. Channels Selection

Ranks every channel by how much class information it carries and keeps the top fraction. Set the Top Percent (1–100, default 50) and, optionally, classes to ignore (for example rest, entered as 0 or 0,1,2). Twenty criteria are available:

Reading the scores

A raw score is not interpretable on its own, the methods return t-values, mutual information, F-statistics and correlation coefficients, all on different scales. Every score is therefore shown next to scale-free rank statistics:

The LASSO and Sparse CSP methods standardise the data and choose their penalty by cross-validation rather than using a fixed default. On signals in physical units, a fixed penalty shrinks every coefficient to zero, which silently presents the first N channels as "the top N" on every dataset.

9. Dimensionality Reducer

Projects the channel space onto fewer components. The method list is the full Dimensionality Reduction category of the ML component catalogue, so anything you can wire into an MLFlow graph is available here as a one-shot fit, PCA, Kernel PCA, TruncatedSVD, FactorAnalysis, FastICA, NMF, t-SNE, UMAP, Isomap, Locally Linear Embedding, MDS, Spectral Embedding, Dictionary Learning, and the rest. Each method exposes its own parameters, built from the catalogue schema rather than hard-coded here.

Reading the components

The components table separates variance accounting from class discriminability, because a projection can explain a great deal of variance while separating nothing a decoder cares about:

10. Feature Extraction

This is the step that produces the labelled design matrix ML Suite trains on: one row per trial, one named column per feature. It sits after dimensionality reduction on purpose, by the time you reach it the channels are clean, selected and optionally projected, so what is extracted comes from the data you actually intend to decode.

Columns are named {unit}_{band}_{family}_{suffix} and each carries its domain, family, channel, band, unit and slot as metadata, so a ranked feature can always be traced back to a channel and a frequency band.

Feature Catalogue

Seventy-one feature families across five domains.

Time Domain, 27 families

Mean, Variance, Standard Deviation, Skewness, Kurtosis, Minimum, Maximum, Peak-to-Peak, Median, Interquartile Range, Root Mean Square, Signal Energy, Mean Absolute Value, Waveform Length, Zero Crossing Rate, Slope Sign Changes, Willison Amplitude, Nonlinear Energy, Hjorth Parameters (Activity / Mobility / Complexity), Shannon Entropy, Permutation Entropy, Sample Entropy, Approximate Entropy, Higuchi Fractal Dimension, Petrosian Fractal Dimension, Katz Fractal Dimension, Autoregressive Coefficients.

Frequency Domain, 18 families

Absolute Band Power, Relative Band Power, Log Band Power, Band Peak Frequency, Total Power, Peak Frequency, Mean Frequency, Median Frequency, Spectral Edge Frequency, Spectral Entropy, Spectral Centroid, Spectral Bandwidth, Spectral Skewness, Spectral Kurtosis, Spectral Rolloff, Spectral Flatness, Spectral Slope, Band Power Ratios (theta/beta, alpha/beta, engagement index).

Time-Frequency Domain, 9 families

Wavelet Sub-band Energy, Wavelet Sub-band Entropy, Wavelet Coefficient Statistics, Wavelet Band Energy, ERD/ERS, Windowed Band Power, Hilbert Envelope Statistics, Instantaneous Frequency, Time-Frequency Entropy.

Spatial Features, 8 families

Common Spatial Patterns (CSP), Covariance Matrix, Riemannian Tangent Space, Global Field Power, Laplacian Variance, CAR Variance, Channel Power Ratio, Region Band Power (frontal, central, parietal, occipital and temporal ROIs derived from 10-20 electrode names).

Connectivity Features, 9 families

Correlation, Cross-Correlation Lag, Coherence, Imaginary Coherence, Phase Locking Value (PLV), Phase Lag Index (PLI), Weighted Phase Lag Index (wPLI), Mutual Information, Graph Metrics (degree, clustering coefficient, efficiency, density).

Extraction settings

Channel-defined families (CSP, connectivity, covariance, ROI, Global Field Power) only exist on the spatial axis, the channels have been averaged away on the temporal axis. They are skipped with a note rather than quietly computed over window indices, because "covariance between time windows" is a different quantity wearing the same name.

Bands above the recording's Nyquist limit are dropped or clamped, and the run reports which. An EEG gamma band on a 10 Hz fNIRS recording is not a small error, it is an empty integration window that would otherwise yield a column of zeros.

Reading the result

The feature picker shows a live estimate of how wide the resulting matrix will be, so a careless selection is priced before it runs rather than after. Extracted features are ranked four ways at once, in one table: Score (the test statistic), p,Effect (effect size), and MI (mutual information), alongside the feature's domain, band, channel, and mean.

11. Data Projection

Encodes one channel's 1-D time course as a 2-D image, so computer-vision architectures can be applied to a signal. Three encodings:

Each projected window is described twice: what the source segment was (RMS, peak-to-peak, kurtosis, zero crossings, dominant frequency, spectral entropy, Hjorth mobility and complexity) and what the encoding turned it into (image statistics and recurrence quantification). Both matter, an image looks different either because the encoding highlighted something or simply because that window happened to hold a burst.

Batch Apply

The Apply tab on each step takes the settings currently in View and runs them across a selection of files.

1. Set up and run the step on one file in View until the result is what you want.
2. Switch to Apply. Files are listed under modality tabs (fNIRS, EEG, EMG, EOG) with a checkbox each.
3. Select the files, or use Select All, and press Apply.
4. Progress reports per file as it goes; Cancel stops cleanly after the current file rather than mid-write.

Batch runs record their own stage artifacts exactly as a View run does, so a batched output is indistinguishable from one you produced interactively, and equally discoverable downstream. Batch runs also carry the same paradigm identity as the View run, so labels resolve against this study's paradigm only.

Files that cannot be processed, for example a subject with no filtered stage yet, are skipped with a logged reason rather than aborting the whole batch.

Provenance & Reproducibility

Analysis is not write-only. Three mechanisms make a study reopenable and a result defensible.

Recorded parameters

Every run writes its real parameters into the stage it produces, with a timestamp, the input hash, and the output handle. The Last run card on each page reads that back and states it plainly, which is a stronger record than the state of the controls: a control can fail to restore, and a control can be changed after a run without re-running.

Methods drafts

The Methods button assembles a publication Methods paragraph from what this recording has actually had done to it, in pipeline order: filtering, ICA, channel screening, epoching, normalisation, augmentation, time-frequency, channel selection, dimensionality reduction, features, projection. It is a first draft built from recorded provenance rather than from memory, and it is yours to edit.

Reopenable pages

Each page captures three layers of state into the study document: the controls you set, the rendered surfaces (tables and summary text), and the run payload itself. When the payload is present, reopening re-renders live plots you can theme, zoom and export, rather than a picture of a plot. Figures are stored as reusable assets inside the subject's container, so an exported study carries publication-ready images without re-rendering them.

Handing Off to ML Suite

Every stage the Analysis Suite writes is selectable as a data source in the Workflow designer, so what you built here binds directly to a training graph. Two handoffs are worth calling out:

• Feature Extraction → classical models. The 2-D design matrix is one row per trial with named columns, which is what LDA, SVM, random forests and gradient boosting expect.
• Feature Extraction (3-D tensor) or Time-Frequency → deep models. The tensor keeps the unit axis for CNN, LSTM and EEGNet-style architectures, and the time-frequency stage stores the per-trial ERSP tensor rather than only an average.

fNIRS & EMG Notes

• Chromophore separation. An fNIRS file holds an HbO and an HbR channel per source-detector pair. Decomposing, ranking, or reducing both together mixes two different physiological signals, so every fNIRS-capable step exposes a Chromophore control (All, HbO, HbR). Activation Maps offers HbO or HbR only, because a topomap draws one value per optode position and both at once would overplot the same sensors.
• fNIRS bands. The fNIRS band preset covers vlf (0.005–0.02 Hz), hemodynamic (0.01–0.08), mayer (0.08–0.12), respiratory (0.2–0.4), and cardiac (0.8–1.5). The higher bands are the physiological confounds you want to be able to measure rather than assume away.
• fNIRS time-frequency resolution. The haemodynamic response lives below about 0.1 Hz. At fNIRS sampling rates a wavelet decomposition has limited resolution in that band, so time-frequency peaks read low. That is a resolution limit of the method, not a defect in the recording.
• EMG bands. The EMG preset covers low (20–50 Hz), mid (50–100), high (100–250) and very_high (250–450). Several time-domain families, RMS, Mean Absolute Value, Waveform Length, Slope Sign Changes, Willison Amplitude, are the standard EMG activation measures.
• Sampling rate is read from the file. Steps derive it from the loaded recording's own metadata rather than assuming an EEG-style rate, which matters for a roughly 10 Hz fNIRS recording.

Troubleshooting