# brainets/frites architecture

> Architecture diagram of the GitHub repository brainets/frites, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brainets/frites
- Repository: https://github.com/brainets/frites

## Overview

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: [`frites/workflow`](https://github.com/brainets/frites/tree/master/frites/workflow) (Workflow), [`frites/conn`](https://github.com/brainets/frites/tree/master/frites/conn) (Connectivity), [`frites/dataset`](https://github.com/brainets/frites/tree/master/frites/dataset) (Dataset), [`frites/core`](https://github.com/brainets/frites/tree/master/frites/core) (Core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_core["Core math"]
  node_node_core{{"Core<br/>numeric kernels"}}
  node_node_copnorm["Copnorm<br/>transform<br/>[copnorm.py]"]
  node_node_gcmi["GCMI<br/>mi kernel<br/>[gcmi_nd.py]"]
  node_node_mi_bin["Binned MI<br/>mi kernel<br/>[mi_bin_ephy.py]"]
end

subgraph group_group_data["Data layer"]
  node_node_dataset["Dataset<br/>data normalization"]
  node_node_ds_ephy["Ephy DS<br/>dataset API<br/>[ds_ephy.py]"]
  node_node_suj_ephy["Subject DS<br/>dataset API<br/>[suj_ephy.py]"]
end

subgraph group_group_conn["Connectivity"]
  node_node_conn["Connectivity<br/>analysis subsystem"]
  node_node_conn_core["Conn ops<br/>connectivity methods<br/>[conn_utils.py]"]
  node_node_conn_spec["Spec/TF<br/>connectivity methods<br/>[conn_spec.py]"]
end

subgraph group_group_analysis["Analysis layer"]
  node_node_estimator["Estimators<br/>metric objects"]
  node_node_est_bin["Bin est<br/>estimator<br/>[est_bin.py]"]
  node_node_est_gcmi["GCMI est<br/>estimator<br/>[est_gcmi.py]"]
  node_node_est_corr["Corr est<br/>estimator<br/>[est_corr.py]"]
  node_node_workflow["Workflow<br/>orchestration"]
  node_node_stats["Stats<br/>inference"]
  node_node_sim["Simulations<br/>synthetic data"]
  node_node_plot["Plotting<br/>visualization"]
  node_node_utils["Utils<br/>support tools"]
  node_node_io["IO<br/>metadata/support"]
end

subgraph group_group_docs["Docs & examples"]
  node_node_docs["Docs<br/>documentation"]
  node_node_examples["Examples<br/>usage demos"]
end

node_node_dataset -->|"contains"| node_node_ds_ephy
node_node_dataset -->|"contains"| node_node_suj_ephy
node_node_core -->|"implements"| node_node_copnorm
node_node_core -->|"implements"| node_node_gcmi
node_node_core -->|"implements"| node_node_mi_bin
node_node_estimator -->|"includes"| node_node_est_bin
node_node_estimator -->|"includes"| node_node_est_gcmi
node_node_estimator -->|"includes"| node_node_est_corr
node_node_conn -->|"uses"| node_node_conn_core
node_node_conn -->|"uses"| node_node_conn_spec
node_node_workflow -->|"ingests"| node_node_dataset
node_node_workflow -->|"configures"| node_node_estimator
node_node_workflow -->|"runs"| node_node_conn
node_node_workflow -->|"summarizes"| node_node_stats
node_node_stats -->|"analyzes"| node_node_conn
node_node_stats -->|"returns"| node_node_workflow
node_node_sim -->|"feeds"| node_node_dataset
node_node_sim -->|"validates"| node_node_core
node_node_plot -->|"visualizes"| node_node_conn
node_node_utils -->|"supports"| node_node_workflow
node_node_io -->|"supports"| node_node_utils
node_node_docs -->|"documents"| node_node_dataset
node_node_docs -->|"documents"| node_node_conn
node_node_docs -->|"documents"| node_node_workflow
node_node_examples -->|"demonstrates"| node_node_sim
node_node_examples -->|"demonstrates"| node_node_workflow
node_node_examples -->|"demonstrates"| node_node_conn

click node_node_dataset "https://github.com/brainets/frites/tree/master/frites/dataset"
click node_node_ds_ephy "https://github.com/brainets/frites/blob/master/frites/dataset/ds_ephy.py"
click node_node_suj_ephy "https://github.com/brainets/frites/blob/master/frites/dataset/suj_ephy.py"
click node_node_core "https://github.com/brainets/frites/tree/master/frites/core"
click node_node_copnorm "https://github.com/brainets/frites/blob/master/frites/core/copnorm.py"
click node_node_gcmi "https://github.com/brainets/frites/blob/master/frites/core/gcmi_nd.py"
click node_node_mi_bin "https://github.com/brainets/frites/blob/master/frites/core/mi_bin_ephy.py"
click node_node_estimator "https://github.com/brainets/frites/tree/master/frites/estimator"
click node_node_est_bin "https://github.com/brainets/frites/blob/master/frites/estimator/est_bin.py"
click node_node_est_gcmi "https://github.com/brainets/frites/blob/master/frites/estimator/est_gcmi.py"
click node_node_est_corr "https://github.com/brainets/frites/blob/master/frites/estimator/est_corr.py"
click node_node_conn "https://github.com/brainets/frites/tree/master/frites/conn"
click node_node_conn_core "https://github.com/brainets/frites/blob/master/frites/conn/conn_utils.py"
click node_node_conn_spec "https://github.com/brainets/frites/blob/master/frites/conn/conn_spec.py"
click node_node_workflow "https://github.com/brainets/frites/tree/master/frites/workflow"
click node_node_stats "https://github.com/brainets/frites/tree/master/frites/stats"
click node_node_sim "https://github.com/brainets/frites/tree/master/frites/simulations"
click node_node_plot "https://github.com/brainets/frites/tree/master/frites/plot"
click node_node_utils "https://github.com/brainets/frites/tree/master/frites/utils"
click node_node_io "https://github.com/brainets/frites/tree/master/frites/io"
click node_node_docs "https://github.com/brainets/frites/tree/master/docs/source"
click node_node_examples "https://github.com/brainets/frites/tree/master/examples"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_core,node_node_copnorm,node_node_gcmi,node_node_mi_bin toneBlue
class node_node_dataset,node_node_ds_ephy,node_node_suj_ephy toneAmber
class node_node_conn,node_node_conn_core,node_node_conn_spec toneMint
class node_node_estimator,node_node_est_bin,node_node_est_gcmi,node_node_est_corr,node_node_workflow,node_node_stats,node_node_sim,node_node_plot,node_node_utils,node_node_io toneRose
class node_node_docs,node_node_examples toneIndigo
```

## Components

### Core math

Low-level information-theoretic kernels and estimators.

- [Core](https://github.com/brainets/frites/tree/master/frites/core): numeric kernels · Low-level information-theoretic primitives used by estimators and workflows. · `frites/core`
- [Copnorm](https://github.com/brainets/frites/blob/master/frites/core/copnorm.py): transform · Copula normalization and related preprocessing transforms. · `frites/core/copnorm.py`
- [GCMI](https://github.com/brainets/frites/blob/master/frites/core/gcmi_nd.py): mi kernel · Gaussian-copula mutual information implementations. · `frites/core/gcmi_nd.py`
- [Binned MI](https://github.com/brainets/frites/blob/master/frites/core/mi_bin_ephy.py): mi kernel · Bin-based mutual-information routines for electrophysiology. · `frites/core/mi_bin_ephy.py`

### Data layer

Dataset normalization and subject-level abstractions.

- [Dataset](https://github.com/brainets/frites/tree/master/frites/dataset): data normalization · Normalizes neurophysiology inputs into analysis-ready dataset abstractions. · `frites/dataset`
- [Ephy DS](https://github.com/brainets/frites/blob/master/frites/dataset/ds_ephy.py): dataset API · Electrophysiology dataset construction and harmonization. · `frites/dataset/ds_ephy.py`
- [Subject DS](https://github.com/brainets/frites/blob/master/frites/dataset/suj_ephy.py): dataset API · Single-subject electrophysiology representation and helpers. · `frites/dataset/suj_ephy.py`

### Connectivity

Pairwise, directed, and time-frequency connectivity methods.

- [Connectivity](https://github.com/brainets/frites/tree/master/frites/conn): analysis subsystem · Connectivity analyses spanning undirected, directed, and time-frequency methods. · `frites/conn`
- [Conn ops](https://github.com/brainets/frites/blob/master/frites/conn/conn_utils.py): connectivity methods · Cross-correlation, covariance GC, instantaneous interaction, PID, TE, and related computations. · `frites/conn/conn_utils.py`
- [Spec/TF](https://github.com/brainets/frites/blob/master/frites/conn/conn_spec.py): connectivity methods · Spectral, sliding-window, and time-frequency connectivity routines. · `frites/conn/conn_spec.py`

### Analysis layer

Workflows, statistics, simulations, plotting, and support utilities.

- [Estimators](https://github.com/brainets/frites/tree/master/frites/estimator): metric objects · Reusable estimator objects that define what measure to compute. · `frites/estimator`
- [Bin est](https://github.com/brainets/frites/blob/master/frites/estimator/est_bin.py): estimator · Binned estimator interface. · `frites/estimator/est_bin.py`
- [GCMI est](https://github.com/brainets/frites/blob/master/frites/estimator/est_gcmi.py): estimator · Gaussian-copula mutual-information estimator interface. · `frites/estimator/est_gcmi.py`
- [Corr est](https://github.com/brainets/frites/blob/master/frites/estimator/est_corr.py): estimator · Correlation-based estimator family. · `frites/estimator/est_corr.py`
- [Workflow](https://github.com/brainets/frites/tree/master/frites/workflow): orchestration · End-to-end pipelines combining datasets, estimators, connectivity, and statistics. · `frites/workflow`
- [Stats](https://github.com/brainets/frites/tree/master/frites/stats): inference · Parametric, nonparametric, and multiple-comparison inference utilities. · `frites/stats`
- [Simulations](https://github.com/brainets/frites/tree/master/frites/simulations): synthetic data · Generates artificial data for validation, benchmarking, and examples. · `frites/simulations`
- [Plotting](https://github.com/brainets/frites/tree/master/frites/plot): visualization · Plot helpers for connectivity and result summaries. · `frites/plot`
- [Utils](https://github.com/brainets/frites/tree/master/frites/utils): support tools · Parallelism, preprocessing, performance, and wrapper helpers. · `frites/utils`
- [IO](https://github.com/brainets/frites/tree/master/frites/io): metadata/support · Dependency checks, attributes, and system logging support. · `frites/io`

### Docs & examples

Documentation and usage demonstrations mirroring the package layout.

- [Docs](https://github.com/brainets/frites/tree/master/docs/source): documentation · API reference and conceptual documentation for each subsystem. · `docs/source`
- [Examples](https://github.com/brainets/frites/tree/master/examples): usage demos · Scenario-driven demonstrations of datasets, MI, connectivity, statistics, and simulations. · `examples`

## Connections

- 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.
