Installation

ncpi requires Python 3.10+.

The current PyPI release of ncpi is a beta pre-release. Install it with pip install --pre ncpi so pip includes pre-release versions.

1) Conda setup notes (Windows + Unix)

We strongly recommend installing ncpi in a dedicated Conda environment.

If you need to install Anaconda first, download it from the official page: https://www.anaconda.com/download

On Windows, start from Anaconda Prompt (recommended). Some packages, including NEST and NEURON, require a Linux environment and should be installed through WSL2. See Section 3 for the native Windows and WSL2 installation options.

2) Install ncpi on Unix (Linux/macOS)

conda create -n ncpi-env python=3.10 -y
conda activate ncpi-env
pip install --pre ncpi

NEST on Unix/macOS (for LIF simulation examples)

If you run examples that depend on NEST (for example in examples/simulation), install it in the same environment:

conda install -c conda-forge nest-simulator=3.8

If nest-simulator is not available for your platform/channel combination, follow the official NEST build/install instructions: https://nest-simulator.readthedocs.io/

3) Install ncpi on Windows

There are two installation options on Windows. Choose the option based on whether your workflow requires NEST or/and NEURON:

1. Native Windows Anaconda environment: suitable for core ncpi workflows and optional dependencies that do not require NEST or NEURON.
2. Anaconda environment inside WSL2: required for NEST- and NEURON-based simulations. NEST and the Python neuron package cannot be installed in the supported native Windows environment, but they can be installed in WSL because it provides a Linux environment.

The Windows and WSL Conda environments are completely separate. Packages installed in one environment are not available in the other.

Option A: Native Windows installation

In Anaconda Prompt, create the environment and install ncpi:

conda create -n ncpi-env python=3.10 -y
conda activate ncpi-env
pip install --pre ncpi

Use this option when you do not need NEST, NEURON, or the ncpi extras that depend on them, such as fieldpotential, examples, tests, and all.

Option B: WSL2 installation with NEST and NEURON

First, install WSL2 with Ubuntu from an Administrator PowerShell:

# One-time WSL2 setup
wsl --install

After restarting Windows if requested, open Ubuntu and install a Linux Conda distribution inside WSL. Then create the WSL environment and install ncpi and NEST:

conda create -n ncpi-env python=3.10 -y
conda activate ncpi-env
pip install --pre ncpi
conda install -c conda-forge nest-simulator=3.8

4) Optional Dependencies

ncpi supports optional extras. Install only what your workflow needs. Because the current PyPI release is a beta pre-release, include --pre when installing extras too.

Extras shortcuts

pip install --pre "ncpi[parser]"          # extended parser backends
pip install --pre "ncpi[fieldpotential]"  # kernel/CDM/LFP + M/EEG forward models [Windows: WSL required]
pip install --pre "ncpi[webui]"           # WebUI runtime backends
pip install --pre "ncpi[examples]"        # dependencies for example scripts [Windows: WSL required]
# Note: the dependencies listed below refer to Section 6 (Optional backends notes).
pip install --pre "ncpi[tests]"           # test stack dependencies [Windows: WSL required]
pip install --pre "ncpi[analysis]"        # statistics + EEG/MEG analysis helpers
pip install --pre "ncpi[hctsa]"           # hctsa backend support
pip install --pre "ncpi[all]"             # all optional dependencies [Windows: WSL required]

5) WebUI: installation and usage

The WebUI must be run from the ncpi repository source. After activating your Conda environment, install its dependencies with:

pip install --pre "ncpi[webui]"

Start WebUI

From the repository root, with the Conda environment activated:

python webui/launcher.py local

The launcher starts Flask and opens the default browser at:

http://127.0.0.1:5000

The following compatibility command also starts the local WebUI:

python webui/app.py

For best results, we recommend running the WebUI in Chrome, as our tests are most stable there and we have observed a couple of issues in other browsers.

Run on a remote server over SSH

Remote command

Run the following command from the ncpi repository on your local machine:

python webui/launcher.py remote <user>@<server> \
  --ssh-port <P> \
  --local-port <L> \
  --remote-port <R> \
  --remote-dir <path/to/ncpi> \
  --python <path/to/python>

Replace the placeholders:

• <user>@<server>: SSH destination (e.g., username@example.org)
• <P>: SSH port (default: 22)
• <L>: Local port on your machine for the browser (default: 5000)
• <R>: Remote port on the server where Flask runs (default: 5000)
• <path/to/ncpi>: Absolute path to the ncpi repository on the server
• <path/to/python>: Absolute path to Python executable on the server (from which python)

The browser opens http://127.0.0.1:<L>. Keep the launcher terminal open while using the WebUI. Press Ctrl+C to close the SSH tunnel and stop the remote Flask process.

Start WebUI manually with Flask

To start the server locally with Flask, activate the Conda environment and run the following command from the <path/to/ncpi>/webui directory:

flask run --port <PORT>

Then manually open http://127.0.0.1:<PORT> in your local browser.

To run Flask on a remote server, first connect from your local machine and create an SSH tunnel:

ssh -L <PORT>:localhost:<PORT> <user>@<server>

In the resulting remote SSH session, activate the Conda environment, change to the <path/to/ncpi>/webui directory, and start Flask:

flask run --port <PORT>

Then manually open http://127.0.0.1:<PORT> in your local browser. Keep the SSH session open while using the WebUI.

Windows note

You can run the same commands from Anaconda Prompt or PowerShell. Run the WebUI from WSL if your workflow requires NEST-based simulations or NEURON-dependent field-potential computations.

6) Optional backends notes

Optional backends are listed in Section 4 (Optional Dependencies). Install only the extras required by your workflow.

analysis/tests (R) note

Both the analysis and tests extras include rpy2 (R-backed dependency). Before installing ncpi[analysis] or ncpi[tests], make sure R is installed on your system (e.g. from https://cran.r-project.org/ or your package manager). Installing rpy2 via pip or conda can fail if a suitable R installation is not present. If you use Conda, you can install R with: conda install -c conda-forge r-base.

The Analysis class uses the following R packages for specific methods:

• lmer_tests(...): lme4, emmeans
• lmer_selection(...): lme4, buildmer

Install options for the R backend:

• In R: install.packages(c("lme4", "emmeans", "buildmer"), repos="https://cloud.r-project.org")
• With conda-forge: conda install -c conda-forge r-base rpy2 r-lme4 r-emmeans r-buildmer

If you want to run tests without setting up R, avoid ncpi[tests] and install only the specific test dependencies you need. R-dependent tests (e.g. tests/Analysis/test_lmer.py) are skipped automatically when rpy2/R is unavailable.

If you install ncpi[analysis] or ncpi[tests], Matplotlib may select a Qt backend because Qt-related packages such as PyQt5, qtpy, or pyvistaqt are available. On minimal Linux, WSL, Docker, or remote-server environments, Qt may fail to initialize the xcb platform plugin unless the corresponding system libraries are installed. On Ubuntu/Debian systems, install them with:

sudo apt install libxcb-cursor0 libxcb-xinerama0 libxkbcommon-x11-0

For headless runs where no plot window is needed, use a non-GUI Matplotlib backend instead:

MPLBACKEND=Agg python example.py

playwright note

To use Playwright-based tests, install the required browsers with:

python -m playwright install

hctsa note

For hctsa-based features, install hctsa first: https://github.com/benfulcher/hctsa

The hctsa extra depends on the hctsa MATLAB toolbox and the MATLAB Engine for Python. Attempting to install a matlabengine pip package without MATLAB installed (or without a matching MATLAB Engine distribution) can fail or raise errors. The recommended approach is to install MATLAB first, then install the MATLAB Engine for Python from the MATLAB installation directory (see MathWorks docs: https://www.mathworks.com/help/matlab/matlab_external/install-the-matlab-engine-for-python.html), or otherwise ensure the engine distribution you install matches your MATLAB version. After that, install hctsa and pass the hctsa repository path as hctsa_folder when invoking hctsa-backed features in ncpi.

Note: the tests extra does not install matlabengine; hctsa tests are skipped unless MATLAB Engine and an hctsa folder are available.