Interop / Conversion Guide

Page Role: Guide

This page is the dedicated interop guide for gwexpy.
Here, interop means conversion and bridging centered on to_*() / from_*() APIs.

This page covers:

• object conversion via to_*() / from_*()

• bridges to external libraries and external data models

• object-level file-bridge helpers

• asymmetric conversion APIs

• conversions that apply only to some classes

This page does not cover:

• Class.read(..., format=...)

• obj.write(..., format=...)

• the choice of local file formats themselves

For local file formats and direct .read() / .write() / fetch() paths, see the File I/O Supported Formats Guide.

Direct I/O Names

These are the canonical direct-I/O format names used by gwexpy. Legacy aliases remain supported during the transition, but new examples should prefer the canonical spellings below.

Canonical name	Legacy aliases	Typical direct-I/O entry points	External package / schema
mseed	miniseed	TimeSeriesDict.read(..., format="mseed"), .write(..., format="mseed")	ObsPy
nc	netcdf4	TimeSeries.read(..., format="nc"), TimeSeriesDict.read(..., format="nc"), TimeSeriesMatrix.read(..., format="nc")	netCDF4, xarray
hdf.ndscope	ndscope-hdf5, ndscope_hdf5, ndscopehdf5	TimeSeriesDict.read(..., format="hdf.ndscope"), .write(..., format="hdf.ndscope")	ndscope HDF5 schema
xml.diaggui	dttxml	TimeSeriesDict.read(..., format="xml.diaggui", products="...")	DiagGUI / DTT XML

At a Glance

Item	Details
Audience	Users and contributors who need to move gwexpy objects into other libraries, containers, or storage representations
Prerequisites	Basic familiarity with gwexpy object types, direct I/O versus interop, and the target library or container you want to use
Use Cases	Choose a to_*() / from_*() path, check whether a bridge is public yet, and distinguish storage conversion from object conversion
Search Keywords	interop, conversion, to_*, from_*, xarray, pandas, ROOT, Zarr, NetCDF4, PyTorch

Search hints: interop, conversion, to_*, from_*, xarray, pandas, ROOT, Zarr, NetCDF4, PyTorch

Jump Links

• How to Read This Page

• Status Labels

• A. Storage Formats and Container Conversion

• B. Analysis Library and Object Conversion

• C. Machine Learning, Acceleration, and Array Backends

• D. Physics and Domain-Specific Libraries

• What to Prioritize First

How to Read This Page

• If you want to convert a live object to a storage format or container, start with A.

• If you want to convert to analysis objects such as pandas, xarray, astropy, or dask, start with B.

• If you want to hand data to PyTorch, TensorFlow, JAX, or CuPy, start with C.

• If you want to connect to ROOT, ObsPy, LAL, PyCBC, or other domain-specific libraries, start with D.

• If you want to move Field objects into xarray, NetCDF4, or Zarr workflows via to_*() / from_*(), treat that as interop, not as direct I/O.

Status Labels

• Public: implemented and reachable from reference/api/interop

• Implemented: implemented, but the page still needs concrete navigation or reference polish

• Implemented, some paths still in progress: the main route works, but some conversion paths are still incomplete

• In progress: the implementation or the public presentation is not finished yet

• Planned: explicitly in scope, but not implemented yet

Optional Dependency Policy

Interop bridges import optional runtime backends lazily. If a runtime backend is missing, the bridge raises ImportError with installation guidance instead of importing the backend at import gwexpy time.

Some import-only adapters consume objects or dictionaries that were produced by external packages, but do not import those producer packages themselves. For example, from_pyoma_results(), from_mtspec(), from_mtspec_array(), from_uff_dataset55(), from_uff_dataset58(), the from_sdynpy_*(), from_metpy_dataarray(), from_wrf_variable(), and from_harmonica_grid() helpers accept caller-supplied pyOMA, multitaper, mtspec, pyuff, SDynPy-style, MetPy-enhanced, wrf-python, or Harmonica objects. Install those packages when you need to create the source objects, not because the adapter imports them directly.

Policy	Dependencies	Install guidance
Declared GWexpy extras	zarr, netCDF4, xarray, obspy, mth5, lalsuite, gwinc, control, pydub	Until PyPI publication, use the source-install extra syntax from the Installation Guide, such as pip install "gwexpy[control] @ git+https://github.com/tatsuki-washimi/gwexpy.git".
Bare package installs	ROOT, polars, dask, torch, tensorflow, jax, cupy, pycbc, finesse, simpeg, mne, neo, quantities, pyroomacoustics, specutils, pyspeckit, PySpice, skrf, pyOMA, multitaper, mtspec, pyuff, sdynpy, metpy, wrf-python, harmonica, emg3d, meshio	Install the named backend directly when the bridge imports it or when you need it to create accepted source objects.

gwexpy[all] installs the declared GWexpy extras as a convenience bundle. It does not install every public interop backend; entries in the bare package row still require direct backend installs when the bridge imports the backend or when you need to create accepted source objects.

The xarray-backed interop bridges list the netcdf4 extra because GWexpy does not currently publish a standalone xarray extra. If you only need in-memory xarray conversion and want to avoid installing netCDF4, install xarray directly.

A. Storage Formats and Container Conversion

This section is for conversions where the target is a file format, container, or storage representation.
Use it when the question is “what storage representation do I bridge to?”

• Purpose: identify object-level bridges whose target is a storage representation

• Input: a gwexpy object plus a destination container or storage backend

• Output: a converted object, container, or storage-facing representation via to_*() / from_*()

Target	API / Entry	Status	Notes	Details
HDF5	to_hdf5(), from_hdf5()	Public	object-level conversion	API
HDF5 FrequencySeries	to_hdf5_frequencyseries(), from_hdf5_frequencyseries()	Public	FrequencySeries HDF5 helpers	API
JSON	to_json(), from_json()	Public	JSON string conversion	API
Python dict	to_dict(), from_dict()	Public	dict conversion	—
SQLite	to_sqlite(), from_sqlite()	Public	object-level bridge	API
Zarr	to_zarr(), from_zarr()	Public	array/store bridge	API
NetCDF4	to_netcdf4(), from_netcdf4()	Public	object-level bridge	API

B. Analysis Library and Object Conversion

This section is for conversions where the target is a Python object model rather than a storage format.
Use it when the question is “which analysis-library object do I bridge to?”

• Purpose: pick the correct bridge into analysis-oriented Python objects

• Input: a gwexpy object or an external analysis object such as pandas, xarray, or astropy

• Output: an analysis-library object or a reconstructed gwexpy object

Target	API / Entry	Status	Notes	Details
NumPy	no dedicated to_*() / from_*() API	Implemented as infrastructure	widely used as the internal array basis	—
pandas	to_pandas_series(), from_pandas_series(), to_pandas_dataframe(), from_pandas_dataframe()	Public	Series / DataFrame	API
pandas FrequencySeries	to_pandas_frequencyseries(), from_pandas_frequencyseries()	Public	FrequencySeries ⇔ pandas.Series	API
polars	to_polars_series(), from_polars_series(), to_polars_dataframe(), from_polars_dataframe(), to_polars_frequencyseries(), to_polars_dict(), from_polars_dict()	Public	Series / DataFrame / dict / FrequencySeries	API
xarray	to_xarray(), from_xarray()	Public	DataArray / Dataset	API
xarray Field	to_xarray_field(), from_xarray_field()	Public	ScalarField / VectorField	API
xarray FrequencySeries	to_xarray_frequencyseries(), from_xarray_frequencyseries()	Public	FrequencySeries ⇔ xarray.DataArray	API
astropy	to_astropy_timeseries(), from_astropy_timeseries()	Public	astropy.timeseries.TimeSeries	API
dask	to_dask(), from_dask()	Public	dask array bridge	API

C. Machine Learning, Acceleration, and Array Backends

This section is for accelerated computing and ML-oriented bridges.
Check whether only the array payload moves, or whether metadata can also be reconstructed.

• Purpose: decide whether an ML or accelerated-array bridge matches your workflow

• Input: a gwexpy object and an ML / GPU / array backend target

• Output: tensors or accelerated arrays, and in some cases a route back into gwexpy

Target	API / Entry	Status	Notes	Details
PyTorch	to_torch(), from_torch()	Public	tensor conversion	API
PyTorch Dataset	TimeSeriesWindowDataset, to_torch_dataset(), to_torch_dataloader()	Public	windowed dataset for training	API
TensorFlow	to_tf(), from_tf()	Public	tensor conversion	API
JAX	to_jax(), from_jax()	Public	JAX array conversion	API
CuPy	to_cupy(), from_cupy(), is_cupy_available()	Public	GPU array conversion	API

D. Physics and Domain-Specific Libraries

This section is for domain-specific libraries and specialized objects.
Read the status carefully: some targets are full round-trips, some are mainly import paths, and some are still being organized publicly.

• Purpose: find bridges into domain-specific tools without confusing them with direct file I/O

• Input: a gwexpy object or a domain-library object such as ObsPy, ROOT, LAL, or PyCBC

• Output: a target-library object, imported data, or a partial round-trip depending on status

Target	API / Entry	Status	Notes	Details
ROOT	to_tgraph(), to_th1d(), to_th2d(), to_tmultigraph(), from_root(), write_root_file()	Implemented, some paths still in progress	TH1 -> non-Histogram is incomplete	API
ObsPy	to_obspy(), from_obspy(), to_obspy_trace(), from_obspy_trace()	Public	seismic bridge	API
LALSuite	to_lal_timeseries(), from_lal_timeseries(), to_lal_frequencyseries(), from_lal_frequencyseries()	Public	GW time / frequency series	API
PyCBC	to_pycbc_timeseries(), from_pycbc_timeseries(), to_pycbc_frequencyseries(), from_pycbc_frequencyseries()	Public	GW time / frequency series	API
GWINC	from_gwinc_budget()	Public	budget import	API
Finesse	from_finesse_frequency_response(), from_finesse_noise()	Public	optics / response	API
python-control	to_control_frd(), from_control_frd(), from_control_response()	Public	FRD / response. Requires the control extra, for example pip install "gwexpy[control] @ git+https://github.com/tatsuki-washimi/gwexpy.git" until PyPI publication. FRD conversion is available from FrequencySeries / FrequencySeriesDict; time-response import is available via TimeSeries.from_control() / TimeSeriesDict.from_control().	API
SimPEG	to_simpeg(), from_simpeg()	Public	geophysics	API
MTH5	to_mth5(), from_mth5()	Public	magnetotellurics	API
MTpy	dedicated to_*() / from_*() API still in progress	In progress	MTH5-adjacent organization is incomplete	—
MNE-Python	to_mne(), from_mne(), to_mne_rawarray(), from_mne_raw()	Public	EEG / biosignal	API
Neo	to_neo(), from_neo()	Public	electrophysiology	API
Elephant	dedicated to_*() / from_*() API still in progress	In progress	organization with Neo and quantities is incomplete	—
quantities	to_quantity(), from_quantity()	Public	quantity bridge	API
pyroomacoustics	to_pyroomacoustics_source(), to_pyroomacoustics_stft(), from_pyroomacoustics_rir(), from_pyroomacoustics_mic_signals(), from_pyroomacoustics_source(), from_pyroomacoustics_stft(), from_pyroomacoustics_field()	Public	room acoustics	API
pydub	to_pydub(), from_pydub()	Public	audio object bridge	API
librosa	to_librosa()	Public	mainly export	API
specutils	to_specutils(), from_specutils()	Public	astronomy spectra	API
pyspeckit	to_pyspeckit(), from_pyspeckit()	Public	spectral analysis	API
PySpice	from_pyspice_transient(), from_pyspice_ac(), from_pyspice_noise(), from_pyspice_distortion()	Public	mainly import	API
scikit-rf	to_skrf_network(), from_skrf_network(), from_skrf_impulse_response(), from_skrf_step_response()	Public	RF network analysis	API
pyOMA	from_pyoma_results()	Public	mainly import	API
multitaper	from_mtspec()	Public	mainly import	API
mtspec	from_mtspec_array()	Public	mainly import	API
pySDy	from_uff_dataset55(), from_uff_dataset58()	Public	mainly import	API
SDynPy	from_sdynpy_frf(), from_sdynpy_shape(), from_sdynpy_timehistory()	Public	mainly import	API
Meep	from_meep_hdf5()	Public	mainly import	API
openEMS	from_openems_hdf5(), DUMP_TYPE_MAP	Public	mainly import	API
emg3d	to_emg3d_field(), from_emg3d_field(), from_emg3d_h5()	Public	EM field import/export	API
meshio	from_meshio(), from_fenics_xdmf(), from_fenics_vtk()	Public	mainly import	API
MetPy	from_metpy_dataarray()	Public	mainly import	API
WRF	from_wrf_variable()	Public	mainly import	API
Harmonica	from_harmonica_grid()	Public	mainly import	API
Exudyn	from_exudyn_sensor()	Public	mainly import	API
OpenSees	from_opensees_recorder()	Public	mainly import	API

What to Prioritize First

The following targets are especially important because they sit close to the direct-I/O boundary or because they are high-value public entry points:

• ROOT: io_formats keeps only EventTable direct I/O; ROOT object conversion belongs here

• xarray / Field: the main route for ScalarField / VectorField bridges

• Zarr: easy to confuse with direct I/O, so the boundary matters

• NetCDF4: needs a clean line between direct I/O and xarray-backed workflows

• ObsPy: common and easy-to-understand round-trip examples

• pandas / polars / astropy: frequent analysis entry points

Related Pages

• Interop tutorial

• Interop API reference

• File I/O Supported Formats Guide

Next to Read

• File I/O Supported Formats Guide if your real question is about Class.read(..., format=...) or obj.write(...)

• GPS Time Utility Functions if conversion workflows depend on GPS or timezone handling

• Interop tutorial for worked examples before dropping into the API reference