### Quick start example using wavespectra

Source: https://wavespectra.readthedocs.io/en/v4.9.0/index.html

Shows the basic workflow: open a spectra file with the ww3 engine, compute significant wave height, partition the spectrum, and plot a contourf. Requires xarray and wavespectra installed.

```python
import xarray as xr
import wavespectra

dset = xr.open_dataset("spectra.nc", engine="ww3")
hs = dset.spec.hs()
dspart = dset.spec.partition.ptm1(dset.wspd, dset.wdir, dset.dpt)
dset.isel(time=0, site=0).spec.plot(kind="contourf")

```

--------------------------------

### Install wavespectra from source with extra dependencies

Source: https://wavespectra.readthedocs.io/en/v4.9.0/install.html

Install from source including the [extra] tag for full install.

```bash
$ pip install './[extra]'

```

--------------------------------

### Install docs dependencies

Source: https://wavespectra.readthedocs.io/en/v4.9.0/install.html

Install the dependencies required to build the documentation.

```bash
$ pip install '.[docs]'

```

--------------------------------

### Install wavespectra with pip

Source: https://wavespectra.readthedocs.io/en/v4.9.0/install.html

Basic installation of the latest stable release using pip.

```bash
$ pip install wavespectra

```

--------------------------------

### Install wavespectra from source

Source: https://wavespectra.readthedocs.io/en/v4.9.0/install.html

Install the package from the source directory. Assumes you are in the root directory containing pyproject.toml.

```bash
$ pip install .

```

--------------------------------

### Install wavespectra in development mode with extra dependencies

Source: https://wavespectra.readthedocs.io/en/v4.9.0/install.html

Development install including extra dependencies.

```bash
$ pip install -e '.[extra]'

```

--------------------------------

### Install test dependencies

Source: https://wavespectra.readthedocs.io/en/v4.9.0/install.html

Install the dependencies required to run the test suite.

```bash
$ pip install '.[test]'

```

--------------------------------

### Set up local development environment

Source: https://wavespectra.readthedocs.io/en/v4.9.0/contributing.html

Create a virtual environment, navigate to the project directory, and install the package with extra and test dependencies.

```bash
$ mkvirtualenv wavespectra
$ cd wavespectra/
$ pip install -e '.[extra,test]'

```

--------------------------------

### Define input data for Zieger reconstruction recipes

Source: https://wavespectra.readthedocs.io/en/v4.9.0/reconstruction.html

Setup code for the Zieger reconstruction examples: reads a WW3 spectrum, partitions it using ptm1, calculates spectral parameters (fp, dm, dspr, gamma, gw, hs), computes alpha values for methods 1-3, and defines common reconstruction parameters.

```python
In [1]: import numpy as np

In [2]: import xarray as xr

In [3]: from wavespectra import read_ww3

In [4]: from wavespectra.construct import construct_partition

# Reading and partitioning existing spectrum
In [5]: dset = read_ww3("_static/ww3file.nc").isel(time=0, site=-1, drop=True).sortby("dir")

In [6]: dsetp = dset.spec.partition.ptm1(dset.wspd, dset.wdir, dset.dpt)

# Calculating parameters
In [7]: ds = dsetp.spec.stats(["fp", "dm", "dspr", "gamma", "gw", "hs"])

# Alpha
In [8]: ds["alpha"] = (5 * np.pi**4 / 9.81**2) * ds.hs**2 * ds.fp**4

# Alpha for method #3
In [9]: hs = ds.hs.where(ds.hs >= 0.7, ds.hs * 1.12)

In [10]: ds["alpha3"] = (5 * np.pi**4 / 9.81**2) * hs**2 * ds.fp**4

# Common reconstruct parameters
In [11]: dir_name = "cartwright"

In [12]: dir_kwargs = dict(dir=dset.dir, dm=ds.dm, dspr=ds.dspr)

In [13]: freq_name = "jonswap"

In [14]: kw = dict(freq=dset.freq, fp=ds.fp)
```

--------------------------------

### Install wavespectra with pip including extra dependencies

Source: https://wavespectra.readthedocs.io/en/v4.9.0/install.html

Full installation that includes netcdf4 and other extra libraries.

```bash
$ pip install wavespectra[extra]

```

--------------------------------

### Import libraries for partitioning examples

Source: https://wavespectra.readthedocs.io/en/v4.9.0/partitioning.html

Imports numpy, xarray, matplotlib.pyplot, cmocean, and wavespectra functions read_ww3 and read_wwm. These are the standard imports used in the partitioning examples.

```python
In [1]: import numpy as np

In [2]: import xarray as xr

In [3]: import matplotlib.pyplot as plt

In [4]: import cmocean

In [5]: from wavespectra import read_ww3, read_wwm

```

--------------------------------

### BBOX partitioning example

Source: https://wavespectra.readthedocs.io/en/v4.9.0/partitioning.html

Partitions spectra using a bounding box defined by frequency and direction limits. The example reads a WAVEWATCH III file and plots the partitioned spectra.

```python
In [40]: dset = read_wwm("_static/wwmfile.nc")

In [41]: bbox = dict(fmin=0.05, fmax=0.1, dmin=30, dmax=120)

In [42]: dspart = dset.spec.partition.bbox(bboxes=[bbox])

In [43]: dspart.isel(time=0, site=0, drop=True).spec.plot(col="part");

In [44]: plt.draw()

```

--------------------------------

### Install wavespectra in development mode

Source: https://wavespectra.readthedocs.io/en/v4.9.0/install.html

Install in editable mode to allow code changes to take effect without reinstalling.

```bash
$ pip install -e .

```

--------------------------------

### Install wavespectra with conda

Source: https://wavespectra.readthedocs.io/en/v4.9.0/install.html

Install the latest stable release using conda from the conda-forge channel.

```bash
$ conda install -c conda-forge wavespectra

```

--------------------------------

### HP01 partitioning example

Source: https://wavespectra.readthedocs.io/en/v4.9.0/partitioning.html

Partitions spectra using the HP01 method, which merges wind-sea and adjacent swells. The example specifies swells=2 and plots the result.

```python
In [45]: dset = read_wwm("_static/wwmfile.nc")

In [46]: dspart = dset.spec.partition.hp01(
   ....:     dset.wspd,
   ....:     dset.wdir,
   ....:     dset.dpt,
   ....:     swells=2,
   ....: )
   ....: 

In [47]: dspart.isel(time=0, site=0, drop=True).spec.plot(col="part");

In [48]: plt.draw()

```

--------------------------------

### Partition and reconstruct spectra with partition_and_reconstruct

Source: https://wavespectra.readthedocs.io/en/v4.9.0/reconstruction.html

Example of using partition_and_reconstruct to partition and reconstruct a spectrum with different directional and frequency shapes. The first call uses Cartwright for all partitions, the second uses asymmetric for wind sea and Cartwright for swells. The example also includes plotting the original and reconstructed spectra.

```python
In [13]: ds = read_ww3("_static/ww3file.nc").isel(time=0, site=0, drop=True).sortby("dir")

# Use Cartwright and Jonswap
In [14]: dsr1 = partition_and_reconstruct(
   ....:     ds,
   ....:     parts=4,
   ....:     freq_name="jonswap",
   ....:     dir_name="cartwright",
   ....:     partition_method="ptm1",
   ....:     method_combine="max",
   ....: )
   ....: 

# Asymmetric for wind sea and Cartwright for swells, Jonswap for all partitions
In [15]: dsr2 = partition_and_reconstruct(
   ....:     ds,
   ....:     parts=4,
   ....:     freq_name="jonswap",
   ....:     dir_name=["asymmetric", "cartwright", "cartwright", "cartwright",],
   ....:     partition_method="ptm1",
   ....:     method_combine="max",
   ....: )
   ....: 

# Plotting
In [16]: dsall = xr.concat([ds.efth, dsr1.efth, dsr2.efth], dim="directype")

In [17]: dsall["directype"] = ["Original", "Cartwright", "Asymmetric+Cartwright"]

In [18]: dsall.spec.plot(
   ....:     figsize=(8,4),
   ....:     show_theta_labels=False,
   ....:     add_colorbar=False,
   ....:     col="directype",
   ....: );
   ....: 

In [19]: plt.draw()
```

--------------------------------

### STEEPNESS default partitioning with one wind sea and one swell

Source: https://wavespectra.readthedocs.io/en/v4.9.0/partitioning.html

Partitions a wave spectrum using the steepness method with default settings, returning one wind sea and one swell. The example reads a WAVEWATCH III file and plots the partitioned spectra.

```python
In [49]: dset = read_wwm("_static/wwmfile.nc")

In [50]: dspart = dset.spec.partition.steepness(dset.dpt)

In [51]: dspart.isel(time=7, site=0, drop=True).spec.plot(col="part");

In [52]: plt.draw()
```

--------------------------------

### Construct spectrum with construct_partition using Jonswap and Cartwright

Source: https://wavespectra.readthedocs.io/en/v4.9.0/quickstart.html

Constructs a wave spectrum using the construct_partition function with Jonswap frequency and Cartwright directional shape functions. The example sets up frequency and direction arrays, then calls construct_partition with specified parameters (fp=0.1, gamma=3.3, hs=1.5, dm=60, dspr=30). Finally, it plots the resulting spectrum.

```python
In [73]: from wavespectra.construct import construct_partition

In [74]: freq = np.arange(0.03, 0.401, 0.001)

In [75]: dir = np.arange(0, 360, 1)

In [76]: ds = construct_partition(
   ....:     freq_name="jonswap",
   ....:     dir_name="cartwright",
   ....:     freq_kwargs={"freq":  freq, "fp": 0.1, "gamma": 3.3, "hs": 1.5},
   ....:     dir_kwargs={"dir": dir, "dm": 60, "dspr": 30},
   ....: )
   ....: 

In [77]: ds.spec.plot();
```

--------------------------------

### Build documentation with make

Source: https://wavespectra.readthedocs.io/en/v4.9.0/install.html

Build the documentation using the make command.

```bash
$ make docs

```

--------------------------------

### Show wavespectra convert help

Source: https://wavespectra.readthedocs.io/en/v4.9.0/cli.html

Shows help for the 'convert' subcommand, listing its subcommands: format and stats.

```bash
$ wavespectra convert --help
Usage: wavespectra convert [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  format  Converts INFILE with format defined by ENGINE to OUTFILE with...
  stats   Write a new file OUTFILE with integrated parameters from INFILE.

```

--------------------------------

### Plot one-dimensional spectrum with ds.spec.oned().plot()

Source: https://wavespectra.readthedocs.io/en/v4.9.0/quickstart.html

Plots the one-dimensional (frequency) spectrum from the constructed dataset. This is a separate plotting example that follows the construction example.

```python
In [78]: ds.spec.oned().plot(figsize=(8, 4));
```

--------------------------------

### Partition.__init__

Source: https://wavespectra.readthedocs.io/en/v4.9.0/generated/wavespectra.partition.partition.Partition.html

Initializes a Partition object with a wave spectra dataset.

```APIDOC
## Partition.__init__

### Description
Initializes a Partition object with a wave spectra dataset.

### Method
Constructor

### Parameters
- **dset** (xarray.Dataset) - Required - The wave spectra dataset to partition.

### Returns
None

```

--------------------------------

### Show wavespectra reconstruct spectra help

Source: https://wavespectra.readthedocs.io/en/v4.9.0/cli.html

Shows help for the 'reconstruct spectra' subcommand, which partitions and reconstructs spectra from a file. Options include -f/--freq_name (default jonswap), -d/--dir_name (default cartwright), -pm/--partition_method (default ptm3), -m/--method_combine (default max), -p/--parts (default 4), and -c/--chunks.

```bash
$ wavespectra reconstruct spectra --help
Usage: wavespectra reconstruct spectra [OPTIONS] INFILE ENGINE OUTFILE

  Partition and reconstruct spectra from file.

Options:
  -k, --engine_kwargs <TEXT TEXT>...
                                  kwargs to pass to file reader engine, repeat
                                  for multiple key-value pairs
  -f, --freq_name TEXT            Frequency function  [default: jonswap]
  -d, --dir_name TEXT             Spread function  [default: cartwright]
  -pm, --partition_method TEXT    Partitioning method, either `ptm1`, `ptm2`
                                  or `ptm3`  [default: ptm3]
  -m, --method_combine TEXT       Method to combine partitions  [default: max]
  -p, --parts INTEGER             Number of partitions to keep  [default: 4]
  -c, --chunks <TEXT TEXT>...     Chunks dict to chunk dataset before
                                  partitioning, repeat for multiple dims
  --help                          Show this message and exit.

```

--------------------------------

### Bunney asymmetrical spread example

Source: https://wavespectra.readthedocs.io/en/v4.9.0/construction.html

Example of using the `asymmetric` function to compute directional spreading with specified mean and peak parameters. The function is called with `dm=45`, `dpm=50`, `dspr=20`, `dpspr=17`, `fm=0.1`, and `fp=0.09`, and the resulting spectrum is plotted. Requires `dir` and `freq` to be defined beforehand.

```python
In [4]: asym = asymmetric(
   ...:     dir=dir,
   ...:     freq=freq,
   ...:     dm=45,
   ...:     dpm=50,
   ...:     dspr=20,
   ...:     dpspr=17,
   ...:     fm=0.1,
   ...:     fp=0.09,
   ...: )
   ...: 

In [5]: asym.spec.plot();

```

--------------------------------

### Show wavespectra convert format help

Source: https://wavespectra.readthedocs.io/en/v4.9.0/cli.html

Shows help for the 'convert format' subcommand, which converts a file from one format to another. Options include -k/--engine_kwargs for reader engine kwargs and -o/--overwrite to overwrite the output file.

```bash
$ wavespectra convert format --help
Usage: wavespectra convert format [OPTIONS] INFILE ENGINE OUTFILE FMT

  Converts INFILE with format defined by ENGINE to OUTFILE with new format
  FMT.

Options:
  -k, --engine_kwargs <TEXT TEXT>...
                                  kwargs to pass to file reader engine, repeat
                                  for multiple key-value pairs
  -o, --overwrite                 Overwrite OUTFILE if it exists
  --help                          Show this message and exit.

```

--------------------------------

### Cartwright symmetrical spread example

Source: https://wavespectra.readthedocs.io/en/v4.9.0/construction.html

Example of using the `cartwright` function to compute directional spreading for a set of directional spreads. The mean direction `dm` is set to 60 degrees, and the function is called for `dspr` values of 20, 30, 40, and 50 degrees, plotting each result. Requires `dir` to be defined beforehand.

```python
In [1]: dm = 60

In [2]: for dspr in [20, 30, 40, 50]:
   ...:     gth = cartwright(dir, dm, dspr=dspr)
   ...:     gth.plot(label=f"$D_m$={dm:0.0f} deg, $\sigma$={dspr} deg");
   ...: 


In [3]: plt.draw()

```

--------------------------------

### Show wavespectra top-level help

Source: https://wavespectra.readthedocs.io/en/v4.9.0/cli.html

Shows the top-level CLI help for wavespectra, listing the available commands: convert and reconstruct.

```bash
$ wavespectra --help
Usage: wavespectra [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  convert
  reconstruct

```

--------------------------------

### wavespectra.partition.partition.Partition.ptm5()

Source: https://wavespectra.readthedocs.io/en/v4.9.0/genindex.html

Method on Partition to partition using PTM5.

```APIDOC
## Partition.ptm5()

### Description
Partitions the spectra using the PTM5 method.

### Method
ptm5()

### Parameters
- **self** (Partition) - Required - The Partition object.

### Returns
- Partitioned spectra.
```

--------------------------------

### Backend Engine Usage

Source: https://wavespectra.readthedocs.io/en/v4.9.0/io-input.html

Example of using the 'ww3' backend engine with xarray.open_dataset to read a WAVEWATCHIII netCDF file.

```APIDOC
## Backend Engine Usage

### Description
Backend engines are provided to seamlessly access wavespectra datasets through the xarray.open_dataset function. These engines are designated by their respective `filetype`.

### Usage Example
```python
import xarray as xr

dset = xr.open_dataset("_static/ww3file.nc", engine="ww3")
```

### Resulting Dataset
```
<SpecDataset> Size: 44kB
Dimensions:  (time: 9, site: 2, freq: 25, dir: 24)
Coordinates:
  * freq     (freq) float32 100B 0.04118 0.0453 0.04983 ... 0.3352 0.3687 0.4056
  * site     (site) int32 8B 1 2
  * time     (time) datetime64[ns] 72B 2014-12-01 ... 2014-12-05
  * dir      (dir) float32 96B 270.0 255.0 240.0 225.0 ... 315.0 300.0 285.0
Data variables:
    dpt      (time, site) float32 72B ...
    efth     (time, site, freq, dir) float32 43kB ...
    lat      (site) float32 8B ...
    lon      (site) float32 8B ...
    wspd     (time, site) float32 72B ...
    wdir     (time, site) float32 72B ...
```
```

--------------------------------

### Run linter and tests

Source: https://wavespectra.readthedocs.io/en/v4.9.0/contributing.html

Run ruff checks, formatting checks, and pytest to verify your changes. These tools are installed with the test extra.

```bash
$ ruff check wavespectra tests
$ ruff format --check wavespectra tests
$ pytest tests

```

--------------------------------

### wavespectra.partition.partition.Partition.ptm1()

Source: https://wavespectra.readthedocs.io/en/v4.9.0/genindex.html

Method on Partition to partition using PTM1.

```APIDOC
## Partition.ptm1()

### Description
Partitions the spectra using the PTM1 method.

### Method
ptm1()

### Parameters
- **self** (Partition) - Required - The Partition object.

### Returns
- Partitioned spectra.
```

--------------------------------

### Import read_hotswan from full module path

Source: https://wavespectra.readthedocs.io/en/v4.9.0/io-input.html

Shows how to import a reading function that does not follow the naming conventions from its full module path, using read_hotswan as an example.

```python
In [4]: from wavespectra.input.swan import read_hotswan
```

--------------------------------

### wavespectra.partition.partition.Partition.ptm3()

Source: https://wavespectra.readthedocs.io/en/v4.9.0/genindex.html

Method on Partition to partition using PTM3.

```APIDOC
## Partition.ptm3()

### Description
Partitions the spectra using the PTM3 method.

### Method
ptm3()

### Parameters
- **self** (Partition) - Required - The Partition object.

### Returns
- Partitioned spectra.
```

--------------------------------

### Show wavespectra convert stats help

Source: https://wavespectra.readthedocs.io/en/v4.9.0/cli.html

Shows help for the 'convert stats' subcommand, which writes a new file with integrated parameters. The -p/--parameters option defaults to hs, tp, dpm.

```bash
$ wavespectra convert stats --help
Usage: wavespectra convert stats [OPTIONS] INFILE ENGINE OUTFILE

  Write a new file OUTFILE with integrated parameters from INFILE.

Options:
  -k, --engine_kwargs <TEXT TEXT>...
                                  kwargs to pass to file reader engine, repeat
                                  for multiple key-value pairs
  -p, --parameters TEXT           Integrated parameters to include, repeat for
                                  multiple parameters  [default: hs, tp, dpm]
  --help                          Show this message and exit.

```

--------------------------------

### Export spectrum to Orcaflex model

Source: https://wavespectra.readthedocs.io/en/v4.9.0/generated/wavespectra.SpecDataset.to_orcaflex.html

Example usage of SpecDataset.to_orcaflex. Requires an Orcaflex license and the OrcFxAPI module. Only 2D spectra E(f,d) are supported, and the DataArray should contain a single spectrum.

```python
>>> from OrcFxAPI import *
>>> from wavespectra import read_triaxys
>>> m = Model()
>>> spectrum = read_triaxys("triaxys.DIRSPEC")).isel(time=0)  # get only the fist spectrum in time
>>> spectrum.spec.to_orcaflex(m)
```

--------------------------------

### STEEPNESS with multiple swells and hp01 merging

Source: https://wavespectra.readthedocs.io/en/v4.9.0/partitioning.html

Partitions with two swells and uses the 'hp01' swell_merge argument to merge excess partitions onto their closest neighbour. The example plots the resulting partitioned spectra.

```python
In [53]: dspart = dset.spec.partition.steepness(dset.dpt, swells=2, swell_merge="hp01")

In [54]: dspart.isel(time=7, site=0, drop=True).spec.plot(col="part");

In [55]: plt.draw()
```

--------------------------------

### wavespectra.partition.partition.Partition.ptm2()

Source: https://wavespectra.readthedocs.io/en/v4.9.0/genindex.html

Method on Partition to partition using PTM2.

```APIDOC
## Partition.ptm2()

### Description
Partitions the spectra using the PTM2 method.

### Method
ptm2()

### Parameters
- **self** (Partition) - Required - The Partition object.

### Returns
- Partitioned spectra.
```