A circular statistics toolbox for computing polar metrics. It includes functions for calculating angular and radial metrics.

Author:
Germano Gallicchio, Bangor University

Reference:
Gallicchio, G. (2025). Polar. GitHub. https://github.com/GermanoGallicchio/Polar/

Code developed on MATLAB R2022b on a Windows 10 device.

• Compute mean resultant vector metrics (e.g., used for Inter-Trial Phase Clustering, Phase Locking, Phase Amplitude Coupling)
• Optional trimming of outliers
• Perform transformations (e.g., logit, FisherZ)

Assume we have a set of complex numbers c, each describing:

• a direction (or angle or phase) arg(c)
• a length (or magnitude) |c|

In formula (with Euler's notation):

$$ c = |c| \ e^{i \ arg(c)} $$

The complex number could be made of angle and magnitude from the same signal (e.g., coefficients of continuous wavelent transform). Or the complex number could be artificially assembled with the angle of a signal and the magnitude of another signal (e.g., to study the phase-magnitude coupling). Sometimes we are only interested in magnitude (you won't need Polar for this). Other times we are only interested in angles (e.g., preference for a certain angle across replicates). Below is a series of formulas describing important polar metrics. By assembling angle and magnitude appropriately, these polar metrics correspond with popular measures of angle-based consistency, such as Inter-Trial Phase Clustering (ITPC), phase-amplitude coupling (PAC), and others. A non-exhaustive list will be provided below on how to use Polar metrics to obtain these measures.

$$ n^{-1} \left| \sum_{t=1}^n c_t \right| $$

$$ \frac{n^{-1} \left| \sum_{t=1}^n c_t \right|}{n^{-1} \sum_{t=1}^n \left| c_t \right|} $$

$$ \arg\left( \sum_{t=1}^n c_t \right) $$

upcoming...

upcoming...

theta contains the phases of signal A

rho contains the magnitudes of signal A ... we don't care about it

po_meanResultant(theta, ones(size(theta)))

ask for "meanResultantLength" for ITPC and "UmeanResultantSquaredLength" for PPC

theta contains the phases of signal A

rho contains the magnitudes of signal B

we just need the (normalized, if you prefer) mean resultant length of rho exp(1i*theta)

po_meanResultant(theta, rho)

theta contains the phases of signal A

rho contains the magnitudes of signal B

[theta_demeaned, rho_demeaned] = po_demean(theta,ones(size(theta)));
po_meanResultant(theta_demeaned, rho.*rho_demeaned);