Development documentation · 0.2.7 12b76261 · Intro examples tested with 0.2.4 · Version details · Known limitations

Installation Guide#

Note

GWexpy 0.2.6 is available on PyPI, the GitHub releases page, and conda-forge. The latest conda-forge package is v0.2.6. The v0.2.6 source is archived on Zenodo. Check each install source for its available versions.

GWexpy supports Python 3.11 or later. You can choose from several installation options (extras) depending on your analysis goals.

Tip

Not sure which one to pick? If your goal is gravitational-wave analysis (NDS2, frame files, GW-specific tools), skip straight to Conda Environment (Recommended / GW Analysis) — this creates a dedicated environment with GW-related binary dependencies and the gw, analysis, and fitting extras. Only use Minimal if you specifically want to keep dependencies to a bare minimum, and only use Developer Mode if you are editing GWexpy itself.

Install Commands#

This table summarizes the commands; the sections below (Minimal, Conda Environment (Recommended / GW Analysis), Developer Mode) give the full steps for each.

Goal	Installation Command	Features
Minimal	`pip install gwexpy`	Numerical containers and basic arithmetic. Minimal dependencies.
Recommended	`pip install "gwexpy[analysis,fitting,plotting]"`	Advanced statistics, curve fitting, and mapping features.
GW Analysis	`pip install "gwexpy[gw,io]"`	Frame file support and official GW tools (NDS2 requires the Conda step below).
Developer / Full	`pip install -e ".[dev,all]"`	Editable install from source with all declared non-GUI optional features, for contributors.

1. Installation Steps#

Minimal#

For users who want to keep dependencies minimal and only use core containers like ScalarField.

Purpose: verify import and core container usage with the smallest dependency set
Input: Python 3.11+ and pip
Output: a minimal GWexpy environment

If you need NDS2, FrameLIB, pygmt, or other binary-heavy tools, skip this section and start with Conda Environment (Recommended / GW Analysis).

pip install gwexpy

Conda Environment (Recommended / GW Analysis)#

For gravitational-wave analysis (requiring NDS2 or FrameLIB), we strongly recommend using Conda (e.g., Miniforge) to resolve binary dependencies first.

This workflow uses Conda for the environment and binary dependencies. Install GWexpy from conda-forge with conda install -c conda-forge gwexpy, or use PyPI extras after Conda has resolved the binary dependencies you need.

Warning

If you use Conda, avoid running pip install directly in base or in a shared environment for unrelated work. Create a dedicated environment for GWexpy first, then install both the Conda-managed binary dependencies and the pip packages there. This keeps binary dependency resolution isolated and reduces the risk of breaking the environment.

Purpose: build a GW-ready environment with binary dependencies such as NDS2 and FrameLIB
Input: a shell with Conda available
Output: a dedicated gwexpy environment with gw extras enabled

# 1. Create environment and resolve binary dependencies
conda create -n gwexpy python=3.11
conda activate gwexpy
conda install -c conda-forge python-nds2-client python-framel ldas-tools-framecpp

# 2. Install GWexpy with analysis/fitting options
pip install "gwexpy[gw,analysis,fitting]"

If you see No module named nds2 or FrameLIB-related import errors, re-run the conda install -c conda-forge ... step inside that dedicated environment first. If you do not need NDS2 or FrameLIB, the minimal or recommended installation without the gw extras is usually sufficient.

Developer Mode#

For contributors who want to install from source and set up a testing environment. Conda is optional here. Use the Conda workflow above when you need to validate gw-related binary dependencies; otherwise, a standard virtual environment such as venv is fine for documentation work and general development.

Purpose: install from a local clone for editing and tests
Input: Git plus a Python virtual environment
Output: an editable install via pip install -e

git clone https://github.com/tatsuki-washimi/gwexpy.git
cd gwexpy
pip install -e ".[dev,all]"

Use the developer mode only when you need to edit GWexpy itself or test unreleased changes from the repository. For normal use, prefer the PyPI commands above.

2. Dependency Troubleshooting#

For No module named nds2, FrameLIB / framecpp import errors, and mixed-environment repairs, see the Troubleshooting guide — it covers these cases in more depth.

If you installed from Quickstart and later discover you need GW binary dependencies, return to Conda Environment (Recommended / GW Analysis) before adding more packages.

3. Optional Dependencies (Extras) Details#

Extra Name	Key Packages	Primary Use Cases
`analysis`	`scikit-learn`, `statsmodels`, `pmdarima`	Noise cancellation, forecasting, and machine learning.
`fitting`	`iminuit`, `emcee`, `corner`	Least-squares fitting and MCMC analysis.
`gw`	`lalsuite`, `gwosc`, `gwinc`, `ligo.skymap`	Data discovery, sensitivity calculations, and sky mapping.
`io`	`nptdms`	Reading LabVIEW TDMS formats.
`netcdf4`	`netCDF4`, `xarray`	Reading and writing NetCDF4 time-series files via xarray.
`zarr`	`zarr`	Reading and writing Zarr array stores.
`plotting`	`pygmt`	High-precision geographic mapping (GeoMap).
`audio`	`pydub`, `tinytag`	Audio export, processing, and optional metadata extraction.
`seismic`	`obspy`, `mth5`, `mtpy`	Seismic and magnetotelluric data.
`control`	`control` (python-control)	Control systems and transfer functions.

4. OS-Specific Notes#

Linux: Ensure standard build tools (build-essential) are installed.
macOS (Apple Silicon): Using the conda-forge channel ensures most binaries run natively on M1/M2/M3.
Windows (WSL2): We recommend installing GWexpy within a Linux environment on WSL2 rather than on Windows proper.

5. Security Note (Pickle)#

To facilitate sharing analysis results, GWexpy supports saving and restoring objects via Pickle. This uses Transparent Pickle technology, allowing objects to be restored as base GWpy objects even if the recipient does not have GWexpy installed.

Caution

Never load Pickle files from untrusted sources. Python’s pickle module has inherent security risks (Arbitrary Code Execution) when loading data. Always exchange data through trusted channels or consider more secure serialization formats like HDF5.

6. Next to Read#

Installed successfully? Continue to Quickstart to confirm import and plotting with the smallest possible example — that is the single next step for most readers.

Quickstart - confirm import and plotting with the smallest possible example
Troubleshooting - reverse-lookup common install, plotting, and binary dependency issues
Getting Started - choose the right learning path after installation
Prerequisites and Conventions - review FFT, GPS time, and GWpy-compatibility assumptions