NeuroAnalyzer.jl documentation

na_info()

Show NeuroAnalyzer and imported packages versions.

Arguments

Nothing

Returns

• Nothing

na_set_colors(value)

Change colors preference.

Arguments

• value::Bool: value

Returns

• Nothing

na_set_exclude_bads(value)

Change exclude_bads preference.

Arguments

• value::Bool: value

Returns

• Nothing

na_set_prefs(; <keyword arguments>)

Set and save NeuroAnalyzer preferences.

Arguments

• progress_bar::Bool
• verbose::Bool
• exclude_bads::Bool
• colors::Bool

Returns

• Nothing

na_set_progress_bar(value)

Change progress_bar preference.

Arguments

• value::Bool: value

Returns

• Nothing

na_set_verbose(value)

Change verbose preference.

Arguments

• value::Bool: value

Returns

• Nothing

na_version()

Convert NeuroAnalyzer version to string.

Arguments

Nothing

Returns

• VER::String

na_plugins_install(plugin)

Install NeuroAnalyzer plugin from remote Git repository or from local .TAR.GZ/.ZIP archive (requires unzip or tar command to be available).

Arguments

• plugin::String: plugin Git repository URL or file name (with full path)

Returns

• Nothing

na_plugins_list()

List NeuroAnalyzer plugins.

Arguments

Nothing

Returns

• Nothing

na_plugins_reload()

Reload NeuroAnalyzer plugins.

Arguments

Nothing

Returns

• Nothing

na_plugins_remove(plugin)

Remove NeuroAnalyzer plugin.

Arguments

• plugin::String: plugin name

Returns

• Nothing

na_plugins_update(plugin)

Update NeuroAnalyzer plugin(s).

Arguments

• plugin::String: plugin to update; if empty, update all

Returns

• Nothing

size(obj)

Return the size of the object data array.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object

Returns

• Tuple{Int64, Int64, Int64}: (channels, samples, epochs).

size(obj, d)

Return the size of the object data array along dimension d.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• d::Int64: dimension index; must be in [1, ndims(obj.data)]

Returns

• Int64: size along dimension d

add_note(obj; <keyword arguments>)

Return a copy of obj with the recording note set to note. The original object is not modified.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• note::String: note text to store

Returns

• NeuroAnalyzer.NEURO: new NEURO object with the updated recording note

add_note!(obj; <keyword arguments>)

Set the recording note in obj in-place.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• note::String: note text to store

Returns

• Nothing

aff_mni2tal(pts)

Convert MNI coordinates to Talairach coordinates using an affine transform.

Applies the Brett affine transformation:

• x′ = 0.88x − 0.8
• y′ = 0.97y − 3.32
• z′ = 0.05y + 0.88z − 0.44

Arguments

• pts::Vector{<:Number}: MNI [X, Y, Z] coordinates

Returns

• Vector{Float64}: Talairach [X, Y, Z] coordinates

References

Brett M. https://www.brainmap.org/training/BrettTransform.html

aff_tal2mni(pts)

Convert Talairach coordinates to MNI coordinates using the inverse affine transform.

Applies the inverse of the Brett affine transformation:

• x = (x′ + 0.8) / 0.88
• y = (y′ + 3.32) / 0.97
• z = (z′ − 0.05y + 0.44) / 0.88

Arguments

• pts::Vector{<:Number}: Talairach [X, Y, Z] coordinates

Returns

• Vector{Float64}: MNI [X, Y, Z] coordinates

References

Brett M. https://www.brainmap.org/training/BrettTransform.html

apply(obj; <keyword arguments>)

Apply a custom function to selected channels and epochs of a NEURO object.

The function string f must reference the signal data using the placeholder variable obj, which is substituted at runtime with the actual channel data (a Vector{Float64} representing one channel × one epoch slice).

Example: f = "cumsum(obj)" or f = "obj .^ 2".

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• ch::Union{String, Vector{String}, Regex}: channel name(s)
• f::String: Julia expression to evaluate, using obj as the signal placeholder

Returns

• Array{Float64, 3}: result array, shape (channels, epoch length, epochs)

areduce(a, f; <keyword arguments>)

Reduce an array by resampling along its second axis at regular intervals of n.

Useful for downsampling a frequency axis (and its associated data) when the number of frequency bins is very large. Only the nearest existing frequency bin to each target frequency is used (via vsearch); no interpolation is performed.

Arguments

• a::AbstractArray: 2- or 3-dimensional data array whose second axis corresponds to f, shape (channels, frequencies) or (channels, frequencies, epochs)
• f::AbstractVector: frequency (or index) vector; length(f) must equal size(a, 2)
• n::Float64=0.5: step size between retained values (in the same units as f); smaller values retain more points; larger values reduce more aggressively

Returns

• Array{eltype(a), ndims(a)}: deduced data array
• Vector{eltype(f)}: reduced frequency vector

arr2mat(x)

Reshape a 3-D array of shape (1, samples, epochs) into a (epochs, samples) matrix.

Arguments

• x::AbstractArray: 3-D input array; first dimension must equal 1

Returns

• AbstractMatrix: matrix of shape (size(x, 3), size(x, 2))

band_frq(obj, band)

Return the frequency limits for a named EEG band.

When band = :list, the available band names are printed to stdout and the function returns (0.0, 0.0) as a sentinel (rather than nothing, which would violate the declared return type).

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• band::Symbol: band name (see list below or pass :list to print all names):
  • :list
  • :total
  • :delta: 0.1-4.0 Hz
  • :theta: 4.0-8.0 Hz
  • :alpha: 8.0-3.0 Hz
  • :alpha_lower: 8.0-10.5 Hz
  • :alpha_higher: 10.5-13.0 Hz
  • :beta: 14.0-30.0 Hz
  • :beta_lower: 14.0-25.0 Hz
  • :beta_higher: 25.0-30.0 Hz
  • :gamma: 30.0-150.0 Hz
  • :gamma_1: 30.0-40.0 Hz
  • :gamma_2: 40.0-50.0 Hz
  • :gamma_lower: 30.0-80.0 Hz
  • :gamma_higher: 80.0-150.0 Hz

Returns

• Tuple{Float64, Float64}: (low_Hz, high_Hz) limits, clamped to the Nyquist frequency if necessary

band_frq(fs, band)

Return the frequency limits for a named EEG band.

When band = :list, the available band names are printed to stdout and the function returns (0.0, 0.0) as a sentinel.

Arguments

• fs::Int64: sampling rate in Hz; must be ≥ 1
• band::Symbol: band name (see list below or pass :list to print all names):
  • :list
  • :total
  • :delta: 0.1-4.0 Hz
  • :theta: 4.0-8.0 Hz
  • :alpha: 8.0-3.0 Hz
  • :alpha_lower: 8.0-10.5 Hz
  • :alpha_higher: 10.5-13.0 Hz
  • :beta: 14.0-30.0 Hz
  • :beta_lower: 14.0-25.0 Hz
  • :beta_higher: 25.0-30.0 Hz
  • :gamma: 30.0-150.0 Hz
  • :gamma_1: 30.0-40.0 Hz
  • :gamma_2: 40.0-50.0 Hz
  • :gamma_lower: 30.0-80.0 Hz
  • :gamma_higher: 80.0-150.0 Hz

Returns

• Tuple{Float64, Float64}: (low_Hz, high_Hz) limits, clamped to the Nyquist frequency if necessary

cextrema(x)

Return the elements of a complex vector with the largest and smallest magnitudes.

Arguments

• x::Vector{ComplexF64}: input complex vector; must not be empty

Returns

Tuple containing:

• ComplexF64: element with the largest absolute value (cmax)
• ComplexF64: element with the smallest absolute value (cmin)

channels_cluster(obj; <keyword arguments>)

Return channel names belonging to a predefined spatial cluster.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• cluster::Symbol: cluster name:
  • :f1: left frontal (Fp1, F1, F3, F5, F7, F9, AF3, AF7)
  • :f2: right frontal (Fp2, F2, F4, F6, F8, F10, AF4, AF8)
  • :t1: left temporal (C3, C5, T7, T9, FC3, FC5, FT7, FT9)
  • :t2: right temporal (C4, C6, T8, T10, FC4, FC6, FT8, FT10)
  • :c1: anterior central (Cz, C1, C2, FC1, FC2, FCz)
  • :c2: posterior central (Pz, P1, P2, CP1, CP2, CPz)
  • :p1: left parietal (P3, P5, P7, P9, CP3, CP5, TP7, TP9)
  • :p2: right parietal (P4, P6, P8, P10, CP4, CP6, TP8, TP10)
  • :o: occipital (O1, O2, POz, PO3, PO4, PO7, PO8, PO9, PO10)

Returns

• Vector{String}: channel names present in the object that belong to the cluster

channel_info(obj; <keyword arguments>)

Return or print information for a single channel.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• ch::String: channel name; must resolve to exactly one channel
• pr::Bool=true: if true, print to stdout and return nothing; if false, return the info string

Returns

• Nothing when pr=true, or String when pr=false.

channel_order(obj)

Return the channel order indices stored in the object header.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object

Returns

• Vector{Int64}: channel order indices

channel_pick(obj; <keyword arguments>)

Return set of channel indices corresponding to a set of electrodes ("pick", e.g. left or frontal electrodes).

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object; must be of type "eeg"
• pick::Vector{Symbol}: pick of electrodes; picks may be combined, e.g. [:left, :frontal]
  • :central / :c
  • :left / :l
  • :right / :r
  • :frontal / :f
  • :temporal / :t
  • :parietal / :p
  • :occipital / :o

Returns

• Vector{String}: channel names matching the pick

chtypes(obj)

Return channel type strings.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object

Returns

• Vector{String}: channel type strings (one per channel)

cmax(x)

Return the element of a complex vector with the largest magnitude.

Selects the element that maximises |x|² (equivalent to maximising |x|).

Arguments

• x::Vector{ComplexF64}: input complex vector; must not be empty

Returns

• ComplexF64: element of x with the largest absolute value

cmin(x)

Return the element of a complex vector with the smallest magnitude.

Selects the element that minimises |x|² (equivalent to minimising |x|).

Arguments

• x::Vector{<:Complex}: input complex vector; must not be empty

Returns

• ComplexF64: element of x with the smallest absolute value

cums(signal)

Compute the cumulative sum of a 3-dimensional array along the sample (second) axis.

Arguments

• s::Array{<:Real, 3}: input array of shape (channels, samples, epochs)

Returns

• Array{Float64, 3}: cumulative sum array of the same shape as signal

cwtfrq(s; <keyword arguments>)

Return the mean frequencies of a collection of analytic or real wavelets for a signal of a given length.

The first frequency bin is set to 0.0 Hz because getMeanFreq returns a non-physical low-frequency artifact for the lowest scale.

Arguments

• s::AbstractVector: signal vector; used only for its length
• fs::Int64: sampling rate in Hz; must be ≥ 1
• wt::T where {T <: CWT}=wavelet(Morlet(2π), β=2): wavelet to use; see the ContinuousWavelets.jl documentation for the full list of available wavelets

Returns

• Vector{Float64}: center frequencies in Hz (rounded to 2 decimal places), length determined by the number of wavelet scales

cwtfrq(s; <keyword arguments>)

Return the mean frequencies of a collection of analytic or real wavelets for a 3-D signal array.

Delegates to the vector method using the first channel and first epoch s[1, :, 1] to determine the wavelet frequency grid (all channels and epochs share the same grid for a fixed signal length).

Arguments

• s::AbstractArray: signal array, shape (channels, samples, epochs)
• fs::Int64: sampling rate in Hz; must be ≥ 1
• wt::T where {T <: CWT}=wavelet(Morlet(2π), β=2): wavelet to use; see the ContinuousWavelets.jl documentation for the full list of available wavelets

Returns

• Vector{Float64}: center frequencies in Hz (rounded to 2 decimal places)

cwtfrq(obj; <keyword arguments>)

Return the mean frequencies of a collection of analytic or real wavelets for a NEURO object.

Uses the first channel and first epoch to determine the wavelet frequency grid.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• wt::T where {T <: CWT}=wavelet(Morlet(2π), β=2): wavelet to use; see the ContinuousWavelets.jl documentation for the full list of available wavelets

Returns

• Vector{Float64}: center frequencies in Hz (rounded to 2 decimal places)

datatype(obj)

Return the data type string of the object.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object

Returns

• String: data type (e.g. "eeg", "meg", "nirs").

delete_note(obj)

Return a copy of obj with the recording note cleared. The original object is not modified.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object

Returns

• NeuroAnalyzer.NEURO: new NEURO object with an empty recording note

delete_note!(obj)

Clear the recording note in obj in-place.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object

Returns

• Nothing

describe(obj; <keyword arguments>)

Print or return descriptive statistics for each channel.

Statistics reported: range, mean, SD, minimum, Q1 (25th percentile), median, Q3 (75th percentile), maximum.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• df::Bool=false: if true, return statistics as a DataFrame; otherwise print a formatted table and return nothing

Returns

• Nothing when df=false, or a DataFrame when df=true

detector_labels(obj)

Return detector labels (NIRS objects only).

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object; must be of type "nirs"

Returns

• Vector{String}: detector label strings

e2t(obj; <keyword arguments>)

Return the time segment in seconds spanning a contiguous range of epoch indices. The returned segment runs from the start of ep[1] to the end of ep[end].

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• ep::Union{Int64, Vector{Int64}: epoch index or vector of epoch indices

Returns

• Tuple{Float64, Float64}: (start_time, end_time) in seconds

epoch_duration(obj)

Return the epoch duration in seconds.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object

Returns

• Float64: duration of one epoch in seconds

epoch_len(obj)

Return the epoch length in samples.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object

Returns

• Int64: number of samples per epoch (second data dimension)

f2t(f)

Convert a frequency in Hz to a cycle length in milliseconds.

Computes 1000 / f, rounded to 2 decimal places.

Arguments

• f::Real: frequency in Hz; must be > 0

Returns

• Float64: cycle length in ms

fft0(x, n)

Perform a zero-padded full (two-sided) FFT.

Appends n zeros to x before computing the FFT. When n = 0 the input is transformed directly, avoiding an unnecessary copy.

Arguments

• x::AbstractVector: signal vector of length L
• n::Int64: number of zeros to append; must be ≥ 0.

Returns

• Vector{ComplexF64}: two-sided Fourier coefficients of length L + n.

fft2(x)

Perform a full (two-sided) FFT after zero-padding the input to the next power of 2.

Zero-padding to a power-of-2 length maximizes FFT efficiency (radix-2 algorithm). If length(x) is already a power of 2, no padding is added.

Arguments

• x::AbstractVector: signal vector of length L

Returns

• Vector{ComplexF64}: two-sided Fourier coefficients of length nextpow2(L)

findpeaks(signal; <keyword arguments>)

Find the indices of local peaks in a 1-D signal.

Peaks are detected using findpeaks1d and a minimum separation of d samples is enforced between consecutive peaks (non-maximum suppression).

Arguments

• signal::AbstractVector: signal vector
• d::Int64=32: minimum distance between consecutive peaks in samples; must be ≥ 1

Returns

• Vector{Int64}: indices of detected peaks in signal, sorted in ascending order

fir_order_bw(; <keyword arguments>)

Calculate the order of a FIR filter using the Harris formula.

The formula is: n = round((a × fs) / (22 × bw)), where 22 is the Harris empirical constant relating attenuation, bandwidth, and sample rate.

Arguments

• bw::Real: transition band width in Hz; must be > 0.
• a::Real=60: attenuation in dB; must be > 0
• fs::Int64: sampling rate in Hz; must be > 0

Returns

• Int64: estimated FIR filter order

fir_order_bw(obj; <keyword arguments>)

Calculate the order of a FIR filter using the Harris formula.

Convenience wrapper that reads the sampling rate from obj.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• bw::Real: transition band width in Hz; must be > 0
• a::Real=60: attenuation in dB; must be > 0

Returns

• Int64: estimated FIR filter order

fir_order_f(; <keyword arguments>)

Calculate a recommended FIR filter order range from the lower frequency bound.

The rule of thumb is that the filter should span 4–5 full cycles of the lowest frequency of interest. The range is returned as (4 × n_samples, 5 × n_samples), where n_samples is the number of samples in one cycle of f.

Arguments

• fs::Int64: sampling rate in Hz; must be > 0
• f::Real: lower frequency bound of the analyzed range in Hz; must be > 0

Returns

• Tuple{Int64, Int64}: recommended filter order range (lowerorder, upperorder)

fir_order_f(obj; <keyword arguments>)

Calculate a recommended FIR filter order range from the lower frequency bound.

Convenience wrapper that reads the sampling rate from obj.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• f::Real: lower frequency bound of the analyzed range in Hz; must be > 0

Returns

• Tuple{Int64, Int64}: (lower_order, upper_order) recommended filter order range

f_nearest(m, pos)

Find the matrix position closest to a query position tuple.

Computes the Euclidean distance from every element of m to p and returns the row and column indices of the nearest element.

Arguments

• m::Matrix{Tuple{Float64, Float64}}: matrix of 2-D position tuples
• p::Tuple{Float64, Float64}: query position

Returns

• Tuple{Int64, Int64}: (row, column) of the nearest position in m

freqs(t; nf)

Return the frequency vector and Nyquist frequency for a time vector.

The sampling rate is inferred as 1 / (t[2] - t[1]).

Arguments

• t::AbstractVector, AbstractRange}: time vector; must contain at least 2 elements
• nf::Bool=false: if true, return both negative and positive frequencies (via fftfreq + fftshift); if false, return positive frequencies only (via rfftfreq)

Returns

• Vector{Float64}: frequency vector in Hz, rounded to 3 decimal places
• Float64: Nyquist frequency in Hz

freqs(s, fs; <keyword arguments>)

Return the frequency vector and Nyquist frequency for a signal vector.

Arguments

• s::AbstractVector: signal vector
• fs::Int64: sampling rate in Hz; must be ≥ 1
• nf::Bool=false: if true, return both negative and positive frequencies (via fftfreq + fftshift); if false, return positive frequencies only (via rfftfreq)

Returns

• Vector{Float64}: frequency vector in Hz, rounded to 3 decimal places
• Float64: Nyquist frequency in Hz

freqs(n, fs; <keyword arguments>)

Return the frequency vector and Nyquist frequency for a signal of n samples.

Arguments

• n::Int64: number of samples; must be ≥ 1
• fs::Int64: sampling rate in Hz; must be ≥ 1
• nf::Bool=false: if true, return both negative and positive frequencies (via fftfreq + fftshift); if false, return positive frequencies only (via rfftfreq)

Returns

• Vector{Float64}: frequency vector in Hz, rounded to 3 decimal places
• Float64: Nyquist frequency in Hz

freqs(obj; <keyword arguments>)

Return the frequency vector and Nyquist frequency for a NEURO object.

Uses the first channel and first epoch of obj to infer signal length, and reads the sampling rate via sr(obj).

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• nf::Bool=false: if true, return both negative and positive frequencies; if false, return positive frequencies only

Returns

• Vector{Float64}: frequency vector in Hz, rounded to 3 decimal places
• Float64: Nyquist frequency in Hz

fwhm(s)

Calculate the indices of the full-width at half-maximum (FWHM) points of a Gaussian-like signal.

Arguments

• s::AbstractVector: signal vector; must contain at least 2 elements

Returns

• Int64: index of the pre-peak half-maximum point
• Int64: index of the signal peak
• Int64: index of the post-peak half-maximum point

Notes

• The input s is normalized internally; the original vector is not modified.
• For noisy or non-unimodal signals, vsearch may return the index of the closest sample to 0.5 rather than a true half-maximum crossing.

generate_cosine(f, t, a, p)

Generate a cosine wave.

Computes a × cos(2πft + φ) where φ = deg2rad(p).

Arguments

• f::Real: frequency in Hz
• t::AbstractVector: time vector in seconds
• a::Real: amplitude; the signal ranges over [-a, +a]
• p::Real: phase shift in degrees

Returns

• Vector{Float64}: cosine wave sampled at the points in t

generate_csine(f, t, a)

Generate a complex sine wave (complex exponential).

Computes a × exp(i × 2πft).

Arguments

• f::Real: frequency in Hz
• t::AbstractVector: time vector in seconds
• a::Real: amplitude; the signal ranges over [-a, +a]

Returns

• Vector{ComplexF64}: complex exponential sampled at the points in t

generate_gaussian(fs, f, t; <keyword arguments>)

Generate a Gaussian envelope.

The standard deviation of the Gaussian is σ = ncyc / (2πf). The time axis spans −t : 1/fs : t.

Arguments

• fs::Int64: sampling rate in Hz; must be ≥ 1
• f::Real: frequency in Hz; determines the Gaussian width via σ = ncyc / (2πf)
• t::Real=1: half-length of the time axis in seconds; must be > 0
• ncyc::Int64: : number of cycles; controls the width (SD) of the Gaussian; must be ≥ 1
• a::Real=1.0: peak amplitude

Returns

• Vector{Float64}: Gaussian envelope of length length(-t:1/fs:t)

generate_morlet(fs, f, t; <keyword arguments>)

Generate a Morlet wavelet.

The wavelet is the product of a complex (or real) sine wave at frequency f and a Gaussian envelope whose width is determined by ncyc. The time axis spans −t : 1/fs : t.

Arguments

• fs::Int64: sampling rate in Hz; must be ≥ 1
• f::Real: centre frequency in Hz
• t::Real=1: half-length of the wavelet in seconds; must be > 0
• ncyc::Int64=5: number of cycles; controls the Gaussian width; must be ≥ 1
• complex::Bool=false: if true, return a complex Morlet; otherwise return the real part only

Returns

• Union{Vector{Float64}, Vector{ComplexF64}}: Morlet wavelet of length length(-t:1/fs:t)

generate_morlet_fwhm(fs, f, t; <keyword arguments>)

Generate a complex Morlet wavelet parameterized by full-width at half-maximum (FWHM).

Uses the FWHM-based Gaussian envelope exp(−4 ln 2 × t² / h²) instead of a cycle-count parameter, providing more intuitive control over time–frequency resolution.

Arguments

• fs::Int64: sampling rate in Hz; must be ≥ 1
• f::Real: centre frequency in Hz
• t::Real=1: half-length of the wavelet in seconds; must be > 0
• h::Float64=0.25: full-width at half-maximum of the Gaussian envelope in seconds; must be > 0

Returns

• Vector{ComplexF64}: complex Morlet wavelet of length length(-t:1/fs:t)

References

Cohen MX. A better way to define and describe Morlet wavelets for time-frequency analysis. NeuroImage. 2019 Oct;199:81–6.

generate_noise(n, a; <keyword arguments>)

Generate a noise signal.

The raw noise is normalized to [−1, 1] and then scaled by a.

Arguments

• n::Int64: number of samples; must be ≥ 1
• a::Real=1.0: amplitude; the output ranges over [-a, +a]
• type::Symbol=:whiten: noise type:
  • :whiten: white noise (normally distributed)
  • :whiteu: white noise (uniformly distributed)
  • :pink: pink (1/f²) noise.

Returns

• Vector{Float64}: noise signal of length n

generate_signal(n, a)

Generate a random walk signal based on cumulative normally distributed noise.

The cumulative sum introduces temporal autocorrelation, producing a Brownian-motion–like signal. The result is normalized to [−1, 1] and scaled by a.

Arguments

• n::Int64: number of samples; must be ≥ 1
• a::Real=1.0: amplitude; the output ranges over [-a, +a]

Returns

• Vector{Float64}: random walk signal of length n

generate_sinc(t; <keyword arguments>)

Generate a sinc function.

Produces either the normalized (sin(2πf(t−peak)) / (π(t−peak))) or unnormalized (sin(2f(t−peak)) / (t−peak)) sinc. The singularity at t = peak is resolved by linear interpolation from the two neighboring samples.

Arguments

• t::AbstractVector=-2:0.01:2: time vector
• `f::Real=1.0: frequency in Hz
• peak::Real=0: time of the sinc peak (location of the singularity)
• norm::Bool=true: if true, generate the normalized sinc; otherwise generate the unnormalized sinc

Returns

• Vector{Float64}: sinc function sampled at the points in t

generate_sine(f, t, a, p)

Generate a sine wave.

Computes a × sin(2πft + φ) where φ = deg2rad(p).

Arguments

• f::Real: frequency in Hz
• t::AbstractVector: time vector in seconds
• a::Real: amplitude; the signal ranges over [-a, +a]
• p::Real: phase shift in degrees

Returns

• Vector{Float64}: sine wave sampled at the points in t

generate_square(t, a, p; <keyword arguments>)

Generate a square wave.

Arguments

• t::AbstractVector: time vector
• a::Real: amplitude scaling factor
• p::Real: phase (horizontal shift of the wave) = duty cycle
• w::Real: width = duty-cycle threshold; samples where mod(p + t, 2) > w are high
• offset::Real=0: vertical amplitude offset

Returns

• Vector{Float64}: square wave sampled at the points in t

generate_triangle(t, a)

Generate a triangle wave.

Computes a × |mod(t, 2) − 1|, which produces a symmetric triangle wave with period 2 and amplitude a.

Arguments

• t::AbstractVector: time vector
• a::Real: amplitude scaling factor

Returns

• Vector{Float64}: triangle wave sampled at the points in t

generate_window(type, n; <keyword arguments>)

Return an n-point symmetric window of the given type.

Arguments

• type::Symbol: window type:
  • :hann: Hann
  • :bh: Blackman-Harris
  • :bohman: Bohman
  • :flat: Flat-top
  • :bn: Blackman-Nuttall
  • :nutall: Nuttall
  • :triangle: symmetric triangle (left half ↑, right half ↓)
  • :exp: symmetric exponential (left half ↑, right half ↓)
• n::Int64: window length in samples; must be ≥ 1
• even::Bool=false: if true, and n is odd, increment n by 1 to enforce even length

Returns

• Vector{Float64}: generated window of length n (or n + 1 if even=true and n was odd)

get_channel(obj; <keyword arguments>)

Return list of channel names of specified type or their numbers if names are specified.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• ch::Union{String, Vector{String}, Regex}="": channel name or list of channel names
• type::Union{String, Vector{String}}="all": channels types
• wl::Real: return NIRS channels for wavelength (in nm)
• exclude::Union{String, Vector{String}, Regex}="": channel name or list of channel names to exclude from the list

Returns

• ch::Union{Vector{String}, Vector{Int64}}

gradient(x; <keyword arguments>)

Calculate the gradient of a 1-dimensional scalar field.

Each element of the returned vector field grad_vf is a 1-element Vector{Float64} giving the gradient direction at that position. grad_mag contains the corresponding gradient magnitudes.

Arguments

• x::AbstractVector: 1-D scalar field
• rev::Bool=false: if false (default), the gradient direction points toward the maximum value; if true, it points toward the minimum value

Returns

Named tuple:

• grad_vf::Vector{Vector{Float64}}: vector field of gradients (one gradient vector per element)
• grad_mag::Vector{Float64}: scalar field of gradient magnitudes

gradient(x; <keyword arguments>)

Calculate the gradient of a 2-dimensional scalar field.

Each element of the returned matrix field grad_vf is a 2-element Vector{Float64} giving the gradient direction (row, column) at that position. grad_mag contains the corresponding gradient magnitudes.

Arguments

• x::AbstractMatrix: 2-D scalar field
• rev::Bool=false: if false (default), the gradient direction points toward the maximum value; if true, it points toward the minimum value

Returns

Named tuple:

• grad_vf::Matrix{Vector{Float64}}: vector field of gradients (one gradient vector per element)
• grad_mag::Matrix{Float64}: scalar field of gradient magnitudes

gradient(x; <keyword arguments>)

Calculate the gradient of a 3-or-higher-dimensional scalar field.

Dispatches when x is neither a vector nor a matrix (i.e. ndims(x) ≥ 3). Each element of the returned array field grad_vf is an ndims(x)-element Vector{Float64} giving the gradient direction at that position. grad_mag contains the corresponding gradient magnitudes.

Arguments

• x::AbstractArray: scalar field with ndims(x) ≥ 3
• rev::Bool=false: if false (default), the gradient direction points toward the maximum value; if true, it points toward the minimum value

Returns

Named tuple:

• grad_vf::Array{Vector{Float64}, 3}: vector field of gradients
• grad_mag::Array{Float64, 3}: scalar field of gradient magnitudes

header(obj; <keyword arguments>)

Print object header metadata to stdout.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object

Returns

• Nothing

history(obj)

Return the processing history log.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object

Returns

• Vector{String}: list of processing steps applied to the object

hz2rads(f)

Convert a frequency from Hz to rad/s.

Computes 2π × f.

Arguments

• f::Real: frequency in Hz

Returns

• Float64: frequency in rad/s

ifft0(x, n)

Perform an IFFT on a zero-padded spectrum and trim the result to the original signal length.

If a signal of length L was zero-padded by n samples before the forward FFT, the padded spectrum has length L + n. This function recovers the original L-sample signal by discarding the trailing n samples after the IFFT.

Arguments

• x::AbstractVector: zero-padded spectrum (length L + n)
• n::Int64: number of zeros that were appended during the forward FFT; must be ≥ 0

Returns

• Vector{ComplexF64}: reconstructed signal of length length(x) - n

iir_order(; <keyword arguments>)

Calculate the minimum order of an IIR filter meeting the given specifications.

Pass-band and stop-band edges are derived from cutoff and bw:

• For :lp / :hp: pass edge = cutoff ± bw/2, stop edge = cutoff ∓ bw/2.
• For :bp / :bs: inner edges shifted inward by bw/2, outer edges shifted outward by bw/2.

The order is estimated via the appropriate DSP.jl design function (buttord, cheb1ord, cheb2ord, or ellipord).

Arguments

• fprototype::Symbol: filter prototype:
  • :butterworth
  • :chebyshev1
  • :chebyshev2
  • :elliptic
• ftype::Symbol: filter type:
  • :lp: low-pass
  • :hp: high-pass
  • :bp: band-pass
  • :bs: band-stop
• cutoff::Union{Real, Tuple{Real, Real}}: cutoff frequency in Hz; scalar for :lp / :hp; two-element tuple for :bp / :bs
• bw::Real: transition band width in Hz; must be > 0
• rp::Union{Nothing, Real}=nothing: pass-band ripple in dB; defaults to 0.5 dB
• rs::Union{Nothing, Real}=nothing: stop-band ripple in dB; defaults to 20 dB
• fs::Int64: sampling rate in Hz; must be > 0

Returns

• order::Int64: minimum filter order satisfying the specifications

iir_order(obj; <keyword arguments>)

Calculate the minimum order of an IIR filter meeting the given specifications.

Convenience wrapper that reads the sampling rate from obj.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• fprototype::Symbol: filter prototype:
  • :butterworth
  • :chebyshev1
  • :chebyshev2
  • :elliptic
• ftype::Symbol: filter type:
  • :lp: low-pass
  • :hp: high-pass
  • :bp: band-pass
  • :bs: band-stop
• cutoff::Union{Real, Tuple{Real, Real}}: cutoff frequency in Hz; scalar for :lp / :hp; two-element tuple for :bp / :bs
• bw::Real: transition band width in Hz; must be > 0
• rp::Union{Nothing, Real}=nothing: pass-band ripple in dB; defaults to 0.5 dB
• rs::Union{Nothing, Real}=nothing: stop-band ripple in dB; defaults to 20 dB

Returns

• Int64: minimum filter order satisfying the specifications

info(obj; <keyword arguments>)

Print object metadata and channel table. Optionally return data as a DataFrame.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• df::Bool=false: if true, return the signal data reshaped into a DataFrame with columns :time and one column per channel label

Returns

• Nothing if df=false, or a DataFrame if df=true.

l1(a1, a2)

Compare two arrays using the L1 (Manhattan) distance.

Computes ∑|a1ᵢ - a2ᵢ| element-wise.

Suitable for comparing spectrograms, feature maps, or any same-shaped numeric arrays.

Arguments

• a1::AbstractArray: first array
• a2::AbstractArray: second array; must be the same size as a1.

Returns

• Float64: L1 distance between a1 and a2

l2(a1, a2)

Compare two arrays using the L2 (Euclidean) distance.

Computes √∑(a1ᵢ - a2ᵢ)² element-wise via Distances.euclidean.

Suitable for comparing spectrograms, feature maps, or any same-shaped numeric arrays.

Arguments

• a1::AbstractArray: first array
• a2::AbstractArray: second array; must be the same size as a1

Returns

• Float64: L2 distance between a1 and a2.

labels(obj)

Return channel labels.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object

Returns

• Vector{String}: channel label strings

linspace(start, stop, length)

Return a vector of n evenly spaced numbers from start to stop (inclusive).

Thin wrapper around Base.range that always materialises the result as a Vector{Float64}.

Arguments

• start::Real: start of the sequence
• stop::Real: end of the sequence (inclusive)
• n::Int64: number of points; must be ≥ 2

Returns

• Vector{Float64}: linearly spaced sequence of length n

logspace(start, stop, n)

Return a vector of n logarithmically spaced numbers from start to stop (inclusive).

Requires start > 0 and stop > 0 (logarithmic spacing is undefined for non-positive values).

Arguments

• start::Real: start of the sequence; must be > 0
• stop::Real: end of the sequence (inclusive); must be > 0
• n::Int64: number of points; must be ≥ 2

Returns

• Vector{Float64}: logarithmically spaced sequence of length n

markers_s2t(m; <keyword arguments>)

Return a copy of a markers DataFrame with :start and :length columns converted from sample numbers to seconds.

Arguments

• m::DataFrame: markers DataFrame containing integer :start and :length columns
• fs::Int64: sampling rate in Hz; must be ≥ 1

Returns

• DataFrame: new DataFrame with :start and :length expressed in seconds

markers_s2t(obj; <keyword arguments>)

Return a copy of the object's markers DataFrame with :start and :length converted from sample numbers to seconds.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object

Returns

• DataFrame: new DataFrame with :start and :length expressed in seconds

markers_s2t!(m; <keyword arguments>)

Convert :start and :length columns of a markers DataFrame from sample numbers to seconds, in-place.

Arguments

• m::DataFrame: markers DataFrame; modified in-place
• fs::Int64: sampling rate in Hz; must be ≥ 1

Returns

• Nothing

markers_s2t!(obj; <keyword arguments>)

Convert :start and :length columns of the object's markers DataFrame from sample numbers to seconds, in-place.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object

Returns

• Nothing

maxat(x, y)

Find the maximum value of x and return the corresponding value from y at that index.

Argument

• x::AbstractVector: vector to find the maximum of; must not be empty
• y::AbstractVector: vector to read the value from; must be the same length as x

Returns

• Real: y[idx] where idx = argmin(x)
• Int64: index of the maximum value in x

meshgrid(x)

Build a 2-D mesh grid from two coordinate vectors.

Returns a pair (mx, my) where mx[i] repeats the full x vector for row i, and my[i] repeats y[i] across all columns. This matches the convention of MATLAB's meshgrid / NumPy's meshgrid(..., indexing="xy").

Arguments

• x::Vector{Float64}: x-coordinate vector of length n
• y::Vector{Float64}: y-coordinate vector of length m

Returns

• Tuple{Vector{Vector{Float64}}, Vector{Vector{Float64}}}:
  • mx: m repetitions of x (one per row)
  • my: m vectors each filled with the corresponding y[i] value

minat(x, y)

Find the minimum value of x and return the corresponding value from y at that index.

Argument

• x::AbstractVector: vector to find the minimum of; must not be empty
• y::AbstractVector: vector to read the value from; must be the same length as x

Returns

• Real: y[idx] where idx = argmin(x)
• Int64: index of the minimum value in x

mni2tal(pts)

Convert MNI coordinates to Talairach coordinates using the non-linear Brett transform.

The transform is piecewise-linear in z:

• z ≥ 0 (above the AC–PC plane): x′ = 0.99x, y′ = 0.9688y + 0.046z, z′ = −0.0485y + 0.9189z
• z < 0 (below the AC–PC plane): x′ = 0.99x, y′ = 0.9688y + 0.042z, z′ = −0.0485y + 0.839z

Arguments

• pts::Vector{<:Number}: MNI [X, Y, Z] coordinates

Returns

• Vector{Float64}: Talairach [X, Y, Z] coordinates

References

Brett M. https://www.brainmap.org/training/BrettTransform.html

m_norm(m)

Normalize an array by the number of columns minus one (size(m, 2) - 1).

Arguments

• m::AbstractArray: input array; must have at least 2 columns

Returns

• AbstractArray: array divided element-wise by size(m, 2) - 1

m_pad0(m)

Pad a matrix with zeros to make it square.

Adds zero columns if the matrix has more rows than columns, or zero rows if it has more columns than rows. Returns the matrix unchanged if it is already square.

Arguments

• m::AbstractMatrix: input matrix

Returns

• AbstractMatrix: square matrix of size max(r, c) × max(r, c) with the same element type as m.

m_pad0(m, r, c)

Pad a matrix with zeros to reach the target size r × c.

Rows are appended to the bottom and columns to the right as needed. At least one of r, c must be strictly larger than the corresponding dimension of m.

Arguments

• m::AbstractMatrix: input matrix
• r::Int64: target number of rows; must be ≥ size(m, 1)
• c::Int64: target number of columns; must be ≥ size(m, 2)

Returns

• AbstractMatrix: matrix of size r × c padded with zeros of the same element type as m

m_sort(m, m_idx; <keyword arguments>)

Sort a matrix using a pre-computed permutation index vector.

Arguments

• m::AbstractMatrix: input matrix
• m_idx::Vector{Int64}: permutation index vector (e.g. from sortperm); this vector is not modified by the function
• rev::Bool=false: if true, reverse the permutation before applying it
• dims::Int64=1: apply permutation along columns (dims=1) or rows (dims=2)

Returns

• AbstractMatrix: sorted matrix with the same size and element type as m

m_sortperm(m; <keyword arguments>)

Return the sorting permutation indices of a matrix column-wise or row-wise.

Arguments

• m::AbstractMatrix: input matrix
• rev::Bool: if true, sort in descending order
• dims::Int64=1: sort along columns (dims=1) or rows (dims=2)

Returns

• Matrix{Int64}: index matrix of the same size as m; each column (or row) contains the permutation that would sort that column (or row)

nchannels(obj; <keyword arguments>)

Return the number of channels of a given type.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• type::String="all": channel type string (must be one of the values in the global channel_types constant); use "all" to count every channel.

Returns

• Int64: number of channels of the requested type

nepochs(obj)

Return the number of epochs.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object

Returns

• Int64: number of epochs (third data dimension)

nextpow2(x)

Return the smallest power of 2 that is ≥ x.

Thin wrapper around Base.nextpow(2, x) with an explicit positivity guard.

Arguments

• x::Int64: input value; must be > 0

Examples

nextpow2(5)   # → 8
nextpow2(8)   # → 8
nextpow2(9)   # → 16

ntapers(obj; <keyword arguments>)

Return the recommended number of Slepian tapers for multi-taper spectral analysis.

The formula is nt = floor(df × T) - 1, where T = epoch_len / fs is the epoch duration in seconds. The result is clamped to a minimum of 1.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• df::Real: desired frequency resolution (bandwidth) in Hz; must be > 0; this is the minimum separation between frequency peaks to be resolved

Returns

• Int64: recommended number of Slepian tapers (≥ 1)

optode_labels(obj)

Return optode labels (NIRS objects only).

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object; must be of type "nirs"

Returns

• Vector{String}: optode label strings

pad0(x, n)

Append n zeros along the second axis (or at the end for 1-D input). Works with 1-, 2-, and 3-dimensional arrays. The zero values match the element type of x.

Arguments

• x::Union{AbstractVector, AbstractArray}: input array; must be 1-, 2-, or 3-dimensional
• n::Int64: number of zeros to append; must be ≥ 0

Returns

• Union{AbstractVector, AbstractArray}: padded array with the same number of dimensions as x

pad2(x)

Pad an array with zeros along its second axis to the next power-of-2 length. Works with 1-, 2-, and 3-dimensional arrays. If the relevant dimension is already a power of 2, the array is returned unchanged.

Arguments

• x::Union{AbstractVector, AbstractArray}: input array; must be 1-, 2-, or 3-dimensional

Returns

• Union{AbstractVector, AbstractArray}: padded array whose second dimension (or length, for 1-D) is a power of 2

padm(x, n)

Pad an array with mean values along its second axis (or at the end for 1-D input). Works with 1-, 2-, and 3-dimensional arrays.

Arguments

• x::Union{AbstractVector, AbstractArray}: input array; must be 1-, 2-, or 3-dimensional
• n::Int64: number of mean-value samples to append; must be ≥ 0
• mode::Symbol=:row: how the mean is computed for 2-D and 3-D arrays:
  • :all: single mean of all elements
  • :row: separate mean per row (broadcasts across the padded columns)

Returns

• Union{AbstractVector, AbstractArray}: padded array with the same number of dimensions as x

paired_labels(l; <keyword arguments>)

Generate all ordered pairwise label combinations from a single label vector.

Arguments

• l::Vector{String}: input label vector; must not be empty
• unq::Bool=true: if true, exclude self-pairs ("label1-label1")

Returns

• Vector{String}: ordered paired labels

paired_labels(l1, l2)

Generate element-wise paired labels from two label vectors of equal length.

Arguments

• l1::Vector{String}: first label vector; must not be empty
• l2::Vector{String}: second label vector; must have the same length as l1

Returns

• Vector{String}: element-wise paired labels of length length(l1)

perm_cmp(a1, a2; <keyword arguments>)

Compare two 3-dimensional arrays using a permutation-based statistic.

Randomly shuffles the combined pool of epochs perm_n times, splits each shuffle into two equal halves, and builds a null distribution of difference maps. The real difference map is then Z-scored against this null distribution and thresholded at the Z-value corresponding to p.

Arguments

• a1::Array{<:Real, 3}: first array (e.g. spectrogram), shape (freq, time, epochs)
• a2::Array{<:Real, 3}: second array; must match a1 in size.
• p::Float64=0.05: two-tailed p-value threshold (must be in (0, 1))
• perm_n::Int64=1000: number of permutations (must be > 0)

Returns

Named tuple:

• zmap::Matrix{Float64}: Z-scored difference map (a2 mean − a1 mean) normalized by the permutation null distribution
• bm::BitMatrix: Boolean mask where true indicates a statistically significant position (|z| ≥ zval)

phases(s)

Compute the instantaneous phase of a signal via the Hilbert transform. The analytic signal is obtained as z = DSP.hilbert(s), then the wrapped instantaneous phase is extracted as φ(t) = angle(z(t)) = atan(imag(z), real(z)).

For the unwrapped phase (suitable for differentiating to obtain instantaneous frequency) apply DSP.unwrap to the output.

Arguments

• s::AbstractVector: signal vector; must contain at least 1 element

Returns

• Vector{Float64}: instantaneous phase in radians ∈ (−π, π]

play(obj; <keyword arguments>)

Play a channel signal segment as audio.

The signal is normalized to [−1, 1] and scaled to [−1000, +1000] before playback. For best results the channel should contain an audio-range signal (e.g. speech, auditory ERP); arbitrary EEG/MEG data will be audible but may not be meaningful.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• ch::String: channel name; must resolve to exactly one channel
• seg::Tuple{Real, Real}: time segment to play in seconds, as (start, stop); both values must lie within the epoch time range
• ep::Int64: epoch index

Returns

• Nothing

rads2hz(f)

Convert a frequency from rad/s to Hz.

Computes f / 2π.

Arguments

• f::Real: frequency in rad/s

Returns

• Float64: frequency in Hz

rfft0(x, n)

Perform a zero-padded one-sided (real) FFT.

Appends n zeros to x before computing rfft, returning only the positive-frequency coefficients. When n = 0 the input is transformed directly, avoiding an unnecessary copy.

Arguments

• x::AbstractVector: signal vector of length L
• n::Int64: number of zeros to append; must be ≥ 0.

Returns

• Vector{ComplexF64}: one-sided Fourier coefficients of length (L + n) ÷ 2 + 1

rfft2(x)

Perform a one-sided (real) FFT after zero-padding the input to the next power of 2.

Zero-padding to a power-of-2 length maximizes FFT efficiency (radix-2 algorithm). If length(x) is already a power of 2, no padding is added.

Arguments

• x::AbstractVector: signal vector of length L

Returns

• Vector{ComplexF64}: one-sided Fourier coefficients of length nextpow2(L) ÷ 2 + 1

s2t(s, fs)

Convert a sample number to time in seconds.

Sample numbering starts at 1: sample 1 maps to t = 0.0. Passing s = 0 is invalid; a warning is emitted and s is silently clamped to 1.

Arguments

• s::Real: sample number; must be ≥ 1 (or 0, which is clamped with a warning)
• fs::Int64: sampling rate in Hz; must be ≥ 1

Returns

• Float64: time in seconds (rounded to 4 decimal places)

s2t(obj; <keyword arguments>)

Convert a sample number to time in seconds using the object's sampling rate.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• s::Int64: sample number; must be ≥ 1

Returns

• Float64: time in seconds

signal_duration(obj)

Return the total signal duration in seconds.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object

Returns

• Float64: duration in seconds

signal_len(obj)

Return the total signal length in samples (across all epochs).

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object

Returns

• Int64: total number of samples; for a 3-D array this equals epoch_len × nepochs

source_labels(obj)

Return source labels (NIRS objects only).

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object; must be of type "nirs"

Returns

• Vector{String}: source label strings

sr(obj)

Return the sampling rate of a NEURO object.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object

Returns

• Int64: sampling rate in Hz

t2f(t)

Convert a cycle length in milliseconds to a frequency in Hz.

Computes 1000 / t, rounded to 2 decimal places.

Arguments

• t::Real: cycle length in ms; must be > 0

Returns

• Float64: frequency in Hz

t2s(t, fs)

Convert a time in seconds to the nearest sample number.

Sample numbering starts at 1: t = 0 maps to sample 1, and any positive time is rounded up via ceil.

Arguments

• t::Real: time in seconds; must be ≥ 0
• fs::Int64: sampling rate in Hz; must be ≥ 1

Returns

• Int64: sample number (≥ 1)

t2s(obj; <keyword arguments>)

Convert a time in seconds to a sample number using the object's sampling rate.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• t::Real: time in seconds; must be ≥ 0

Returns

• Int64: sample number (≥ 1)

tal2mni(pts)

Convert Talairach coordinates to MNI coordinates using the inverse non-linear Brett transform.

This is the analytical inverse of mni2tal. The transform is piecewise-linear in z, with the branching threshold applied to the Talairach z coordinate:

z ≥ 0 - inverse of the upper matrix [[0.9688, 0.046], [−0.0485, 0.9189]] (det ≈ 0.8925):

• x = x′ / 0.99
• y = (0.9189 y′ − 0.046 z′) / det
• z = (0.0485 y′ + 0.9688 z′) / det

z < 0 - inverse of the lower matrix [[0.9688, 0.042], [−0.0485, 0.839]] (det ≈ 0.8151):

• x = x′ / 0.99
• y = (0.839 y′ − 0.042 z′) / det
• z = (0.0485 y′ + 0.9688 z′) / det

Arguments

• pts::Vector{<:Number}: Talairach [X, Y, Z] coordinates

Returns

• m::Vector{Float64}: MNI [X, Y, Z] coordinates

References

Brett M. https://www.brainmap.org/training/BrettTransform.html

tavg(s)

Average a 3-dimensional signal array across the trial (third) dimension.

Arguments

• s::AbstractArray: signal array, shape (channels, samples, epochs)

Returns

• AbstractArray: mean across epochs, shape (channels, samples, 1)

to_df(obj)

Export object signal data as a DataFrame.

Each row corresponds to one time point across all epochs (epochs are concatenated). Columns are :time followed by one column per channel, named after the channel labels.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object

Returns

• DataFrame: table with signal_len(obj) rows and nchannels(obj) + 1 columns ([:time, ch1, ch2, …])

Notes

• For multi-epoch objects the time column contains obj.time_pts, which spans the full concatenated signal, not individual epoch times.
• Channel columns are named via labels(obj); ensure the object has channel labels assigned before calling this function.

trtm(obj; <keyword arguments>)

Return a single channel's signal in trials × time format.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• ch::String: channel name; must resolve to exactly one channel
• ep::Union{Int64, Vector{Int64}, AbstractUnitRange{Int64}}=_c(nepochs(obj)): epoch numbers; default use all epochs

Returns

• Matrix{Float64}: matrix of shape (n_epochs, epoch_len)

vec2mat(x; <keyword arguments>)

Reshape a vector into a matrix using a sliding window with optional overlap.

The vector is divided into ⌊length(x) / wlen⌋ non-overlapping segments of length wlen. The woverlap parameter shifts the start of each subsequent window backward by that many samples.

Arguments

• x::AbstractVector: input vector
• wlen::Int64: window length in samples; must be ≥ 1
• woverlap::Int64: number of overlapping samples between consecutive windows; must satisfy 0 ≤ woverlap < wlen

Returns

• AbstractMatrix: matrix of shape (n_segments, wlen)

header(obj)

Print all keys and values stored in the object header.

Iterates over the :subject, :recording, and :experiment sub-dictionaries of obj.header and prints each key–value pair in the format header.<section>[:<key>]: <value>.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object

Returns

• Nothing

view_note(obj)

Return the recording note stored in the object header.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object

Returns

• String: recording note (empty string if no note has been set)

vreduce(x, f; <keyword arguments>)

Reduce two same-length vectors by resampling f at regular intervals of n and returning the corresponding values from x.

Useful for downsampling a frequency axis (and its associated data) when the number of frequency bins is large. The nearest existing entry in f is used for each target frequency (via vsearch); no interpolation is performed.

Arguments

• x::AbstractVector: data vector (e.g. spectral power); must not be empty
• f::AbstractVector: index vector (e.g. frequencies); must have the same length as x
• n::Float64=0.5: step size for the reduced grid (in the same units as f)

Returns

• AbstractVector: reduced data values
• AbstractVector: reduced frequency grid

vsearch(y, x)

Return the index of the first occurrence of string y in vector x, or nothing if y is not present.

Arguments

• y::String: value to search for
• x::Vector{String}: vector to search within

Returns

• Union{Int64, Nothing}: index of the first match, or nothing if not found

vsearch(y, x; <keyword arguments>)

Return the index of the element in x nearest to scalar y.

Arguments

• y::Real: value of interest
• x::AbstractVector: vector to search within; must not be empty
• acc::Bool=false: if true, also return the absolute difference between y and x[idx]

Returns

• Int64: index of the nearest element
• Tuple{Int64, Real}: (index, |y − x[index]|) when acc=true

vsearch(y, x; <keyword arguments>)

Return the indices of the elements in x nearest to each element of y.

Arguments

• y::AbstractVector: vector of interest
• x::AbstractVector: vector to search within; must not be empty and must be at least as long as y.
• acc::Bool=false: if true, also return the absolute differences between each y[i] and its nearest match in x

Returns

• Vector{Int64}: indices of nearest elements (one per entry of y)
• Tuple{Vector{Int64}, Vector{Real}}: (indices, differences) when acc=true

vsplit(x, n)

Split a vector into contiguous pieces of equal length n.

Argument

• x::AbstractVector: input vector; must not be empty and its length must be divisible by n
• n::Int64: length of each piece; must be ≥ 1

Returns

• Vector{AbstractVector}: vector of length(x) ÷ n sub-vectors, each of length n

arf(df, var)

Calculate absolute and relative frequencies for a categorical variable.

Arguments

• df::DataFrame: input DataFrame
• var::Union{Symbol, String}: column name; must be present in df and contain at least 2 distinct values

Returns

• Matrix{Float64}: a (3 × (k + 1)) matrix where k = length(unique(x)):
  • row 1: absolute frequencies per category, total in last column
  • row 2: relative frequencies as proportions (rounded to 3 d.p.), total = 1.0
  • row 3: relative frequencies as percentages (rounded to 2 d.p.), total = 100.0

ba(x, y; <keyword arguments>)

Calculate a Bland-Altman comparison between two sets of clinical measurements.

Computes the mean difference and the upper and lower limits of agreement (LoA), defined as mean(d) ± z × std(d), where d = x − y and z is the two-tailed Z-score corresponding to la.

Arguments

• x::AbstractVector: first measurement vector
• y::AbstractVector: second measurement vector; must be the same length as x
• la::Float64=0.95: confidence level for the limits of agreement; must be in (0, 1); default gives the standard 95 % LoA (mean ± 1.96 SD)

Returns

Named tuple:

• md::Float64: mean of the differences x − y
• ll::Float64: lower limit of agreement (md − z × SD)
• ul::Float64: upper limit of agreement (md + z × SD)

Notes

To produce a Bland-Altman plot:

means = (x .+ y) ./ 2
diffs = x .- y
scatter(means, diffs)
hline!([md, ul, ll])

binom_prob(p, r, n)

Calculate the probability of exactly r successes in n independent trials.

Uses the binomial probability mass function: P(X = r) = C(n, r) × pʳ × (1 − p)^(n − r)

Arguments

• p::Float64: success probability per trial; must be in [0, 1]
• r::Int64: number of successes; must satisfy 0 ≤ r ≤ n
• n::Int64: number of successes; must satisfy 0 ≤ r ≤ n

Returns

• Float64: probability of exactly r successes

binom_test(p, n; verbose)

Test whether a proportion differs significantly from 0.5 (two-sided binomial test).

Arguments

• prop::Float64: proportion of level-1 observations; must be in [0, 1]
• n::Int64: total number of observations; must be ≥ 1
• verbose::Bool=true: if true, print counts, proportions, 95 % CIs, and p-value

Returns

Named tuple:

• x0::Int64: level-0 count
• x1::Int64: level-1 count
• p0::Float64: level-0 proportion
• p1::Float64: level-1 proportion
• ci0::Tuple{Float64, Float64}: level-0 proportion 95 % CI
• ci1::Tuple{Float64, Float64}: level-1 proportion 95 % CI
• p::Float64: Two-sided binomial test p-value (clamped to eps() if below machine epsilon)

binom_test(x; verbose)

Test whether the proportion of true values in a boolean vector differs from 0.5.

Delegates to binom_test(::Float64, ::Int64) after computing the proportion of true observations.

Arguments

• x::Vector{Bool}: binary observation vector; must not be empty
• verbose::Bool=true: if true, print counts, proportions, 95 % CIs, and p-value

Returns

Named tuple:

• x0::Int64: level-0 count
• x1::Int64: level-1 count
• p0::Float64: level-0 proportion
• p1::Float64: level-1 proportion
• ci0::Tuple{Float64, Float64}: level-0 proportion 95 % CI
• ci1::Tuple{Float64, Float64}: level-1 proportion 95 % CI
• p::Float64: Two-sided binomial test p-value (clamped to eps() if below machine epsilon)

binom_test(x, n; verbose)

Test whether the proportion x / n differs from 0.5 (two-sided binomial test).

Delegates to binom_test(::Float64, ::Int64).

Arguments

• x::Int64: number of level 1 observations; must satisfy 0 ≤ x ≤ n
• n::Int64: number of observations; must be ≥ 1
• verbose::Bool=true: if true, print counts, proportions, 95 % CIs, and p-value

Returns

Named tuple:

• x0::Int64: level-0 count
• x1::Int64: level-1 count
• p0::Float64: level-0 proportion
• p1::Float64: level-1 proportion
• ci0::Tuple{Float64, Float64}: level-0 proportion 95 % CI
• ci1::Tuple{Float64, Float64}: level-1 proportion 95 % CI
• p::Float64: Two-sided binomial test p-value (clamped to eps() if below machine epsilon)

biplot(df, vars; <keyword arguments>)

Plot a PCA biplot (PC1 vs PC2 scores with loading vectors).

Requires at least 2 PCs; returns nothing with a warning otherwise.

Arguments

• df::DataFrame: input data
• vars::Union{Vector{String}, Vector{Symbol}}: variable names for PCA
• n::Int64=length(vars): number of PCs to compute (≥ 2 needed for the plot)
• zstd::Bool=true: if true, Z-score standardise before PCA

Returns

• GLMakie.Figure: biplot figure, or nothing if fewer than 2 PCs result

bootstrap_ci(s; <keyword arguments>)

Calculate a bootstrap confidence interval for a signal matrix.

Algorithm:

1. Stage 1 (n1 iterations): randomly draw n2 epochs (with replacement), average them → produces n1 bootstrap mean traces.
2. Stage 2: for each time point, sort the n1 bootstrap means and take the cl/2 and 1 − cl/2 quantiles as the lower and upper CI bounds.

Arguments

• s::AbstractMatrix: signal matrix, shape (samples, epochs)
• n1::Int64=3000: number of bootstrap resamples (outer loop); must be ≥ 1
• n2::Int64=1000: number of epochs drawn per resample (inner loop); must be ≥ 1
• cl::Float64=0.95: confidence level; must be in (0, 1)

Returns

Named tuple:

• gm::Vector{Float64}: bootstrap grand mean (averaged across all n1 resamples)
• ll::Vector{Float64}: lower CI bound at each time point
• ul::Vector{Float64}: upper CI bound at each time point

bootstrap_stat(s; <keyword arguments>)

Calculate a scalar statistic of a signal matrix using bootstrapping.

At each of the n1 iterations, n2 epochs are drawn at random (with replacement), averaged into a single trace, and the expression f is evaluated on that trace. The result is a distribution of the statistic across bootstrap resamples.

The formula string f must reference the current signal trace using the placeholder variable obj. For example: f = "abs(maximum(obj))".

Arguments

• s::AbstractMatrix: signal matrix, shape (samples, epochs)
• n1::Int64=3000: number of bootstrap resamples; must be ≥ 1
• n2::Int64=1000: number of epochs drawn per resample; must be ≥ 1
• f::String: Julia expression to evaluate on each bootstrap mean trace; use obj as the placeholder for the current trace vector

Returns

• AbstractVector: bootstrap distribution of the statistic; length n1

center(x)

Center a vector by subtracting its mean.

Arguments

• x::AbstractVector: input vector; must contain at least 1 element

Returns

• Vector{Float64}: mean-centered vector x .- mean(x)

chi2p(chi; <keyword arguments>)

Convert a χ² statistic to a right-tailed p-value P(χ² > chi).

Arguments

• chi::Real: χ² statistic; must be ≥ 0
• df::Real: degrees of freedom; must be > 0

Returns

• Float64: right-tailed p-value

Notes

To obtain the left-tailed probability P(χ² < chi) use 1 - chi2p(chi; df=df).

cim(x; <keyword arguments>)

Calculate the confidence interval for the mean.

Arguments

• x::AbstractVector: data vector; must contain at least 2 elements
• cl::Float64=0.95: confidence level; must be in (0, 1)
• d::Symbol=:t: istribution used for the critical value; :t (Student's t, recommended for small samples) or :z (standard normal)
• twotailed::Bool=true: if true, compute a two-sided interval

Returns

• Tuple{Float64, Float64}: (lower_bound, upper_bound)

cimd(x; <keyword arguments>)

Calculate the confidence interval for the median of a 1-D vector.

Uses the order-statistic method: the CI bounds are x[j] and x[k] where j and k are quantile-derived indices from the sorted data.

Arguments

• x::AbstractVector: data vector; must contain enough elements so that the derived indices j and k fall within [1, n]
• cl::Float64=0.95: confidence level; must be in (0, 1)

Returns

• Tuple{Float64, Float64}: (lower_bound, upper_bound)

cimd(x; <keyword arguments>)

Calculate the confidence interval for the median of a multi-dimensional array.

Column medians are computed, sorted, and the order-statistic CI method is applied across columns.

Arguments

• x::AbstractArray: data array; medians are taken along dims=1 (across rows per column); must have at least 2 columns
• cl::Float64=0.95: confidence level; must be in (0, 1)

Returns

• Tuple{Float64, Float64}: (lower_bound, upper_bound)

cip(p, n; <keyword arguments>)

Calculate the confidence interval for a proportion using the normal approximation (Wald interval).

Arguments

• p::Float64: sample proportion; must be in [0, 1]
• n::Int64: sample size; must be ≥ 1
• cl::Float64=0.95: confidence level; must be in (0, 1)

Returns

• Tuple{Float64, Float64}: (lower_bound, upper_bound)

cir(x, y; <keyword arguments>)

Calculate the confidence interval for a Pearson correlation coefficient computed from two vectors, using Fisher's Z transformation.

Arguments

• x::AbstractVector: first data vector; must have the same length as y and length > 3
• y::AbstractVector: second data vector
• cl::Float64=0.95: confidence level; must be in (0, 1)

Returns

• Tuple{Float64, Float64}: (lower_bound, upper_bound)

cir(; <keyword arguments>)

Calculate the confidence interval for a Pearson correlation coefficient using Fisher's Z transformation.

Transforms r to z = arctanh(r), applies the normal CI, then back-transforms with tanh.

Arguments

• r::Float64: Pearson correlation coefficient; must be in (−1, 1)
• n::Int64: number of observations; must be > 3
• cl::Float64=0.95: confidence level; must be in (0, 1)

Returns

• Tuple{Float64, Float64}: (lower_bound, upper_bound) in correlation units

cis(x; <keyword arguments>)

Calculate the confidence interval for the standard deviation using the chi-squared distribution.

Arguments

• x::AbstractVector: data vector; must contain at least 2 elements
• cl::Float64=0.95: confidence level; must be in (0, 1)

Returns

• Tuple{Float64, Float64}: (lower_bound, upper_bound)

civ(x; <keyword arguments>)

Calculate the confidence interval for the variance using the chi-squared distribution.

Arguments

• x::AbstractVector: data vector; must contain at least 2 elements
• cl::Float64=0.95: confidence level; must be in (0, 1)

Returns

• Tuple{Float64, Float64}: (lower_bound, upper_bound)

cl2z(ci; <keyword arguments>)

Convert a confidence level to the corresponding Z-score.

Arguments

• cl::Float64: confidence level; must be in (0, 1)
• twotailed::Bool=true: if true, returns the Z-score for a two-tailed interval, i.e. z such that P(−z ≤ X ≤ z) = cl; if false, returns the Z-score for a one-tailed interval, i.e. z such that P(X ≤ z) = cl

Returns

• Float64: critical Z-score

Notes

• Two-tailed (twotailed=true): the CI is (−z, +z)
• One-tailed (twotailed=false): the CI is (−∞, z) (upper bound) or equivalently (−z, +∞) (lower bound) depending on direction

cmp_stat(stat_dist, v)

Calculate the proportion of elements in a statistic distribution that are greater or lesser than a given value.

Arguments

• stat_dist::AbstractVector: distribution of statistic values; must not be empty
• v::Real: reference statistic value
• type::Symbol=:g: Comparison direction:
  • :g: proportion of elements > v
  • :l: proportion of elements < v

Returns

• Float64: proportion of elements satisfying the condition

cmp_test(seg1, seg2; <keyword arguments>)

Compare two vectors using an automatically selected or explicitly requested statistical test.

Test selection (when type = :auto):

1. Jarque–Bera test is applied to the pooled data to assess normality.
2. If normal: variances are compared with an F-test; an equal- or unequal-variance t-test (or a paired one-sample t-test) is used.
3. If non-normal: Wilcoxon signed-rank test (paired) or Mann–Whitney U test (unpaired) is used.

Arguments

• s1::AbstractVector: first signal vector
• s2::AbstractVector: second signal vector; must have the same length as s1 when paired = true
• paired::Bool" if true, treat the vectors as paired observations"
• alpha::Float64=0.05: significance level; must be in (0, 1)
• type::Symbol=:auto: test selection strategy:
  • :auto: choose automatically based on normality and variance tests
  • :perm: permutation-based test
  • :p: force parametric test
  • :np: force non-parametric test
• exact::Bool=false: if true, use the exact Wilcoxon signed-rank test (only applies when type ∈ {:auto, :np} and paired = true)
• nperm::Int64=1000: number of permutations for type = :perm; must be ≥ 1
• verbose::Bool=true: if true, print test selection and result details

Returns

Permutation test (type = :perm), named tuple:

• t::NamedTuple{perm_diff, obs_diff}: permutation null distribution and observed difference
• p1::Float64: one-tailed p-value
• p2::Float64: two-tailed p-value (2 × p1, clamped to 1.0)

All other tests, named tuple:

• t: the HypothesisTests.jl test object
• ts::Tuple{Float64, String}: test statistic value and its name
• tc: confidence interval of the test statistic (tuple or scalar NaN for non-parametric)
• df::Float64: degrees of freedom
• p::Float64: two-tailed p-value (clamped to eps() if below machine epsilon)

cor_test(seg1, seg2)

Calculate the Pearson correlation between two vectors and return associated test statistics.

Arguments

• s1::AbstractVector: first signal vector; must have the same length as s2 and length > 3 (required for the Fisher Z confidence interval)
• s2::AbstractVector: second signal vector

Returns

Named tuple:

• t::CorrelationTest{Float64}: full HypothesisTests.jl result object
• r::Float64: Pearson correlation coefficient
• rc::Tuple{Float64, Float64}: 95 % confidence interval for r
• ts::Tuple{Float64, String}: t-statistic and label "t"
• df::Int64: degrees of freedom (n1 + n2 − 2)
• p::Float64: two-tailed p-value (clamped to eps() if below machine epsilon)

count_thresh(x; <keyword arguments>)

Threshold a matrix and count the number of elements satisfying the condition.

Arguments

• x::AbstractMatrix: input matrix
• t::Real: threshold value
• t_type::Symbol=:g: thresholding rule:
  • :eq: x == t
  • :geq: x ≥ t
  • :leq: x ≤ t
  • :g: x > t
  • :l: x < t

Returns

Named tuple:

• x_t::Matrix{Bool}: boolean mask; true where the condition holds
• n::Int64: number of elements satisfying the condition

crit_chi(df, alpha)

Calculate the critical χ² value for a given degrees of freedom and significance level.

Arguments

• df::Real: degrees of freedom; must be > 0; typically df = n − 1
• alpha::Float64=0.05: significance level (upper or lower tail probability); must be in (0, 1)

Returns

• Float64: critical χ² value such that P(X ≤ chi) = alpha under χ²(df)

Notes

To obtain the upper-tail critical value (i.e. P(X > chi) = alpha) pass 1 − alpha as the alpha argument.

crit_t(df, alpha; <keyword arguments>)

Calculate the critical t-value for a given degrees of freedom and significance level.

Arguments

• df::Real: degrees of freedom; must be > 0; typically df = n − 1
• alpha::Float64=0.05: significance level (upper or lower tail probability); must be in (0, 1)
• twotailed::Bool=true: if true, compute the two-tailed critical value; if false, compute the one-tailed critical value

Returns

• Float64: critical t-value (always positive)

Notes

Critical regions:

• One-tailed left: (−∞, −t]
• One-tailed right: [t, +∞)
• Two-tailed: (−∞, −t] ∪ [t, +∞)

crit_z(alpha; <keyword arguments>)

Calculate the critical Z-score for a given significance level.

Arguments

• alpha::Float64=0.05: significance level (upper or lower tail probability); must be in (0, 1)
• twotailed::Bool=true: if true, compute the two-tailed critical value; if false, compute the one-tailed critical value

Returns

• Float64: critical Z-score (always positive; the rejection region is symmetric around zero)

Notes

Critical regions:

• One-tailed left: (−∞, −z]
• One-tailed right: [z, +∞)
• Two-tailed: (−∞, −z] ∪ [z, +∞)

cvm(x)

Calculate the coefficient of variation (CV) for the mean.

Computed as σ / μ, where σ = std(x) and μ = mean(x). Expresses the standard deviation as a fraction of the mean; meaningful only when mean(x) ≠ 0.

Arguments

• x::AbstractVector: input vector; must contain at least 2 elements and have a non-zero mean

Returns

• Float64: coefficient of variation (dimensionless ratio)

cvmd(x)

Calculate the coefficient of variation (CV) for the median.

Uses the robust formula (Q3 − Q1) / 2 / median(x), where Q1 and Q3 are the 25th and 75th percentiles (the semi-interquartile range normalised by the median). Meaningful only when median(x) ≠ 0.

Arguments

• x::AbstractVector: input vector; must contain at least 2 elements and have a non-zero median

Returns

• Float64: robust coefficient of variation (dimensionless ratio)

dap(x)

Calculate the D'Agostino–Pearson omnibus test for normality.

Combines standardized skewness (zs) and standardized kurtosis (zk) into a single chi-squared test statistic d = zs² + zk², which follows a χ²(2) distribution under the null hypothesis of normality.

Arguments

• x::AbstractVector: input vector; must contain at least 8 elements (ses and sek require sufficient sample size); a warning is issued for length(x) < 20 as the approximation is unreliable for small samples

Returns

Named tuple:

• zs::Float64: standardized skewness statistic (skewness(x) / ses(x))
• zk::Float64: standardized kurtosis statistic (kurtosis(x) / sek(x))
• d::Float64: omnibus test statistic zs² + zk²; follows χ²(2) under H₀
• p::Float64: p-value from the χ²(2) survival function

Notes

• The test requires n ≥ 20 for reliable results; a diagnostic message is printed for smaller samples.
• H₀: the data are normally distributed.
• H₁: the data are not normally distributed.

References

D'Agostino RB, Belanger A, D'Agostino RB Jr. A suggestion for using powerful and informative tests of normality. The American Statistician. 1990;44(4):316–21.

df(x)

Calculate the degrees of freedom for a vector (length(x) − 1).

Arguments

• x::AbstractVector: input vector; must contain at least 1 element

Returns

• Int64: degrees of freedom length(x) − 1

distance(p1, p2)

Calculate the Euclidean distance between two points.

Arguments

• p1::Tuple{Real, Real}: first point (x₁, y₁)
• p2::Tuple{Real, Real}: second point (x₂, y₂)

Returns

• Float64: Euclidean distance √((x₂−x₁)² + (y₂−y₁)²)

dprime(p1::Real, p2::Real)

Calculate the sensitivity index d′ and response bias for two proportions.

p1 is typically the hit rate and p2 the false-alarm rate. Both are converted to Z-scores using the inverse normal CDF, then combined as:

• d′ = Z(p1) − Z(p2)
• bias = −(Z(p1) + Z(p2)) / 2

Boundary values p ∈ {0, 1} produce ±Inf; callers should apply a correction (e.g. the Hautus log-linear rule) before passing boundary proportions.

Arguments

Named tuple:

• dp::Float64: sensitivity index d′
• rb::Float64: response bias (negative = liberal, positive = conservative)

References

Green DM, Swets JA. Signal Detection Theory and Psychophysics. Wiley; 1966.

dranks(x, nbins)

Scale tied ranks into discrete bins 1 … nbins.

Tied ranks are computed with StatsBase.tiedrank, normalised to (0, 1], then mapped to integers in [1, nbins] via ceil.

Arguments

• x::AbstractArray: input array of continuous values; must not be empty
• nbins::Int64: number of bins; defaults to Sturges' formula ceil(Int64, 1 + log2(length(x))); must be ≥ 1

Returns

• Array{Int64}: rank-bin indices ∈ [1, nbins], same shape as x

efs(x1, x2)

Calculate effect size measures for two independent samples.

Arguments

• x1::AbstractVector: first sample; must contain ≥ 2 elements with non-zero SD
• x2::AbstractVector: second sample; must contain ≥ 2 elements with non-zero SD

Returns

Named tuple:

• d::Float64: Cohen's d (pooled SD denominator, unbiased for equal n)
• g::Float64: Hedges' g (maximum-likelihood pooled SD; less biased for small n)
• delta::Float64: Glass' Δ (uses SD of x2 as the denominator; preferred when groups have different variances)

efs_p1g(p)

Calculate Cohen's h arcsine transformation for a single proportion.

Computes the arcsine-transformed proportion φ = 2 × arcsin(√p), which stabilizes the variance of a binomial proportion.

Arguments

• p::Float64: proportion; must be in [0, 1]

Returns

• Float64: transformed value φ = 2 × arcsin(√p)

efs_p2g(p1, p2; nd)

Calculate Cohen's h effect size for two independent proportions.

Computed as h = 2arcsin(√p1) − 2arcsin(√p2). The two proportions are independent and do not need to sum to 1.

Arguments

• p1::Float64: first proportion; must be in [0, 1]
• p2::Float64: second proportion; must be in [0, 1]
• nd::Bool=false: if true, return |h| (non-directional effect size)

Returns

• Float64: Cohen's h (signed, or absolute if nd=true)

f1(; <keyword arguments>)

Assess classification model performance using the F1-score.

The F1-score is the harmonic mean of precision and recall: F1 = 2 × (precision × recall) / (precision + recall)

Arguments

• tp::Int64: number of true positives; must be ≥ 0
• tn::Int64: number of true negatives; must be ≥ 0
• fp::Int64: number of false positives; must be ≥ 0
• fn::Int64: number of false negatives; must be ≥ 0

Returns

Named tuple:

• f1_score::Float64: F1-score ∈ [0, 1]
• prec::Float64: precision tp / (tp + fp)
• rec::Float64: recall tp / (tp + fn)

References

https://www.statology.org/what-is-a-good-f1-score/

f2p(t; <keyword arguments>)

Convert an F-statistic to a right-tailed p-value P(F > f).

Arguments

• f::Real: F-statistic; must be ≥ 0
• df1::Real: numerator degrees of freedom; must be > 0
• df2::Real: denominator degrees of freedom; must be > 0

Returns

• Float64: right-tailed p-value

Notes

To obtain the left-tailed probability P(F < f) use 1 - f2p(f; df1=df1, df2=df2).

fano(x)

Calculate the Fano factor.

Computed as σ² / μ, where σ² = var(x) and μ = mean(x). The Fano factor is a measure of the dispersion of a probability distribution relative to its mean; a value of 1 corresponds to a Poisson process.

Arguments

• x::AbstractVector: input vector; must contain at least 2 elements and have a non-zero mean

Returns

• Float64: Fano factor (units of x)

friedman(m)

Estimate Friedman's non-parametric two-way analysis of variance and the associated Kendall's coefficient of concordance W.

Rankings are computed within each group (column) across observations (rows). The Q statistic approximately follows a χ²(k − 1) distribution under H₀.

Arguments

• m::AbstractArray: data matrix of shape (observations × groups); must have ≥ 2 groups (columns) and ≥ 2 observations (rows)

Returns

Named tuple:

• q::Float64: Friedman's Q statistic
• w::Float64: Kendall's coefficient of concordance W ∈ [0, 1]
• p::Float64: p-value from the χ²(k − 1) distribution

Notes

• H₀ (Friedman): all treatment groups have the same distribution
• H₀ (Kendall): there is no agreement between rankings (W = 0)
• W = 0 indicates no agreement; W = 1 indicates perfect agreement

References

Friedman M. The use of ranks to avoid the assumption of normality implicit in the analysis of variance. Journal of the American Statistical Association. 1937;32(200):675–701.

grubbs(x; <keyword arguments>)

Perform the Grubbs test for a single outlier.

Tests whether the most extreme value in x (maximum, minimum, or both) is a statistically significant outlier at confidence level alpha.

The test statistic is:

• Two-tailed: G = max|xᵢ − x̄| / s
• Upper one-tailed: G = (max(x) − x̄) / s
• Lower one-tailed: G = (x̄ − min(x)) / s

The critical value is derived from the t-distribution with df = n − 2.

Arguments

• x::AbstractVector: input vector; must contain at least 7 elements
• alpha::Float64=0.95: confidence level (not significance level); must be in (0, 1); default 0.95 corresponds to a 5 % significance level
• t::Int64=0: test type:
  • 0: two-tailed (tests both extremes)
  • 1: upper one-tailed (tests maximum)
  • -1: lower one-tailed (tests minimum)

Returns

• Bool: true if an outlier is detected; false otherwise

References

Grubbs FE. Procedures for detecting outlying observations in samples. Technometrics. 1969;11(1):1–21.

hildebrand_rule(x; verbose)

Calculate the Hildebrand rule statistic for a vector.

Computed as H = (mean(x) − median(x)) / std(x). Values of |H| < 0.2 indicate approximate symmetry of the distribution.

Arguments

• x::AbstractVector: input vector; must contain at least 2 elements and have non-zero standard deviation
• verbose::Bool=true: if true, print a message when the symmetry criterion is met

Returns

• Float64: Hildebrand statistic H

Notes

The criterion |H| < 0.2 is checked (not just H < 0.2) because a negative mean–median difference also indicates asymmetry if its magnitude is ≥ 0.2.

infcrit(m)

Calculate R², adjusted R², AIC (with small-sample correction), and BIC for a fitted linear regression model.

The small-sample corrected AIC (AICc) is applied when n / k < 40: AICc = AIC + 2k(k+1) / (n − k − 1), where k is the number of predictors (excluding the intercept).

Arguments

• m::StatsModels.TableRegressionModel: fitted linear regression model

Returns

Named tuple:

• R2::Float64: coefficient of determination R²
• R2adj::Float64: adjusted R²; penalizes for the number of predictors
• aic::Float64: AIC (AICc-corrected when n / k < 40)
• bic::Float64: BIC

Notes

• k = number of predictors (coefficients excluding the intercept).
• AIC = 2k − 2L; BIC = k × ln(n) − 2L, where L = log-likelihood.
• AICc correction is applied when the sample-to-parameter ratio n/k < 40.

jaccsim(x, y)

Calculate the Jaccard similarity between two vectors.

Computed as |x ∩ y| / |x ∪ y| where |x ∪ y| = |x| + |y| − |x ∩ y|.

Values range from 0 (no common elements) to 1 (identical element sets).

Arguments

• x::AbstractVector: first vector; must not be empty
• y::AbstractVector: second vector; must not be empty

Returns

• Float64: Jaccard similarity ∈ [0, 1]

Notes

Jaccard distance = 1 − jaccsim(x, y).

k_categories(n)

Calculate the recommended number of histogram categories for a sample of size n.

Returns two common rules:

• Square-root choice: k1 = √n
• Sturges' extended rule: k2 = 1 + 3.222 × log₁₀(n)

Arguments

• n::Int64: sample size; must be ≥ 1

Returns

Named tuple:

• k1::Float64: square-root estimate
• k2::Float64: sturges' extended estimate

linreg(x, y)

Fit a simple linear regression model y ~ x.

Arguments

• x::AbstractVector: predictor vector; must have the same length as y and contain at least 3 elements
• y::AbstractVector: response vector

Returns

Named tuple:

• lr::StatsModels.TableRegressionModel: fitted model object
• c::Vector{Float64}: coefficients [intercept, slope]
• se::Vector{Float64}: standard errors of the coefficients
• R2::Float64: coefficient of determination R²
• R2adj::Float64: adjusted R²
• aic::Float64: Akaike Information Criterion (AICc-corrected when n/k < 40)
• bic::Float64: Bayesian Information Criterion
• lf::Vector{Float64}: fitted values (use plot(x, lf) to visualise)

Notes

To predict at new x-values:

new_x = DataFrame(x = [3.5, 7])
predict(lr, new_x)

logit(p)

Convert a proportion to its logit (log-odds).

Computed as log(p / (1 − p)). Returns −Inf for p = 0 and +Inf for p = 1.

Arguments

• p::Float64: proportion; must be in [0, 1]

Returns

• Float64: log-odds log(p / (1 − p))

make_table(; <keyword arguments>)

Display data as a formatted table using PrettyTables.jl.

The header row is prepended to the data and printed as a single table body with a horizontal separator after the first row.

Arguments

• header::Matrix{String}: single-row header matrix, e.g. ["Group" "A" "B"]; must have the same number of columns as data
• data::Matrix{Any}: data matrix, e.g. ["var1" 1.0 2.0; "var2" 3.0 4.0]; integer values are converted to strings before display

Returns

• Nothing

Notes

• The formatters = ft_printf("%1.3f", 2:3) format is hardcoded to columns 2 and 3; callers with a different column count should adjust the source accordingly.
• Integer elements in data are converted to String in-place to ensure uniform display.

mcc(; <keyword arguments>)

Assess classification model performance using the Matthews Correlation Coefficient (MCC).

MCC is a balanced metric that accounts for all four confusion-matrix cells, making it reliable even for imbalanced classes.

Computed as: MCC = (tp × tn − fp × fn) / √((tp+fp)(tp+fn)(tn+fp)(tn+fn))

MCC's value ranges from -1 to 1, depending on:

• A score of -1 denotes a complete discrepancy between expected and actual classes.
• 0 is equivalent to making an entirely arbitrary guess.
• Total agreement between expected and actual classes is indicated by a score of 1.

Arguments

• tp::Int64: number of true positives; must be ≥ 0
• tn::Int64: number of true negatives; must be ≥ 0
• fp::Int64: number of false positives; must be ≥ 0
• fn::Int64: number of false negatives; must be ≥ 0

Returns

• Float64: MCC ∈ [−1, 1]; returns 0.0 when the denominator is zero (degenerate classifier - all predictions in one class)

References

https://finnstats.com/index.php/2022/09/06/assess-performance-of-the-classification-model/

mde(; <keyword arguments>)

Calculate the minimum detectable effect (MDE) for a given sample size.

Computed as MDE = (z_α + z_β)² × s² / n.

Arguments

• n::Int64: number of subjects per group; must be ≥ 1
• s::Real: standard deviation; must be > 0
• alpha::Float64=0.05: type I error probability; must be in (0, 1)
• beta::Float64=0.20: type II error probability; must be in (0, 1)
• verbose::Bool=true: if true, print the critical Z-scores

Returns

• Float64: minimum detectable effect size

meanc(g, x)

Calculate the weighted mean of categorical data.

Computed as Σ(g × x) / Σx.

Arguments

• g::Vector{Int64}: group labels (e.g. [0, 1, 2, 3])
• x::Vector{Int64}: subject counts per group (e.g. [2, 8, 27, 45]); must be the same length as g, non-empty, and sum to ≥ 1

Returns

• Float64: weighted categorical mean

meancirc(x; <keyword arguments>)

Calculate the circular (angular) mean.

Uses the two-argument arctangent of the mean sine and cosine components.

Arguments

• x::AbstractVector: angles; must be non-empty
• rad::Bool=false: if true, x is in radians; if false, x is in degrees

Returns

• Float64: circular mean in the same unit as the input (radians or degrees)

meang(x)

Calculate the geometric mean.

Computed as exp(mean(log.(x))), which is numerically stable for large vectors (avoids overflow from prod(x)). All elements must be strictly positive.

Arguments

• x::AbstractVector: input vector; must be non-empty and contain only positive values

Returns

• Float64: geometric mean

meanh(x)

Calculate the harmonic mean.

Computed as n / Σ(1/xᵢ). All elements must be non-zero.

Arguments

• x::AbstractVector: input vector; must be non-empty and contain no zero values

Returns

• Float64: harmonic mean

meanp(p, n)

Calculate the expected count (mean) of a proportion.

Computed as n × p.

Arguments

• p::Float64: proportion; must be in [0, 1]
• n::Int64: number of observations; must be ≥ 1

Returns

• Float64: expected count n × p

meant(x; <keyword arguments>)

Calculate the trimmed mean.

Sorts x and removes the bottom and top n × 100 % of values before computing the mean.

Arguments

• x::AbstractVector: input vector; must contain enough elements so that trimming leaves at least one value
• n::Float64=0.1: fraction of values to trim from each tail; must be in (0, 0.5) to ensure a non-empty trimmed set

Returns

• Float64: trimmed mean

meanw(x, w)

Calculate the weighted mean.

Computed as Σ(xᵢ × wᵢ) / Σwᵢ.

Arguments

• x::AbstractVector: values vector; must be non-empty
• w::AbstractVector: weights vector; must have the same length as x and sum to a non-zero value

Returns

• Float64: weighted mean

moe(n)

Calculate the margin of error for a given sample size.

Computed as 1 / √n (the standard error of a proportion at p = 0.5).

Arguments

• n::Int64: sample size; must be ≥ 1

Returns

• Float64: margin of error

moe(x)

Calculate the margin of error for a data array based on its sample size.

Computed as 1 / √length(x).

Arguments

• x::AbstractArray: input array; must not be empty

Returns

• Float64: margin of error

mrng(x)

Calculate the midrange of an array: (maximum(x) − minimum(x)) / 2.

Arguments

• Float64: midrange of x.

mscr(; <keyword arguments>)

Assess classification model performance using the misclassification rate and accuracy.

• Misclassification rate: (fp + fn) / (tp + tn + fp + fn)
• Accuracy: 1 − misclassification rate

Arguments

• tp::Int64: number of true positives; must be ≥ 0
• tn::Int64: number of true negatives; must be ≥ 0
• fp::Int64: number of false positives; must be ≥ 0
• fn::Int64: number of false negatives; must be ≥ 0

Returns

Named tuple:

• mr::Float64: misclassification rate ∈ [0, 1]
• acc::Float64: accuracy ∈ [0, 1]

References

https://www.statology.org/misclassification-rate/

norminv(x::Real)

Return the quantile of the standard normal distribution at probability x.

Equivalent to Φ⁻¹(x) where Φ is the standard normal CDF.

Arguments

• x::Real: probability; must be in (0, 1)

Returns

• Float64: normal quantile at x

npca(m; <keyword arguments>)

Calculate the recommended number of principal components (PCs).

Arguments

• m::Matrix{Float64}: data matrix (observations × variables); must have ≥ 2 rows and ≥ 1 column
• zstd::Bool=true: if true, Z-score standardise each variable before PCA.
• type::Symbol: selection criterion:
  • :var: keep enough PCs to explain at least value fraction of total variance
  • :eig: keep PCs whose eigenvalue exceeds value
• value::Real: threshold; must be in (0, 1) for :var, or > 0 for :eig

Returns

• Int64: recommended number of PCs (≥ 1)

o2p(o::Float64)

Convert odds to a probability.

Computed as p = o / (1 + o).

Arguments

• o::Real: odds; must be ≥ 0

Returns

• Float64: probability ∈ [0, 1)

op(x, y)

Calculate the outer product of two vectors.

Computed as x × yᵀ, producing a matrix of shape (length(x) × length(y)).

Arguments

• x::AbstractVector: left vector; must not be empty
• y::AbstractVector: right vector; must not be empty

Returns

• Matrix: outer product matrix of shape (length(x), length(y))

outlier_detect(x; <keyword arguments>)

Detect outliers in a vector using a selected method.

Arguments

• x::AbstractVector: input vector; must contain at least 7 elements when using method = :g
• method::Symbol=:iqr: detection method:
  • :iqr: interquartile range (flags values outside Q1 − 1.5×IQR and Q3 + 1.5×IQR)
  • :z: Z-score (flags values with |z| > 3)
  • :g: iterative Grubbs test applied to both tails

Returns

• Vector{Bool}: boolean mask; true at each index identified as an outlier

Notes

• The :g method iteratively removes the most extreme value while length(x_tmp) > 6 (Grubbs requires at least 7 observations), checking both the maximum and minimum tails separately.
• Outlier indices are tracked relative to the original vector, so deletion from the working copy does not affect index mapping.

p2o(p::Float64)

Convert a probability to odds.

Computed as o = p / (1 − p).

Arguments

• p::Real: probability; must be in [0, 1) (odds undefined at p = 1)

Returns

• Float64: odds

p2z(p; <keyword arguments>)

Convert a p-value to the corresponding Z-score.

Arguments

• p::Float64=0.05: p-value; must be in (0, 1)
• twotailed::Bool=false: if true, compute the two-tailed Z-score; if false (default), compute the one-tailed Z-score

Returns

• Float64: Z-score such that P(Z > z) = p (one-tailed) or P(|Z| > z) = p (two-tailed)

pcacomp(m; <keyword arguments>)

Calculate the first n principal components (PCs) of a data matrix.

Arguments

• m::Matrix{Float64}: data matrix of shape (observations × variables); must have ≥ 2 rows and ≥ 1 column
• n::Int64=size(m, 2): number of PCs to compute; must satisfy 1 ≤ n ≤ size(m, 2)
• zstd::Bool=true: if true, Z-score standardize each variable before PCA

Returns

Named tuple:

• pc::DataFrame: PC scores; columns named PC1 … PCn
• pcv::Vector{Float64}: percentage of total variance explained by each PC
• pcm::Vector{Float64}: column means of the (possibly standardised) data
• pcp::Matrix{Float64}: PC projection (loading) matrix
• pc_model::MultivariateStats.PCA{Float64}: fitted PCA model object

pcacomp(df, vars; <keyword arguments>)

Calculate the first n principal components from selected columns of a DataFrame.

Arguments

• df::DataFrame: input data
• vars::Union{Vector{String}, Vector{Symbol}}: column names to use; must all exist in df and there must be at least 2
• n::Int64=length(vars): number of PCs; must satisfy 1 ≤ n ≤ length(vars)
• zstd::Bool=true: if true, Z-score standardize each variable before PCA

Returns

Named tuple:

• pc::DataFrame: PC scores; columns named PC1 … PCn
• pcv::Vector{Float64}: percentage of total variance explained by each PC
• pcm::Vector{Float64}: column means of the (possibly standardised) data
• pcp::Matrix{Float64}: PC projection (loading) matrix
• pc_model::MultivariateStats.PCA{Float64}: fitted PCA model object

permute(s, n)

Generate n cyclic permutations of a signal vector.

Each permutation randomly selects a split point and rotates the vector (moves the tail before the head).

Arguments

• s::AbstractVector: input signal vector; must contain at least 2 elements
• n::Int64: number of permutations; must be ≥ 1

Returns

• Matrix{Float64}: matrix, shape (n, length(s))

permute(s, n)

Generate n cyclic permutations of each row of a 2- or 3-D array.

Each permutation randomly selects a split point along the second axis and rotates that row cyclically.

Arguments

• s::AbstractArray: input array; must be 2- or 3-dimensional, with at least 2 elements along the second axis
• n::Int64: number of permutations; must be ≥ 1

Returns

• Array{Float64, 3}: shape (n × size(s,1) × size(s,2)) for 2-D input
• Array{Float64, 4}: shape (n × size(s,1) × size(s,2) × size(s,3)) for 3-D input

power_c1g(; <keyword arguments>)

Calculate study power for a one-group continuous outcome comparison (group vs population), using the t-distribution.

Arguments

• m::Real: population mean
• s::Real: population standard deviation; must be > 0
• xbar::Real: study group mean
• n::Int64: group sample size; must be ≥ 2
• alpha::Float64=0.05: type I error probability; must be in (0, 1)

Returns

• Float64: estimated study power

power_c2g(; <keyword arguments>)

Calculate study power for a two-group continuous outcome comparison.

Arguments

• m1::Real: group 1 mean
• s1::Real: group 1 standard deviation; must be > 0
• n1::Int64: group 1 sample size; must be ≥ 1
• m2::Real: group 2 mean
• s2::Real: group 2 standard deviation; must be > 0
• n2::Int64: group 2 sample size; must be ≥ 1
• alpha::Float64=0.05: type I error probability; must be in (0, 1)

Returns

• Float64: estimated study power

power_p1g(; <keyword arguments>)

Calculate study power for a one-proportion comparison (group vs population).

Arguments

• p1::Float64: study group proportion; must be in (0, 1)
• p2::Float64: population proportion; must be in (0, 1)
• n1::Int64: study group sample size; must be ≥ 1
• alpha::Float64=0.05: type I error probability; must be in (0, 1)

Returns

• Float64: estimated study power

power_p2g(; <keyword arguments>)

Calculate study power for a two-proportion comparison.

Arguments

• p1::Float64: group 1 proportion; must be in (0, 1)
• p2::Float64: group 2 proportion; must be in (0, 1)
• n1::Int64: group 1 sample size; must be ≥ 1
• n2::Int64: group 2 sample size; must be ≥ 1
• alpha::Float64=0.05: type I error probability; must be in (0, 1)

Returns

• Float64: estimated study power

prank(x)

Calculate percentile ranks for each element of x.

The percentile rank of element xᵢ is the proportion of values in x that are strictly less than xᵢ, expressed as a value in [0, 1): PR(xᵢ) = count(x .< xᵢ) / length(x)

Ties receive the same rank. Results are returned in the original element order.

Arguments

• x::AbstractVector: input vector; must not be empty

Returns

• Vector{Float64}: percentile ranks ∈ [0, 1), in the same order as x

pred_int(n)

Return the 95 % prediction interval multiplier adjusted for sample size n.

Values for n ≤ 19 are taken from a lookup table. Values for n ≥ 20 are approximated from published stepped ranges; a warning is issued because accuracy decreases for larger samples. For very large samples (n > 200) the value converges to the normal-distribution limit of 1.96.

Returns NaN for n = 1 (prediction interval is undefined for a single observation).

Arguments

• n::Int64: sample size; must be ≥ 1

Returns

• Float64: prediction interval multiplier

Notes

For n > 20 the result is approximate and a diagnostic warning is issued.

r1r2_zscore(; <keyword arguments>)

Calculate the Z-score for the difference between two independent Pearson correlation coefficients using Fisher's Z transformation.

The test statistic is: z = (atanh(r1) − atanh(r2)) / √(1/(n1 − 3) + 1/(n2 − 3))

Arguments

• r1::Float64: correlation coefficient for group 1; must be in (−1, 1)
• r2::Float64: correlation coefficient for group 2; must be in (−1, 1)
• n1::Int64: number of observations in group 1; must be > 3
• n2::Int64: number of observations in group 2; must be > 3

Returns

• Float64: Z-score for the difference r1 − r2

Notes

Both samples must have n > 3 for the Fisher Z standard error 1/√(n − 3) to be defined. The original guards (n > 0) were insufficient.

res_norm(x, g)

Test whether residuals follow a normal distribution, per group and overall.

For each group (and for the whole sample), residuals are computed as x .- mean(x_group). Normality is then assessed with:

• Anderson–Darling one-sample test against Normal(0, 1).
• Kolmogorov–Smirnov one-sample exact test against Normal(0, 1).

Arguments

• x::AbstractVector: data values; must not be empty
• g::Vector{Int64}=repeat([1], length(x)): group membership for each element of x; must have the same length as x

Returns

Named tuple:

• adt_p::Vector{Float64}: Anderson–Darling p-values; one per group (in sorted group order) plus one for the whole sample at the last index
• ks_p::Vector{Float64}: Kolmogorov–Smirnov p-values; same layout as adt_p

If there is only one group, both vectors have length 1 (whole-sample result only).

Notes

• Results are non-random: both tests compare residuals against the theoretical Normal(0, 1) distribution rather than a random reference sample.
• For large groups ExactOneSampleKSTest may be slow; consider wrapping in ApproximateOneSampleKSTest for n > 1000.

rfz(r)

Compute Fisher's Z transformation of a Pearson correlation coefficient.

Applies z = atanh(r). Because atanh(±1) is infinite, the boundary values r = ±1 are clamped to ±atanh(1 − ε) where ε = eps(), giving z ≈ ±18.368 in practice.

Arguments

• r::Float64: Pearson correlation coefficient; must be in [−1, 1]

Returns

• Float64: Fisher z-transformed value

Notes

• Boundary clamping: rfz(1.0) ≈ 18.368, rfz(-1.0) ≈ -18.368.
• For values strictly inside (−1, 1) the result equals atanh(r) exactly.

rmna(x)

Return a copy of x with all NaN and Missing values removed.

Arguments

• x::AbstractVector: input vector; may contain Float64, Missing, or NaN

Returns

• Vector{Float64}: filtered vector converted to Float64

rng(x)

Calculate the range of an array (maximum − minimum).

Arguments

• x::AbstractArray: input array; must not be empty

Returns

• Float64: range of x

screeplot(df, vars; <keyword arguments>)

Plot a PCA scree plot showing variance explained and eigenvalues per PC.

Arguments

• df::DataFrame: input data
• vars::Union{Vector{String}, Vector{Symbol}}: variable names for PCA
• n::Int64=length(vars): number of PCs to compute
• zstd::Bool=true: if true, Z-score standardize before PCA

Returns

• GLMakie.Figure: two-panel figure (% variance explained + eigenvalues)

sdi(x, y)

Calculate the Sørensen–Dice similarity index between two vectors.

Computed as 2|x ∩ y| / (|x| + |y|). Values range from 0 to 1.

Arguments

• x::AbstractVector: first vector; must not be empty
• y::AbstractVector: second vector; must not be empty

Returns

• Float64: Sørensen–Dice index ∈ [0, 1], rounded to 2 decimal places

Notes

Interpretation guide:

• 0.80–1.00: very high similarity
• 0.60–0.79: high similarity
• 0.40–0.59: moderate similarity
• 0.20–0.39: low similarity
• 0.00–0.19: very low similarity

sek(x)

Calculate the standard error of kurtosis.

Computed as 2 × (n−1) × √(6n / ((n−2)(n−3)(n+3)(n+5))).

Requires n ≥ 4 so that the (n−3) term in the denominator is non-zero.

Arguments

• x::AbstractVector: input vector; must contain at least 4 elements.

Returns

• Float64: standard error of kurtosis

sek(n)

Calculate the standard error of kurtosis for a sample of size n.

Computed as 2 × (n−1) × √(6n / ((n−2)(n−3)(n+3)(n+5))).

Arguments

• n::Int64: sample size; must be ≥ 4

Returns

• Float64: standard error of kurtosis

sem(x)

Calculate the standard error of the mean.

Computed as std(x) / √n.

Arguments

• x::AbstractVector: input vector; must contain at least 2 elements

Returns

• Float64: standard error of the mean

semd(x)

Calculate the standard error of the median.

Approximated as 1.253 × std(x) / √n (valid for large normal samples).

Arguments

• x::AbstractVector: input vector; must contain at least 2 elements

Returns

• Float64: standard error of the median

sem_diff(x, y)

Calculate the standard error of the difference between two means.

For equal-length vectors: √(SEM(x)² + SEM(y)²).

For unequal-length vectors: pooled SD × √(1/n1 + 1/n2).

Arguments

• x::AbstractVector: first sample; must contain at least 2 elements
• y::AbstractVector: second sample; must contain at least 2 elements

Returns

• Float64: standard error of the mean difference

sen(n)

Calculate the standard error of a count (√n).

Arguments

• n::Int64: number of observations; must be ≥ 1

Returns

• Float64: √n.

sen_diff(n1, n2)

Calculate the standard error of the difference between two counts.

Computed as √(n1 + n2).

Arguments

• n1::Int64: group 1 count; must be ≥ 1
• n2::Int64: group 2 count; must be ≥ 1

Returns

• Float64: √(n1 + n2)

sep(p, n)

Calculate the standard error of a proportion.

Computed as √(p(1 − p) / n).

Arguments

• p::Float64: proportion; must be in [0, 1]
• n::Int64: number of observations; must be ≥ 1

Returns

• Float64: standard error of the proportion

sep_diff(p1, p2, n1, n2)

Calculate the standard error of the difference between two proportions.

Computed as √(p1(1−p1)/n1 + p2(1−p2)/n2).

Arguments

• p1::Float64: proportion of group 1; must be in [0, 1]
• p2::Float64: proportion of group 2; must be in [0, 1]
• n1::Int64: group 1 sample size; must be ≥ 1
• n2::Int64: group 2 sample size; must be ≥ 1

Returns

• Float64: standard error of the difference in proportions

ses(x)

Calculate the standard error of skewness.

Computed as √(6n(n−1) / ((n−2)(n+1)(n+3))).

Requires n ≥ 3 so that the denominator is non-zero.

Arguments

• x::AbstractVector: input vector; must contain at least 3 elements

Returns

• Float64: standard error of skewness

ses(n)

Calculate the standard error of skewness for a sample of size n.

Arguments

• n::Int64: sample size; must be ≥ 3

Returns

• Float64: standard error of skewness

size_c1diff(; <keyword arguments>)

Calculate required sample size for detecting a difference in variance (study SD vs population SD) using a lookup table.

Arguments

• s1::Real: study SD to detect; ratio s1/s2 must be in [0.1, 1.5]
• s2::Real: population SD; must be > 0
• twotailed::Bool=true: if true, return twice the one-sided table value
• power::Float64=0.8: desired power; must be in [0.8, 0.99]

Returns

• Int64: required sample size (doubled if twotailed=true)

Notes

Values outside the table range are clamped to the nearest boundary and a warning is issued.

size_c1g(; <keyword arguments>)

Calculate the required sample size for a one-group continuous outcome study (group vs population).

Arguments

• m::Real: population mean
• s::Real: population standard deviation; must be > 0
• xbar::Real: expected study group mean; must differ from m
• alpha::Float64=0.05: type I error probability; must be in (0, 1)
• power::Float64=0.8: desired power; must be in (0, 1)
• iter::Bool=false: if true, use an iterative power search (n from 2 to 10,000)

Returns

• Int64: required sample size

size_c2g(; <keyword arguments>)

Calculate the required sample size for a two-group continuous outcome study.

Assumes equal group standard deviations (both equal to s1).

Arguments

• m1::Real: group 1 mean
• s1::Real: group 1 standard deviation (assumed equal for both groups); must be > 0
• m2::Real: group 2 mean (expected)
• r::Int64=1: enrollment ratio (group 2 / group 1); must be ≥ 1
• alpha::Float64=0.05: type I error probability; must be in (0, 1)
• power::Float64=0.8: desired power; must be in (0, 1)

Returns

Named tuple:

• n1::Int64: group 1 sample size
• n2::Int64: group 2 sample size

size_m(; <keyword arguments>)

Calculate the required sample size for estimating a population mean within a margin of error E.

Arguments

• sigma::Real: population standard deviation; must be > 0
• alpha::Float64=0.05: type I error probability; must be in (0, 1)
• E::Real: desired margin of error; must be > 0

Returns

• Int64: required sample size

size_p(; <keyword arguments>)

Calculate the required sample size for estimating a proportion within a margin of error E.

Arguments

• p::Union{Float64, Nothing}=nothing: expected proportion; if nothing, uses the conservative estimate p = 0.5
• alpha::Float64=0.05: type I error probability; must be in (0, 1)
• E::Float64: desired margin of error; must be in (0, 1)

Returns

• Int64: required sample size

size_p1diff(; <keyword arguments>)

Calculate required sample size for detecting a difference in proportions (study vs population) using a lookup table.

Arguments

• p1::Float64: study group proportion; must be in (0, 1)
• p2::Float64: population proportion; must be in (0, 1)
• power::Float64=0.8: desired power; must be in [0.8, 0.99]

Returns

• Int64: total required sample size (both groups combined)

Notes

Values outside the table range are clamped and a warning is issued.

size_p1g(; <keyword arguments>)

Calculate the required sample size for a one-group proportion study (group vs population).

Arguments

• p1::Float64: population proportion; must be in (0, 1)
• p2::Float64: study group proportion; must be in (0, 1) and ≠ p1
• alpha::Float64=0.05: type I error probability; must be in (0, 1)
• power::Float64=0.8: desired power; must be in (0, 1)

Returns

• Int64: required sample size

size_p2g(; <keyword arguments>)

Calculate the required sample size for a two-group proportion study.

Arguments

• p1::Float64: group 1 proportion; must be in (0, 1)
• p2::Float64: group 2 proportion; must be in (0, 1) and ≠ p1
• r::Int64=1: enrollment ratio (group 2 / group 1); must be ≥ 1
• alpha::Float64=0.05: type I error probability; must be in (0, 1)
• power::Float64=0.8: desired power; must be in (0, 1)

Returns

Named tuple:

• n1::Int64: group 1 sample size
• n2::Int64: group 2 sample size

slope(p1, p2)

Calculate the slope of the line passing through two points.

Arguments

• p1::Tuple{Real, Real}: first point (x₁, y₁)
• p2::Tuple{Real, Real}: second point (x₂, y₂); x₂ ≠ x₁

Returns

• Float64: slope (y₂ − y₁) / (x₂ − x₁)

stdc(g, x)

Calculate the standard deviation of categorical data.

Arguments

• g::Vector{Int64}: group labels (e.g. [0, 1, 2, 3])
• x::Vector{Int64}: number of subjects per group; same length as g

Returns

• Float64: standard deviation of the categorical variable

stdp(p, n)

Calculate the standard deviation of a proportion.

Computed as √(p × (1 − p) / n).

Arguments

• p::Float64: proportion; must be in [0, 1]
• n::Int64: number of observations; must be ≥ 1

Returns

• Float64: standard deviation of the proportion

stdp(x1, x2; <keyword arguments>)

Calculate the pooled standard deviation from two sample vectors.

Arguments

• x1::AbstractVector: first sample; must contain ≥ 2 elements
• x2::AbstractVector: second sample; must contain ≥ 2 elements
• type::Symbol=:cohen: pooling method:
  • :cohen: √(((n1−1)s1² + (n2−1)s2²) / (n1+n2−2)); requires n1+n2 > 2
  • :hedges: √(((n1−1)s1² + (n2−1)s2²) / (n1+n2)) (MLE; slightly biased downward)

Returns

• Float64: pooled standard deviation

stdp(s1, s2, n1, n2; <keyword arguments>)

Calculate the pooled standard deviation from summary statistics when group sizes differ.

Arguments

• s1::Real: standard deviation of group 1; must be ≥ 0
• s2::Real: standard deviation of group 2; must be ≥ 0
• n1::Int64: sample size of group 1; must be ≥ 2
• n2::Int64: sample size of group 2; must be ≥ 2
• type::Symbol=:cohen: pooling method:
  • :cohen: √(((n1−1)s1² + (n2−1)s2²) / (n1+n2−2)); requires n1+n2 > 2
  • :hedges: √(((n1−1)s1² + (n2−1)s2²) / (n1+n2)) (MLE; slightly biased downward)

Returns

• Float64: pooled standard deviation

stdp(s1, s2)

Calculate the pooled standard deviation when both groups have equal size.

Computed as √((s1² + s2²) / 2).

Arguments

• s1::Real: standard deviation of group 1; must be ≥ 0
• s2::Real: standard deviation of group 2; must be ≥ 0

Returns

• Float64: pooled standard deviation

summary(x; g)

Return summary statistics for a single vector, printing a formatted table.

Arguments

• x::AbstractVector: input data; may contain Missing or NaN values (removed before computation)
• g::String="": optional group label shown in the table header

Returns

Named tuple:

• n::Int64: total number of observations (including missing)
• ms::Int64: number of missing / NaN observations
• m::Float64: mean
• v::Float64: variance
• s::Float64: standard deviation
• min::Float64: minimum
• q1::Float64: first quartile (25th percentile)
• me::Float64: median
• q3::Float64: third quartile (75th percentile)
• max::Float64: maximum
• mo::Float64: mode

summary(x; g, d)

Return summary statistics for each column of a matrix, printing a formatted table.

Arguments

• x::AbstractMatrix: data matrix; each column is treated as one group. may contain Missing or NaN values
• g::Vector{String}: group labels; length must equal size(x, 2)
• d::Int64=3: number of decimal places for rounding

Returns

• DataFrame: one row per group with columns :group, :n, :missing, :mean, :var, :std, :min, :Q1, :median, :Q3, :max, :mode

summary(x; g, d)

Return summary statistics for each vector in a varargs list, printing a formatted table.

Arguments

• x::AbstractArray...: one or more data vectors (passed as positional arguments)
• g::Vector{String}: group labels; length must equal the number of vectors
• d::Int64=3: number of decimal places for rounding

Returns

• DataFrame: one row per group with columns :group, :n, :missing, :mean, :var, :std, :min, :Q1, :median, :Q3, :max, :mode

sumsq(x)

Calculate the sum of squared deviations from the mean.

Computed as Σ(xᵢ − x̄)².

Arguments

• x::AbstractVector: input vector; must contain at least 2 elements

Returns

• Float64: sum of squared deviations

t2p(t; <keyword arguments>)

Convert a t-score to a p-value using the Student's t-distribution.

Arguments

• t::Real: t-statistic
• df::Real: degrees of freedom; must be > 0
• twotailed::Bool=false: if true, compute P(|T| > |t|); if false, compute P(T > t) for t ≥ 0 or P(T < t) for t < 0

Returns

• Float64: p-value ∈ (0, 1)

Notes

Derived probabilities:

• P(T < t) (left-tailed): 1 - t2p(t; df=df, twotailed=false)
• P(|T| < t): 1 - t2p(t; df=df, twotailed=true)
• P(0 < T < t): (1 - t2p(t; df=df, twotailed=true)) / 2

varc(g, x)

Calculate the variance of categorical data using group labels and counts.

Arguments

• g::Vector{Int64}: group labels (e.g. [0, 1, 2, 3])
• x::Vector{Int64}: number of subjects per group (e.g. [2, 8, 27, 45]); must be the same length as g, non-empty, and sum to > 1

Returns

• Float64: variance of the categorical variable

Notes

Formula: (Σ(g² × x) − (Σ(g × x))² / Σx) / (Σx − 1)

varp(p, n)

Calculate the variance of a proportion.

Computed as p × (1 − p) / n (the variance of a binomial proportion estimator).

Arguments

• p::Float64: proportion; must be in [0, 1]
• n::Int64: number of observations; must be ≥ 1

Returns

• Float64: variance of the proportion

z2p(z; <keyword arguments>)

Convert a Z-score to a p-value.

Arguments

• z::Real: Z-score
• twotailed::Bool=false: if true, compute the two-tailed probability P(|Z| > |z|); if false, compute the one-tailed probability P(Z > z) for z ≥ 0 or P(Z < z) for z < 0.

Returns

• Float64: p-value ∈ (0, 1)

Notes

Derived probabilities:

• P(Z < z) (left-tailed): 1 - z2p(z; twotailed=false)
• P(|Z| < z): 1 - z2p(z; twotailed=true)
• P(0 < Z < z): (1 - z2p(z; twotailed=true)) / 2

zscore(x)

Calculate Z-scores for each element of a vector.

Computed as (xᵢ − mean(x)) / std(x).

Arguments

• x::AbstractVector: input vector; must contain at least 2 elements and have non-zero standard deviation

Returns

• Vector{Float64}: Z-scores with mean ≈ 0 and SD ≈ 1

zscore(x, m, sd)

Calculate the Z-score of a single value given a known mean and standard deviation.

Computed as (x − m) / sd.

Arguments

• x::Real: observed value
• m::Real: population or sample mean
• sd::Real: population or sample standard deviation; must not be zero

Returns

• Float64: Z-score

export_csv(obj; <keyword arguments>)

Export a NeuroAnalyzer.NEURO object to CSV (and optional sidecar files).

The primary signal data is always written to file_name. When the corresponding flag is true, companion files are created next to it using the same base name:

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• file_name::String: path of the primary output CSV file
• names::Bool=true: write channel names as the CSV header row
• header::Bool=false: export recording/subject/experiment metadata to a sidecar text file
• epoch_time::Bool=false: export per-epoch time points to a sidecar CSV
• markers::Bool=false: export event markers to a sidecar CSV (skipped when the markers table is empty)
• locs::Bool=false: export channel locations to a sidecar CSV (skipped when the locations table is empty)
• history::Bool=false: export processing history to a sidecar text file (skipped when history is empty)
• overwrite::Bool=false: allow overwriting existing files; throws ArgumentError otherwise

Returns

• Nothing

export_locs(obj; <keyword arguments>)

Export channel location data from a NeuroAnalyzer.NEURO object to a file.

The output format is determined automatically from file_name's extension:

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• file_name::String: output file path; extension determines the format
• overwrite::Bool=false: allow overwriting an existing file; throws ArgumentError otherwise

Returns

• Nothing

export_locs(locs; <keyword arguments>)

Export a channel-locations DataFrame to a file.

The output format is determined automatically from file_name's extension:

Arguments

• locs::DataFrame: channel locations table (must contain the standard NeuroAnalyzer location columns)
• file_name::String: output file path; extension determines the format
• overwrite::Bool=false: allow overwriting an existing file; throws ArgumentError otherwise

Returns

• Nothing

export_markers(obj; <keyword arguments>)

Export the event markers table of a NeuroAnalyzer.NEURO object to a CSV file.

If the markers table is empty, a warning is issued and no file is written.

Arguments

• obj::NeuroAnalyzer.NEURO: input NEURO object
• file_name::String: path of the output CSV file
• overwrite::Bool=false: allow overwriting an existing file; throws ArgumentError otherwise

Returns

• Nothing

import_alice4(file_name; <keyword arguments>)

Load an EDF file exported from the Alice 4 Polysomnography System and return a NeuroAnalyzer.NEURO object.

Alice 4 EDF files are non-conforming in two ways that prevent import_edf from handling them:

• The data_records header field is always -1 (unknown); the true record count is inferred from file size.
• Channels may have different sampling rates; they are upsampled to the highest rate using Fourier resampling.

Arguments

• file_name::String: name of the file to load
• detect_type::Bool=true: infer channel type from channel label

Returns

• NeuroAnalyzer.NEURO

import_bdf(file_name; <keyword arguments>)

Load a BDF or BDF+ file and return a NeuroAnalyzer.NEURO object.

BDF is BioSemi's 24-bit extension of the EDF format. Each sample is stored as a 24-bit little-endian two's-complement integer. BDF files always carry a Status channel as their last channel; BDF+ files may additionally contain annotation channels which are parsed into event markers and removed from the signal data.

Arguments

• file_name::String: name of the file to load
• detect_type::Bool=true: infer channel type from channel label

Returns

• NeuroAnalyzer.NEURO

Notes

• sampling_rate = samples_per_datarecord ÷ data_record_duration
• gain = (physical_max − physical_min) / (digital_max − digital_min)
• value = (raw − digital_min) × gain + physical_min

References

1. https://www.biosemi.com/faq/file_format.htm

import_bv(file_name; <keyword arguments>)

Load a BrainVision BV/BVCDF recording and return a NeuroAnalyzer.NEURO object.

At minimum two files are required: a .vhdr (or .ahdr) header file and the corresponding .eeg signal file. Event markers are loaded automatically from the .vmrk file when present, or from a BIDS-style _events.tsv sidecar.

Channel locations are read from the [Coordinates] section of the header when available. A BIDS JSON sidecar (.json) is parsed for experiment metadata.

Arguments

• file_name::String: path to the .vhdr or .ahdr header file
• detect_type::Bool=true: infer channel type from channel label

Returns

• NeuroAnalyzer.NEURO

import_cnt(file_name; <keyword arguments>)

Load a Neuroscan continuous signal (CNT) file and return a NeuroAnalyzer.NEURO object.

CNT files store a fixed 900-byte global header, a per-channel header block (75 bytes × number of channels), multiplexed signal data, and an event table. Three event-table variants are supported (TEEG types 1, 2, and 3).

Arguments

• file_name::String: name of the file to load
• detect_type::Bool=true: infer channel type from channel label
• data_format::Symbol=:i32: sample width; :i16 for 16-bit or :i32 for 32-bit; Neuroscan does not encode this in the file header - you must supply it based on your recording setup

Returns

• NeuroAnalyzer.NEURO

Notes

Based on loadcnt.m by Sean Fitzgibbon and Arnaud Delorme (https://cnl.salk.edu/~arno/cntload/index.html).

import_csv(file_name; <keyword arguments>)

Load a CSV (or gzip-compressed CSV) file and return a NeuroAnalyzer.NEURO object.

The file layout (time × channels or channels × time) is detected automatically from the type of the first column:

• Time × channels: first column is numeric (time axis); remaining columns are channels labelled by their header row.
• Channels × time: first column is a string (channel names); remaining column headers are parsed as time points.

Sampling rate is inferred from the step between the first two time points.

Gzip-compressed files (.csv.gz) are decompressed automatically by CSV.jl.

Arguments

• file_name::String: path to the .csv or .csv.gz file
• detect_type::Bool=true: infer channel type from channel label

Returns

• NeuroAnalyzer.NEURO

import_dat(file_name)

Load a Neuroscan DAT behavioural data file and return it as a DataFrame.

The DAT format has a 20-line text header followed by space-separated data rows with five columns: event index, trial number, response, type, and correctness flag. Event indices are stored as 1-based in the file and are converted to 0-based on import to match Neuroscan's convention.

Arguments

• file_name::String: path to the .dat file

Returns

• DataFrame: table with columns :event, :trial, :response, :type, :correct

import_digitrack(file_name; <keyword arguments>)