BCILattice FAQ
Straight answers about the BCILattice desktop app, BCINexus cloud, data handling, plans, and the most common things that go wrong.
General
Q: What is BCILattice?
BCILattice is the NeuroMatrix desktop application for BCI and neuroscience research. One local workspace covers the whole study: import recordings, preprocess signals, design paradigms, build and train ML pipelines, track experiments, inspect model behavior, and export reports.
Q: What is BCINexus, and how is it different?
BCILattice is the desktop tool you run on your own machine, and it requires a BCINexus account for access. BCINexus also provides the connected layer around it: plan limits, cloud backup, the community study catalog, public publishing, private share links, reviewer workflows, and team workspaces.
Q: Do I need to write code?
No. The whole pipeline is visual: import data, configure preprocessing, design Neural Flow paradigms, wire up ML Suite blocks, run training in Workflow, compare runs, and export reports, all without code. Custom code blocks are there when you want lower-level control, not as a requirement.
Q: Does it work offline?
No. There is no offline mode, and an active account is required to run BCILattice. The compute-heavy work is all local — importing, preprocessing, pipeline building, training, analysis, and report generation run on your machine — but the connection still has to be there.
Paid features come from a licence check against the server, never from cached data on disk. If the connection drops mid-session the app keeps running and paid features survive for the remaining life of the current licence token, roughly ten minutes; after that it falls back to Free features and retries in the background, restoring them on the first success. Starting with no connection at all means a Free session until you get one.
Internet is also needed for cloud sync, community publishing and imports, update checks, and remote AI providers in AI Chat.
Q: Which signal modalities are supported?
EEG, fNIRS, EMG, and EOG each have a dedicated import and preprocessing path. EEG, fNIRS, and EMG are the most developed research flows; EOG focuses on filtering, annotation, and feature extraction.
Q: Who is it for?
BCI researchers, neuroscience labs, students, ML engineers, and teams that want a reproducible local workflow without rebuilding the import, preprocessing, training, and reporting stack from scratch.
Install & Setup
Q: What hardware do I need?
A modern desktop or workstation with at least 8 GB RAM (16 GB+ for large multi-subject datasets), a multi-core CPU, and disk space for your recordings plus derived outputs. A CUDA-capable NVIDIA GPU speeds up deep-learning training but is not required, CPU training is always available.
Q: Do I need to install Python myself?
No, for packaged builds, the installer bundles the application runtime. You only manage a Python environment if you run BCILattice from a developer source checkout, in which case use the study's environment and dependency files.
Q: Which operating systems are supported?
BCILattice is a PySide6 desktop application, so it is cross-platform by design. The Download page is the source of truth for which packaged installers are currently published. If your platform is not listed there, it is a developer/source setup until an installer ships.
Q: What does 'Server not ready' or 'Server: Not Running' mean?
The desktop UI talks to a local FastAPI service running on your own machine. If that service has not finished starting, API-backed pages may wait, show an empty state, or ask you to retry. Restart BCILattice first. If it keeps happening, check the app logs and make sure no other process is holding the local server port.
Q: Do I need administrator rights?
Day-to-day use does not require admin rights. Whether installation does depends on the package and install location. If your institution locks down software installs, use a user-level install or ask IT to approve the package.
Data & Studies
Q: What file formats can I import?
By modality: EEG, EDF, BDF, GDF, FIF, VHDR, SET, CNT, TXT, CSV, XLSX. fNIRS, SNIRF, FIF, TXT, CSV, XLSX. EMG, EDF, BDF, GDF, FIF, TXT, CSV. EOG, EDF, BDF, FIF, TXT, CSV, XLSX.
Q: Can I import a whole multi-subject dataset at once?
Yes. Data Manager has folder import: point it at a directory, and it scans compatible files, preserves your subject/session structure, and lets you assign modalities and labels before adding everything to the study.
Q: Does BCILattice change my original recordings?
No. Preprocessing is non-destructive. Source files are never modified, derived data, preprocessing settings, study metadata, and output artifacts are all written separately.
Q: What is the study file format?
Local studies use .blts. It stores study metadata and the workflow state BCILattice needs to reopen your study, and it is the file to move when you carry work between machines. Older session/share exports may still open, but new work should use the study workflow.
Q: Where is my data stored locally?
Imported recordings and derived outputs stay on your machine. Trained model artifacts live in a global per-user store (~/.bcilattice/experiments) and are referenced by experiments; the .bciproj bundle pulls them in when you export or share a study.
Q: Can I export reports and results?
Yes. Reports export as PDF, HTML, JSON study documents, and CSV metric tables. Experiment Hub can also export run records as CSV for analysis outside BCILattice.
Desktop Workflow
Q: What is the recommended order of work?
Create or open a study → import data in Data Manager → configure Preprocessing → explore in Analysis → design a paradigm in Neural Flow → build the pipeline in ML Suite and assign data in Workflow → train → review Experiment Hub and Results → inspect Model Analysis → generate a report or publish.
Q: What is Data Manager?
The entry point for files, subjects, sessions, modalities, labels, and quality checks. Everything downstream, preprocessing, analysis, workflow assignment, and training, reads from the records you define here.
Q: What is Neural Flow?
The visual paradigm and stimulus designer. You lay out task timing, cues, trial markers, motor-imagery or cognitive blocks, rest periods, and loops, then compile a paradigm definition you can pair with recordings or session labels.
Q: What is ML Suite?
The visual machine-learning area. It bundles MLFlow graph editing, Workflow data assignment, training dashboards, curated BCILattice blocks, and a large catalog of scikit-learn, PyTorch, MNE, preprocessing, and evaluation components.
Q: What is Experiment Hub, and how is it different from Results?
Experiment Hub is your run history, it stores every completed training run so you can compare, inspect, export, and restore experiment state. Results focuses on the metrics themselves and cross-experiment comparison. Use Experiment Hub to ask "what changed between runs?" and Results to ask "which run is best, and by how much?"
Q: What is Model Analysis?
The interpretability surface: SHAP attributions, learned weights, and activation maps where the selected model and data support them. It is about understanding why a model behaves the way it does, not just its score.
Q: Does it support live recording and edge devices?
Yes, the workspace includes Record Session (live streaming acquisition) and Edge Devices (on-device model deployment) surfaces. Both are marked experimental in the app and not yet validated against physical acquisition hardware, so verify channel labels and sample rates against your amplifier before relying on a recording. They are optional local tools; analysing imported datasets does not need them.
Machine Learning
Q: Which models are available?
The catalog includes BCI-specific EEG architectures, EEGNet, ShallowConvNet, DeepConvNet, EEGConformer, and ATCNet, alongside sequence and transformer models, edge-focused models, classical estimators (LDA, SVM, random forests, gradient boosting, and more), feature selection, dimensionality reduction, evaluation metrics, and custom blocks.
Q: Does training use my CPU or GPU?
Training runs on your machine. PyTorch models use a compatible NVIDIA GPU when one is available and fall back to CPU otherwise. The actual speedup depends on your installed runtime, drivers, and the chosen model. There is no cloud GPU, BCINexus does not host training.
Q: How do I avoid data leakage?
Keep subject/session splits explicit in Workflow and use validation or cross-validation blocks that match your study design. Never fit scalers, feature selectors, or dimensionality reduction on the full dataset before splitting, fit them inside the training fold only. For subject-generalization claims, use subject-aware validation such as leave-one-subject-out.
Q: Can I export trained models?
Yes, on the Lab plan and up. Export runs from the Model Analysis “Export Model” action or the desktop edge workflow for supported experiments. PyTorch and ONNX are the main portable targets (scikit-learn and other native formats are supported too), with edge-specific options where the required conversion tools are installed. Free and Researcher plans do not include model export or edge deployment.
Q: Can I use my own Python code?
Yes, there are custom-code entry points for preprocessing, feature extraction, and pipeline work. Document your dependencies, seeds, and data splits when you do: undocumented custom code is the easiest way to make a study hard to reproduce.
AI Chat
Q: Which AI providers can I connect?
AI Chat connects to your own provider accounts: Gemini (Google), ChatGPT (OpenAI), Claude (Anthropic), Mistral, DeepSeek, a free-tier Groq API, and a local Ollama endpoint. You supply the API key (or run Ollama locally); BCILattice does not resell access.
Q: Where do my AI Chat messages go?
Straight from your desktop to the provider endpoint you selected, using your own credentials. The BCINexus backend is never in the loop. Treat any prompt to a remote provider as data leaving your machine, use the local Ollama endpoint when prompts must stay on-device.
Q: What can AI Chat actually do?
It is grounded in your work through retrieval over app knowledge, your experiments, sessions, and pipelines, so you can ask it to explain a preprocessing choice, interpret a result, or troubleshoot a pipeline with context from your own study, not just generic answers.
BCINexus Cloud
Q: Do I need a BCINexus account?
Yes. A BCINexus account is required to operate BCILattice. Local analysis and training still run on your machine; cloud sync, private sharing, team workspaces, community publishing, reviewer workflows, and dashboard features are connected account services.
Q: Can I import community studies?
Yes. Browse the community catalog on BCINexus or from the desktop Community entry points, then import it into a study, as a new study or into the current one. Always review the imported graph and settings before running it on your own data.
Q: How do I publish a study or experiment?
Use the desktop Publish flow from the study workspace or the Import / Export page. You choose the title, description, modality, task type, visibility, and which artifacts to include. Published items are versioned and tracked through the BCINexus dashboard.
Q: What is Cloud Submissions?
A desktop-side view of your BCINexus publish/review state, so you can see whether a submitted item is pending, accepted, rejected, or needs follow-up without leaving the app.
Plans & Teams
Q: What are the current plan limits?
These are the live backend quotas:
| Plan | Uploads / month | Storage | Team |
|---|---|---|---|
| Free | 3 | 100 MB | — |
| Researcher | 15 | 500 MB | — |
| Lab | 50 | 5 GB shared | 5 pooled seats |
| Enterprise | Unlimited | From 50 GB | Contract-defined seats |
Community downloads are unlimited on every plan, including Free — we do not charge anyone to read what someone else chose to publish. Upload allowances reset on the 1st of each month.
An "upload" is a published or cloud-stored item; downloads from the community are metered weekly on the Free plan only.
Q: What does a team workspace add?
Team plans (Lab and above) unlock shared workspaces: members and roles, shared studies and files, dataset manifests, tasks, pages, activity logs, and study requests, all drawing on the team's quota instead of an individual's.
Q: Can my institution use a purchase order?
Yes, route Enterprise arrangements through the sales/enterprise contact flow, since legal review, deployment model, support terms, and billing vary by organization.
Privacy & Compliance
Q: Does importing a recording upload it to the cloud?
No. Imported recordings stay local. Data leaves your machine only when you explicitly run a cloud sync, publish, share, or AI-provider action that includes it. This separation matters for IRB, clinical, and restricted-research settings.
Q: What does AI Chat send to providers?
Whatever you put in the prompt, sent directly to the provider you connected, using your credentials. Assume prompt content leaves your machine unless you are using the local Ollama endpoint.
Q: Can I use it with regulated or clinical data?
It supports local-first, institution-controlled workflows, but compliance depends on your deployment, policies, agreements, and data handling. The product does not carry a blanket HIPAA, GDPR, SOC 2, or clinical certification, review the Security & Compliance page and involve your compliance team.
Q: How do I delete my cloud account data?
Use account settings for self-service controls. For privacy or right-to-erasure requests, email [email protected].
Troubleshooting
Q: Import fails with 'unsupported format', what do I check?
Confirm the extension matches the real file type, open it in a trusted external tool, and make sure the selected modality is correct. For CSV/TXT/XLSX, check that the table is numeric and the label column is clearly identified.
Q: Training is slow, what first?
Start small: fewer folds, a lighter model, and a sanity check on your data shape. Confirm the GPU runtime is actually being used. When debugging a new dataset, run a classical baseline (LDA or SVM) before reaching for deep models.
Q: A Neural Flow or ML Suite graph won't compile, why?
Almost always an incomplete graph, a missing required parameter, an incompatible connection, or an output block that doesn't match what training expects. Read the graph validation message before changing the model.
Q: Cloud sync or publishing fails, what do I check?
Sign-in state, active workspace, plan quota, internet connection, and whether the selected artifacts are valid. If a team workspace is active, quota and permissions come from the team, not your personal plan. An expired session needs a fresh sign-in, refreshing only works before expiry.
Q: How do I contact support?
Email [email protected] with your app version, operating system, the module where the issue happened, and the relevant error text from the desktop logs.