Development documentation · 0.2.3 30c2f8ba · Intro examples tested with 0.2.3 · Version details · Known limitations

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.

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.

  • For concrete callable surfaces, follow the API entry links in each section to the matrix API, fields API, and fitting API.

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, timeseries API

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, Scalar Field Slicing Guide

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.

Static data-flow diagram for GWexpy containers and metadata preservation.

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.

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.

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

Next to Read#