Installing Julia

Note: NeuroAnalyzer is under active development and its API is subject to change.

NeuroAnalyzer requires the current stable release of Julia (see Requirements). The recommended way to install and update Julia is juliaup:

# Linux, FreeBSD, macOS
curl -fsSL https://install.julialang.org | sh

# Windows
winget install --name Julia --id 9NJNWW8PVKMN -e -s msstore

Later updates:

juliaup update

Multi-threading

NeuroAnalyzer processes channels and epochs in parallel. Julia starts with a single thread unless told otherwise, and the number of threads cannot be changed after Julia has started.

Option 1 - command line (all platforms):

julia -t auto

auto uses all available CPU threads; a number (e.g. julia -t 12) can be given instead.

Option 2 - environment variable, so that every Julia session uses multiple threads.

Linux, FreeBSD, macOS: add to your shell configuration file (~/.profile, ~/.bashrc or ~/.zshrc):

export JULIA_NUM_THREADS=auto

Windows (PowerShell; open a new terminal afterwards):

setx JULIA_NUM_THREADS auto

In Visual Studio Code, set julia.NumThreads in the Julia extension settings instead.

Check the number of threads in the REPL:

Threads.nthreads()

Setting JULIA_NUM_THREADS inside Julia (e.g. in ~/.julia/config/startup.jl) has no effect, because the threads are created before startup.jl is run.

Package precompilation runs in parallel by default; the number of parallel tasks can be limited with the JULIA_NUM_PRECOMPILE_TASKS environment variable (e.g. on a machine with little RAM).

Installation

From the Julia General Registry (latest released version):

using Pkg
Pkg.add("NeuroAnalyzer")

From the repository (always up to date):

The stable branch is main and is installed by default:

using Pkg
Pkg.add(url = "https://codeberg.org/AdamWysokinski/NeuroAnalyzer.jl")

The development branch, devel, contains the newest features and fixes, but may be less stable:

using Pkg
Pkg.add(url = "https://codeberg.org/AdamWysokinski/NeuroAnalyzer.jl",
        rev = "devel")

Update NeuroAnalyzer (installed in either way) and its dependencies with:

using Pkg
Pkg.update()

To return from a repository version to the registered release, use Pkg.free("NeuroAnalyzer").

Installation in a Dedicated Environment

Installing NeuroAnalyzer in a separate project environment keeps its dependencies apart from your other Julia projects and records the exact package versions used in an analysis (in Project.toml and Manifest.toml), which helps reproducibility:

mkdir my_analysis
cd my_analysis
julia -t auto --project=.

using Pkg
Pkg.add("NeuroAnalyzer")

Later, start Julia with julia -t auto --project=. in that folder to use the environment. On another computer, copy both .toml files and run Pkg.instantiate() to install the same versions.

Developing NeuroAnalyzer: to work on the source code, clone the repository and use its own environment:

git clone https://codeberg.org/AdamWysokinski/NeuroAnalyzer.jl
cd NeuroAnalyzer.jl
julia -t auto --project=.

using Pkg
Pkg.instantiate()

To use the local copy from another environment, run Pkg.develop(path = "path/to/NeuroAnalyzer.jl") there.

Running NeuroAnalyzer

Start Julia and enter the following in the REPL:

using NeuroAnalyzer

The first using NeuroAnalyzer after installation or update triggers precompilation, which takes several minutes. Afterwards loading takes a few seconds, and the first call of each function in a session includes its compilation time. To reduce this latency, a custom sysimage can be created using PackageCompiler.jl - see this tutorial for step-by-step instructions.

Show version and info (for reproducibility):

version()

"0.26.11"

info()

     NeuroAnalyzer: 0.26.11-dev
NeuroAnalyzer path: /home/eb/.julia/packages/NeuroAnalyzer/XKHvs/
     Julia version: 1.13.2
      Plugins path: /home/eb/NeuroAnalyzer/plugins
    Resources path: /home/eb/.julia/artifacts/caee10403ca3e62f4cbc0d1c98fc01f707e928af/neuroanalyzer-resources
 Show progress bar: false
           Verbose: false
      Exclude bads: false
            Colors: false
           Threads: 48 [set using `JULIA_NUM_THREADS` environment variable or Julia --threads command-line option]
For best performance, `JULIA_NUM_THREADS` (48) should be less than the number of CPU threads (48).

Imported packages:
                Artifacts 1.11.0
                    Cairo 1.1.1
             ColorSchemes 3.31.0
       ComplexityMeasures 3.12.0
       ContinuousWavelets 1.2.0
                  Crayons 4.2.0
                    Dates 1.11.0
            Deconvolution 1.1.1
                    DICOM 0.11.0
                  Dierckx 0.5.4
                      DSP 0.8.6
                   Einsum 0.4.1
                     FFTW 1.10.0
                   FileIO 1.20.0
                FilePaths 0.9.0
              FindPeaks1D 0.1.8
             FourierTools 0.5.1
        FractalDimensions 1.9.6
           GeometryBasics 0.5.13
                      Git 1.5.0
                  GLMakie 0.13.16
                       GR 0.73.27
                     Gtk4 0.7.14
                    Hurst 0.1.5
        ImageBinarization 0.3.1
           ImageFiltering 0.7.12
          ImageMorphology 0.4.7
                   Images 0.26.2
      InformationMeasures 0.3.1
           Interpolations 0.16.3
                   Jacobi 0.7.0
                     JLD2 0.6.7
                     JSON 1.11.0
            KernelDensity 0.6.12
            LibSerialPort 0.5.2
            LinearAlgebra 1.13.0
           LinRegOutliers 0.11.10
                  Logging 1.11.0
                      MAT 0.12.1
                      MLJ 0.23.3
                      NPZ 0.4.3
                    Optim 2.3.2
                   PiGPIO 0.2.1
                      Pkg 1.13.0
                    Plots 1.41.7
              Polynomials 4.1.3
              Preferences 1.6.1
             PrettyTables 3.5.0
            ProgressMeter 1.13.0
                   Random 1.11.0
                     REPL 1.11.0
            SavitzkyGolay 0.9.1
   ScatteredInterpolation 0.3.6
                StatsFuns 1.5.3
                 StatsKit 0.3.1
              StatsModels 0.7.10
               StatsPlots 0.15.8
                TimeZones 1.22.3
                     TOML 1.0.3
                    Trapz 2.0.3
                      WAV 1.2.0
                 Wavelets 0.10.2
              WaveletsExt 0.2.3
                      XDF 0.2.1

Use Julia’s built-in help system to access documentation for any function, e.g. ?NeuroAnalyzer.plot.

Notebooks

NeuroAnalyzer works with Pluto reactive notebooks (with PlutoUI for interactive controls):

using Pkg
Pkg.add(["Pluto", "PlutoUI"])
using Pluto
Pluto.run()

An example Pluto notebook is located here.

NeuroAnalyzer can also be used with Jupyter:

using Pkg
Pkg.add("IJulia")
using IJulia
notebook()

An example Jupyter notebook is located here.

To use multiple threads in Jupyter, create a kernel with threads enabled:

using IJulia
installkernel("Julia (auto threads)"; env = Dict("JULIA_NUM_THREADS" => "auto"))

Docker Image

NeuroAnalyzer is also available as a pre-built Docker image (Linux; the X11 options allow plots and GUIs to be displayed on the host):

docker pull neuroanalyzer/neuroanalyzer:latest
xhost +local:docker
docker run -it -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix \
    neuroanalyzer/neuroanalyzer:latest

To work with your own files, mount a folder into the container, e.g. -v $HOME/data:/data.