---
myst:
  html_meta:
    description: "Understand GWexpy architecture, container design, data flow, field and matrix API roles, and where to continue into theory or reference pages."
---

# Architecture and Data Flow

This section details the design philosophy of `gwexpy` and the internal data handling logic.
`gwexpy` extends GWpy to provide intuitive multi-channel time-series matrix operations and 4D physical field handling.

(architecture-how-to-read)=
## How to Read This Page

- Read this page first if you want the mental model behind `gwexpy` container design and internal reshaping.
- For the mathematical foundations of each algorithm, continue to [Physics Models and Analysis Theory](physics_models.md).
- For concrete callable surfaces, follow the API entry links in each section to the [matrix API](../reference/api/matrix), [fields API](../reference/api/fields), and [fitting API](../reference/api/fitting).

(architecture-design-philosophy)=
## Design Philosophy

### 1. Matrix Object Flattening Flow
**Goal:** Explain how matrix-like containers are reshaped for analysis while preserving metadata.
**Input:** Multi-channel or matrix-like series data such as `TimeSeriesMatrix` and `FrequencySeriesMatrix`.
**Output:** A 2D feature representation for computation, with metadata restored on the way back.

Classes like `TimeSeriesMatrix` and `FrequencySeriesMatrix` handle automatic conversion to formats compatible with machine learning libraries like scikit-learn.
Typically, 3D data (Channels/Rows $\times$ Columns $\times$ Samples) is temporarily flattened into a 2D feature matrix for computation, while metadata (GPS timestamps, units) is preserved and restored after processing.

API entry: [matrix API](../reference/api/matrix), [timeseries API](../reference/api/timeseries)

### 2. 4D Field API Model
**Goal:** Explain why field containers keep all axes aligned during slicing and indexing.
**Input:** A `ScalarField` with one time (or frequency) axis and three spatial axes.
**Output:** A field object whose grid and axis metadata remain synchronized after selection operations.

`ScalarField` adopts a 4D structure as its base unit: axis 0 is the **time axis** (or the **frequency axis** after `fft_time()`), and axes 1–3 are the **spatial axes** `x, y, z` (mapped to wavenumbers `kx, ky, kz` by `fft_space()`) — for example `(t, x, y, z)`, `(f, x, y, z)`, or `(f, kx, ky, kz)`.
By maintaining all 4 dimensions during indexing operations, the Field APIs are designed to preserve grid information and axis metadata with the data.

API entry: [fields API](../reference/api/fields), [Scalar Field Slicing Guide](../how-to/containers/scalarfield_slicing.md)

(data-flow-diagram)=
## Data Flow Diagram

The static diagram below summarizes how the main GWexpy containers move from raw inputs to analysis APIs while keeping axis metadata available in the current docs build.

```{figure} /_static/images/phase3/architecture_data_flow.svg
:alt: Static data-flow diagram for GWexpy containers and metadata preservation.
:width: 100%

GWexpy data flow from raw arrays and GWpy objects through matrix and field analysis paths, with axis metadata preserved across reshaping and transforms.
```

Reading notes:

- `TimeSeriesDict -> TimeSeriesMatrix -> Flatten to 2D features` is the matrix-analysis path used when scikit-learn-style algorithms expect 2D inputs.
- `ScalarField -> Field slicing / indexing -> Field-aware transforms` is the field-analysis path used when the time/frequency axis and the spatial axes must stay aligned.
- Metadata is preserved across both paths so derived outputs can still be interpreted in physical coordinates rather than raw array indices alone.

---

(architecture-core-analysis-components)=
## Core Analysis Components

`gwexpy` builds advanced analysis pipelines by combining the following core components. For detailed mathematical and physical foundations, refer to [Physics Models and Analysis Theory](physics_models.md).

- **Multi-channel Analysis Engine**: Implementation of ICA/PCA for environmental noise isolation.
- **Fast Correlation Framework**: Accelerated coherence calculations (Bruco) for large-scale observation data.
- **Statistical Inference & Fitting**: Parameter estimation using GLS and MCMC.

(related-documents)=
## Related Documents

- [Physics Models and Analysis Theory](physics_models.md) — Mathematical context for the containers and transforms summarized here
- [Validated Algorithms](validated_algorithms.md) — Audit-backed behavior for numerical paths referenced by this design guide
- [Scalar Field Slicing Guide](../how-to/containers/scalarfield_slicing.md) — Why the Field API preserves 4D structure
- [Prerequisites and Conventions](prerequisites_and_conventions.md) — Shared time, FFT, and compatibility assumptions
- [Matrix API](../reference/api/matrix) — Reference entry for container reshaping and matrix-style operations
- [Fields API](../reference/api/fields) — Reference entry for field-aware transforms and slicing

(next-to-read)=
## Next to Read
- [Physics Models and Analysis Theory](physics_models.md) — Detailed analysis theory and physics models (ICA/Bruco/MCMC)
- [Validated Algorithms](validated_algorithms.md) — Validation reports for numerical algorithms
- [Scalar Field Slicing Guide](../how-to/containers/scalarfield_slicing.md) — Details on 4D field operations
- [Prerequisites and Conventions](prerequisites_and_conventions.md) — Shared FFT, GPS time, and compatibility assumptions