How brainets/frites works
1. What this repository is
Frites is a Python scientific library for information-theoretic analysis of neurophysiological data. Its main purpose is to compute mutual information, connectivity, and related statistics on M/EEG and intracranial recordings, usually to study task-modulated brain networks.
2. Top-level architecture
The package is organized as a set of analysis subsystems under frites/, with each subsystem focused on one stage of the pipeline: data preparation, estimator computation, connectivity analysis, statistics, simulation, plotting, and workflow orchestration. The repo also includes docs, examples, and tests for each major module.
3. Data and experiment modeling
frites.dataset is the boundary where neurophysiology data is normalized into analysis-ready structures. It provides dataset/single-subject abstractions and utilities that likely wrap or harmonize inputs from MNE, xarray, and raw NumPy arrays so the rest of the library can operate on a consistent representation.
4. Core information-theory primitives
frites.core contains the low-level numerical routines that implement the actual information-theoretic estimators and transforms, such as copula normalization, Gaussian-copula MI, and bin-based MI for electrophysiology. These functions form the computational kernel used by higher-level estimators and workflows.
5. Estimator layer
frites.estimator defines reusable estimator objects for different measure families: binned estimators, correlation, distance correlation, Gaussian-copula MI, custom estimators, and resampling-based estimators. This layer abstracts “what metric to compute” from “how the data is organized,” which makes it the main plug-in point for analysis methods.
6. Connectivity analysis subsystem
frites.conn is the largest domain-specific area and covers undirected and directed connectivity methods such as cross-correlation, covariance-based Granger causality, dynamic functional connectivity, instantaneous interaction, partial information decomposition, transfer entropy, time-frequency connectivity, and fitting/io utilities. This is where the package turns prepared time series or trial data into pairwise or network-level connectivity outputs.
7. Workflow orchestration
frites.workflow ties datasets, estimators, connectivity methods, and statistics together into end-to-end analysis pipelines. The workflow layer is the user-facing orchestration boundary: it standardizes how inputs are passed through preprocessing, metric computation, aggregation, and statistical evaluation.
8. Statistics and inference
frites.stats provides parametric, nonparametric, and multiple-comparison procedures. This layer consumes outputs from workflows or connectivity computations and produces inference-ready results such as significance tests, corrections, and group-level summaries.
9. Simulation and synthetic data
frites.simulations generates artificial data for validating algorithms and demonstrating use cases, including autoregressive models, mutual-information scenarios, and local MI simulations. These modules act as a testing and benchmarking data source for the estimators and workflows.
10. Visualization and utility boundaries
frites.plot contains plotting helpers for connectivity results, while frites.utils and frites.io provide cross-cutting support such as preprocessing, parallel execution, performance helpers, dependency checks, system logging, and metadata handling. These are not the core analytics layer but support reproducibility and usability.
11. Documentation, examples, and tests as part of the architecture
The docs/ tree is extensive and documents the API by subsystem, with overview pages and usage guides that mirror the package layout. examples/ provides scenario-based demonstrations for datasets, MI, connectivity, statistics, simulations, xarray integration, and performance comparisons. The test suite is organized per module, reinforcing the same subsystem boundaries used in the code.
12. External technologies that shape the design
The package is built as a Python distribution and depends materially on NumPy, SciPy, Joblib, Xarray, and MNE, with optional acceleration or plotting support via Numba, Dcor, Matplotlib, Seaborn, and NetworkX. These dependencies explain the architecture: numeric kernels in core, data interoperability in dataset, and parallel/statistical workflows in higher layers.
13. Overall data flow
A typical flow is: raw neurophysiology data enters through dataset abstractions, is preprocessed and standardized, passed to an estimator or connectivity workflow, computed in core numerical routines, then summarized by statistics and optionally visualized. The repository is therefore structured as a layered analysis pipeline rather than a monolithic application.
Main entry points: workflow Workflow · conn Connectivity · dataset Dataset · core Core
Components 22
Core math
Low-level information-theoretic kernels and estimators.
- Core · Low-level information-theoretic primitives used by estimators and workflows.
frites/core - Copnorm · Copula normalization and related preprocessing transforms.
frites/core/copnorm.py - GCMI · Gaussian-copula mutual information implementations.
frites/core/gcmi_nd.py - Binned MI · Bin-based mutual-information routines for electrophysiology.
frites/core/mi_bin_ephy.py
Data layer
Dataset normalization and subject-level abstractions.
- Dataset · Normalizes neurophysiology inputs into analysis-ready dataset abstractions.
frites/dataset - Ephy DS · Electrophysiology dataset construction and harmonization.
frites/dataset/ds_ephy.py - Subject DS · Single-subject electrophysiology representation and helpers.
frites/dataset/suj_ephy.py
Connectivity
Pairwise, directed, and time-frequency connectivity methods.
- Connectivity · Connectivity analyses spanning undirected, directed, and time-frequency methods.
frites/conn - Conn ops · Cross-correlation, covariance GC, instantaneous interaction, PID, TE, and related computations.
frites/conn/conn_utils.py - Spec/TF · Spectral, sliding-window, and time-frequency connectivity routines.
frites/conn/conn_spec.py
Analysis layer
Workflows, statistics, simulations, plotting, and support utilities.
- Estimators · Reusable estimator objects that define what measure to compute.
frites/estimator - Bin est · Binned estimator interface.
frites/estimator/est_bin.py - GCMI est · Gaussian-copula mutual-information estimator interface.
frites/estimator/est_gcmi.py - Corr est · Correlation-based estimator family.
frites/estimator/est_corr.py - Workflow · End-to-end pipelines combining datasets, estimators, connectivity, and statistics.
frites/workflow - Stats · Parametric, nonparametric, and multiple-comparison inference utilities.
frites/stats - Simulations · Generates artificial data for validation, benchmarking, and examples.
frites/simulations - Plotting · Plot helpers for connectivity and result summaries.
frites/plot - Utils · Parallelism, preprocessing, performance, and wrapper helpers.
frites/utils - IO · Dependency checks, attributes, and system logging support.
frites/io
Connections 27
- Dataset → Ephy DS: contains · Dataset package provides electrophysiology dataset construction.
- Dataset → Subject DS: contains · Dataset package provides subject-level abstractions.
- Core → Copnorm: implements · Core package includes copula normalization transforms.
- Core → GCMI: implements · Core package includes Gaussian-copula MI kernels.
- Core → Binned MI: implements · Core package includes binned MI routines.
- Estimators → Bin est: includes · Estimator layer exposes binned estimator objects.
- Estimators → GCMI est: includes · Estimator layer exposes GCMI estimator objects.
- Estimators → Corr est: includes · Estimator layer exposes correlation estimators.
- Connectivity → Conn ops: uses · Connectivity subsystem centers on analysis methods and utilities.
- Connectivity → Spec/TF: uses · Connectivity subsystem includes spectral and time-frequency paths.
- Workflow → Dataset: ingests · Workflows begin from standardized dataset abstractions.
- Workflow → Estimators: configures · Workflows select estimators for the target measure.
- Workflow → Connectivity: runs · Workflows can execute connectivity analyses end to end.
- Workflow → Stats: summarizes · Workflows hand results to statistical inference.
- Stats → Connectivity: analyzes · Statistics consume connectivity outputs for inference.
- Stats → Workflow: returns · Statistics feed group-level workflow outputs.
- Simulations → Dataset: feeds · Synthetic data supports dataset and pipeline validation.
- Simulations → Core: validates · Simulations exercise numerical kernels and estimators.
- Plotting → Connectivity: visualizes · Plotting focuses on connectivity results.
- Utils → Workflow: supports · Utilities provide preprocessing, parallelism, and performance helpers.
- IO → Utils: supports · IO support underpins utilities and runtime checks.
- Docs → Dataset: documents · Docs mirror the dataset subsystem.
- Docs → Connectivity: documents · Docs mirror the connectivity subsystem.
- Docs → Workflow: documents · Docs explain workflow usage and orchestration.
- Examples → Simulations: demonstrates · Examples include synthetic-data scenarios.
- Examples → Workflow: demonstrates · Examples show end-to-end workflow usage.
- Examples → Connectivity: demonstrates · Examples cover connectivity methods and variants.