> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nimbusbci.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch Inference Configuration

> Configure Nimbus for offline BCI inference, calibration, validation, and research analysis across multiple trials.

Batch inference processes complete trials offline. Use it for calibration, validation, model comparison, research studies, and quality review. Use [Streaming Inference Configuration](/inference-configuration/streaming-inference) when predictions must update during a live trial.

<Tip>
  Python product path: calibrate [`Personalizer`](/personalizer/overview) on labeled trials (embeddings or classical features), then evaluate `BrainState` offline. Standalone heads (`NimbusLDA`, …) remain valid for research CV.
</Tip>

## When To Use Batch

* Calibrate a Personalizer / head on labeled trials.
* Evaluate held-out sessions or subjects.
* Compare model families and hyperparameters.
* Run preprocessing diagnostics before deployment.
* Analyze confidence, entropy, accuracy, and ITR after a session.

## Data Contracts

| SDK | Typical Batch Shape | Notes |
| - | - | - |
| Python Personalizer / heads | `(n_trials, n_features)` | Embeddings after encode, or classical features; sklearn-compatible heads. |
| Python `BCIData` utilities | `(n_features, n_samples, n_trials)` | Used by lower-level inference helpers. |
| Julia `BCIData` | `(n_features, n_samples, n_trials)` | Labels are typically 1-indexed integers. |

All batch workflows should use embeddings or preprocessed features, not raw EEG.

## Basic Pattern

<Tabs>
  <Tab title="Python Personalizer">
    ```python theme={null}
    from nimbus_bci import Personalizer, wrap

    enc = wrap(model.encode, model_id="partner-encoder", embedding_dim=64)
    adapter = Personalizer(
        encoder=enc,
        head="lda",
        classes=["left", "right"],
        preset="research",
    )
    adapter.fit(X_cal, y_cal)
    states = adapter.predict(X_test)  # list[BrainState]
    print(states[0].intent, states[0].confidence)
    ```
  </Tab>

  <Tab title="Python head">
    ```python theme={null}
    from nimbus_bci import NimbusLDA
    from sklearn.model_selection import cross_val_score

    X = load_features()  # (n_trials, n_features)
    y = load_labels()

    clf = NimbusLDA()
    scores = cross_val_score(clf, X, y, cv=5)

    clf.fit(X, y)
    probabilities = clf.predict_proba(X)
    predictions = clf.predict(X)
    ```
  </Tab>

  <Tab title="Julia">
    ```julia theme={null}
    using NimbusSDK
    using Statistics

    features = load_features()  # (n_features, n_samples, n_trials)
    labels = load_labels()

    metadata = BCIMetadata(
        sampling_rate = 250.0,
        paradigm = :motor_imagery,
        feature_type = :csp,
        n_features = size(features, 1),
        n_classes = length(unique(labels)),
        chunk_size = nothing
    )

    data = BCIData(features, metadata, labels)
    model = train_model(NimbusLDA, data; iterations=50)
    results = predict_batch(model, data)

    accuracy = mean(results.predictions .== labels)
    ```
  </Tab>
</Tabs>

## Evaluation Checklist

* Split by session or subject when testing generalization.
* Estimate normalization parameters on training folds only.
* Report accuracy with confidence and rejection rate.
* Inspect posterior entropy for uncertain trials.
* Compare against a simple `NimbusLDA` baseline before tuning.

## Batch Diagnostics

Run diagnostics when batch accuracy is unexpectedly low:

```julia theme={null}
report = diagnose_preprocessing(data)

if !isempty(report.errors)
    error("Invalid batch data: $(report.errors)")
end
```

Common issues include wrong feature shape, raw EEG passed as features, inconsistent label encoding, missing normalization, and mismatched model metadata.

## Batch vs Streaming

| Need | Use |
| - | - |
| Offline calibration | Batch |
| Cross-validation | Batch |
| Research analysis | Batch |
| Live feedback | Streaming |
| Chunk-by-chunk command updates | Streaming |

Most production BCI systems use both: batch for calibration and validation, streaming for live operation.

## Next Read

<CardGroup cols={2}>
  <Card title="Feature Normalization" icon="arrow-up-down" href="/inference-configuration/feature-normalization">
    Keep train/test/deployment scales consistent.
  </Card>

  <Card title="Streaming Inference" icon="activity" href="/inference-configuration/streaming-inference">
    Configure live chunk processing.
  </Card>

  <Card title="Basic Examples" icon="play" href="/examples/basic-examples">
    Compact batch and streaming recipes.
  </Card>

  <Card title="Model Specification" icon="brain" href="/model-specification">
    Choose a model before evaluation.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.