Quickstart

Currently, only shear processing is fully functional. The high-level API can be imported from turban.

Setup

Clone the repository:

git clone https://github.com/turban-toolbox/turban-toolbox.git
cd turban-toolbox

Activate your Python environment of choice. Then, install TURBAN with dependency groups as needed. Requires pip >= 24.1 for --groups support:

python -m pip install --upgrade pip
python -m pip install -e . --group mss --group microrider

Example data, also needed for the unit tests, can be downloaded using:

turban_download_datafiles

Alternatively the environment variable TURBAN_AUTO_DOWNLOAD_DATAFILES can be set to 1, which has the effect that data are downloaded automatically when a test is run. The command turban_download_datafiles accepts the option --force which downloads all data, even if they have been downloaded before.

Using the high-level ShearProcessing pipeline

from turban import ShearProcessing, plot

# Process a level 1 dataset all the way to level 4
p = ShearProcessing.from_atomix_netcdf("data/process/shear/MSS_Baltic.nc", level=1)

# export level 4 to an xarray.Dataset
ds = p.level4.to_xarray()

# or plot e.g. like this:
plot(p)

Manual configuration

If no suitable ShearProcessing.from_* method exists, you can configure one manually like this (use numpy arrays time, shear, etc. from anywhere):

import numpy as np
import xarray as xr
from turban import ShearProcessing, ShearLevel1, ShearConfig, plot

atomix_nc_filename = "data/process/shear/MSS_Baltic.nc"

cfg = ShearConfig(
    sampfreq=1024.0,
    segment_length=2048,
    segment_overlap=1024,
    chunk_length=5120,
    chunk_overlap=2560,
    freq_cutoff_antialias=None,  # None means that this cutoff is not applied
    freq_cutoff_corrupt=None,  # None means that this cutoff is not applied
    freq_highpass=0.15,
    spatial_response_wavenum=50.0,
    waveno_cutoff_spatial_corr=None,  # None means that this cutoff is not applied
    waveno_spectral_min=None,  # None means that this cutoff is not applied
    spike_threshold=8.0,
    max_tries=10,
    spike_replace_before=512,
    spike_replace_after=512,
    spike_include_before=10,
    spike_include_after=20,
    cutoff_freq_lp=0.5,
)

ds1 = xr.load_dataset(atomix_nc_filename, group="L1_converted")
ds2 = xr.load_dataset(atomix_nc_filename, group="L2_cleaned")

level1 = ShearLevel1(
    time=ds1.TIME.values,
    senspeed=ds1.PSPD_REL.values,
    cfg=cfg,
    shear=ds1.SHEAR.values,
    section_number=ds2.SECTION_NUMBER.values.astype(int),
)

p = ShearProcessing(level1)
plot(p)