Overview

BCILattice is the NeuroMatrix desktop application for BCI and neuroscience research. It is built around a local-first workflow: import recordings, preprocess signals, design paradigms, build ML pipelines, train models, compare experiments, inspect model behavior, and export reports from one study workspace.

The application is visual first, but it is not a black box. Researchers can inspect intermediate outputs, configure preprocessing explicitly, use custom blocks where needed, and keep experiments reproducible through study snapshots, run history, report exports, and BCINexus publishing metadata.

BCILattice vs BCINexus

Workflow Map

Installation

Download the current installer or package from bcinexus.xyz/download. The desktop app is designed as a cross-platform PySide6 (Qt for Python) application, but the download page is the source of truth for which packaged builds are currently available.

• Use a workstation with at least 8 GB RAM; 16 GB or more is recommended for large multi-subject datasets.
• Use an NVIDIA CUDA GPU when available for faster PyTorch training; CPU training remains supported.
• Keep enough disk space for raw recordings, derived preprocessing outputs, reports, and local study files.
• If you run from source, use the repository dependency files and developer environment instead of the end-user installer instructions.

Account

A BCINexus account is optional for local work and required for cloud-backed features. Sign in when you want to sync a study, publish to the community, create private share links, join a team workspace, or use dashboard/account features.

1. Create an account at bcinexus.xyz/register or from the desktop sign-in flow.
2. Verify your email if prompted.
3. Return to BCILattice and sign in from Settings, Account, or the module that requested authentication.

Cloud quota and plan behavior follow the active workspace. A team study uses the team's plan and quota; a personal study uses your personal account quota.

Studies

Studies are the container for local research work. New study work should use .blts, which stores study metadata and references to the workflow state BCILattice needs to reopen your study.

• Create: open Studies and create a local study with name, modality, task type, and description.
• Open: load a .blts file from the Studies page.
• Workspace: use the study workspace to move between Data Manager, Preprocessing, Analysis, Neural Flow, ML Suite, Experiment Hub, Results, Model Analysis, Reports, and publish actions.
• Sync: use explicit cloud sync when you want a selected study package backed up to BCINexus.

Trained model artifacts are kept in a global per-user store (~/.bcilattice/experiments) and referenced by experiments rather than copied into each study. When you export or share a study as a .bciproj bundle, the referenced artifacts are gathered and restored automatically.

Data Manager

Data Manager is the source for files, subjects, sessions, modalities, labels, and quality checks. Downstream preprocessing, analysis, workflow assignment, and training depend on the records you define here.

Importing Files

1. Open the active study workspace and choose Data Manager.
2. Import a single file or scan a folder containing subject/session directories.
3. Select the modality and confirm labels or label columns.
4. Review previews and quality warnings before adding the data to the study.

Supported Formats

Original recordings are not modified. BCILattice writes derived outputs and study metadata separately.

Preprocessing

Preprocessing applies signal conditioning before feature extraction and training. Use it to create a documented, repeatable transformation path rather than editing raw files manually.

Neural Flow

Neural Flow is the visual paradigm designer. Use it to define trial structure, cues, task blocks, rest periods, looped blocks, markers, and timing. The output can be used as a paradigm artifact and as a label/timing reference for downstream work.

1. Open Neural Flow from the study workspace.
2. Add task, cue, feedback, timing, marker, or loop blocks.
3. Set labels, durations, marker codes, and repeat counts.
4. Compile the graph and fix any validation errors.
5. Export or save the paradigm with the study.

ML Suite

ML Suite is the visual ML area. It includes MLFlow graph editing, Workflow assignment, training dashboards, curated BCILattice blocks, and a larger catalog of scikit-learn, PyTorch, MNE, signal-processing, feature, evaluation, and model components.

• MLFlow: build the graph that defines transforms, models, metrics, and outputs.
• Workflow: assign study data, subjects, sessions, and endpoints to the graph.
• Training: compile, validate, and execute runs with local CPU/GPU resources.
• Custom Code: add controlled custom logic when built-in blocks are not enough.

Workflow & Training

1. Start with a simple baseline graph before adding deep models or complex projections.
2. Use Workflow to bind files from Data Manager to the graph.
3. Compile and fix structural errors before training.
4. Run training from the dashboard and monitor per-subject or per-run progress.
5. Review metrics in Experiment Hub and Results before making conclusions.

For subject-generalization claims, use validation that respects subject boundaries. For quick debugging, compare a simple LDA/SVM baseline against deep models before tuning architecture.

Experiment Hub

Experiment Hub is the run-history and comparison surface. It stores completed run records, lets you inspect metrics, compare selected runs, export CSV records, restore selected experiment state where available, and publish selected artifacts to BCINexus.

• Use run history to see what changed between training attempts.
• Compare metrics before declaring a model improvement.
• Export CSV when you need external statistical analysis.
• Publish only artifacts that are safe and meaningful for other researchers to reuse.

Analysis & Results

Analysis, Results, and Model Analysis are separate surfaces. Analysis is for signal and feature inspection. Results is for metrics and cross-experiment comparison. Model Analysis is for interpretability and diagnostics such as SHAP, weights, and activation maps where the selected experiment supports them.

The Analysis Suite

Analysis runs as eleven steps in two sections. Prepare cleans the recording and cuts it into trials; Reduce & Extract narrows those trials into the labelled matrix ML Suite trains on. Every step has a View tab for working on one file and an Apply tab for batching the same settings across many, and every step reads a named stage and writes a named stage inside the subject's .bltd container.

1. Pick the modality, session, file, and upstream Source stage.
2. Set the step's parameters and run it on that one file.
3. Read the result tabs, tables, figures, and the diagnostics that come with them.
4. Switch to Apply and batch the same settings across the rest of the dataset.
5. Use Methods to draft a Methods paragraph from the recorded provenance.

The seven Prepare steps can be dragged into a different order, and the app remembers it; Reduce & Extract is a fixed dependency chain. Each step's Source dropdown offers only the stages that step is allowed to consume.

Reports

Reports turns the current study document and experiment outputs into shareable files. Use it after the data, preprocessing, workflow, training, and result sections are complete enough to explain.

1. Open Reports from the study workspace.
2. Generate the report from the current study state.
3. Review the generated sections in the editor.
4. Export PDF, HTML, JSON, or CSV depending on the recipient.

Use JSON when you need a machine-readable study document and CSV when you need metric tables for external analysis.

AI Chat

AI Chat connects the desktop app to your own AI provider accounts or a local Ollama endpoint. Supported providers are Gemini (Google), ChatGPT (OpenAI), Claude (Anthropic), Mistral, DeepSeek, a free-tier Groq API, and local Ollama. You supply the API key, or run Ollama on your own machine for a fully local model. Answers are grounded in your work through retrieval over app knowledge, your experiments, sessions, and pipelines.

• Connect providers from the AI Chat connection page.
• Use prompt tools to ask about preprocessing, interpretation, reports, or ML troubleshooting.
• Review answers critically before applying them to a research workflow.
• Use local Ollama when you need prompts to stay on your own machine.

Cloud & Sharing

BCINexus cloud features are explicit actions. Signing in does not automatically publish or upload every file in a study.

Teams

Teams are BCINexus workspaces for labs and organizations. They add shared quota, members, roles, study sharing, file sharing, dataset manifests, tasks, pages, activity logs, and study requests.

Training still runs locally on each researcher's machine. Team features coordinate study state, shared artifacts, permissions, and collaboration records.

Privacy

BCILattice is local-first. Imported recordings remain local unless you explicitly choose a cloud, team, share, publish, or AI-provider workflow that sends selected information elsewhere.

• Raw recordings are not uploaded automatically after import.
• Cloud sync and publishing should be treated as explicit data-transfer actions.
• AI Chat with remote providers sends prompt content to that provider endpoint.
• Regulated use depends on your deployment, data handling policy, agreements, and institutional review.

For compliance posture and procurement language, use the Security & Compliance guide rather than assuming the app carries a blanket certification.

Troubleshooting