pysmo.functions

def clone_to_mini[TMini: _AnyMini](
    mini_cls: type[TMini], source: "_AnyProto", update: dict | None = None
) -> TMini:
    """Create a new instance of a Mini class from a matching other one.

    This function creates a clone of an existing class by
    [copying][copy.copy] the attributes defined in `mini_cls` from the source
    to the target. Attributes only present in the source object are ignored,
    potentially resulting in a smaller and more performant object.

    If the source instance is missing an attribute for which a default is
    defined in the target class, then that default value for that attribute is
    used.

    Args:
        mini_cls: The type of Mini class to create.
        source: The instance to clone (must contain all attributes present
            in `mini_cls`).
        update: Update or add attributes in the returned `mini_cls` instance.

    Returns:
        A new Mini instance type mini_cls.

    Raises:
        AttributeError: If the `source` instance does not contain all
            attributes in `mini_cls` (unless they are provided with the
            `update` keyword argument).

    Examples:
        Create a [`MiniSeismogram`][pysmo.MiniSeismogram] from a
        [`SacSeismogram`][pysmo.classes.SacSeismogram] instance with
        a new `begin_time`.

        ```python
        >>> from pysmo.functions import clone_to_mini
        >>> from pysmo import MiniSeismogram
        >>> from pysmo.classes import SAC
        >>> import pandas as pd
        >>> from datetime import timezone
        >>> now = pd.Timestamp.now(timezone.utc)
        >>> sac_seismogram = SAC.from_file("example.sac").seismogram
        >>> mini_seismogram = clone_to_mini(MiniSeismogram, sac_seismogram, update={"begin_time": now})
        >>> all(sac_seismogram.data == mini_seismogram.data)
        True
        >>> mini_seismogram.begin_time == now
        True
        >>>
        ```

    Tip: See Also
        [`copy_from_mini`][pysmo.functions.copy_from_mini]: Copy attributes
        from a Mini instance to matching other one.
    """

    update = update or dict()

    if all(
        map(
            lambda x: (
                hasattr(source, x.name) or x.name in update or x.default is not NOTHING
            ),
            fields(mini_cls),
        )
    ):
        clone_dict = {
            attr.name: (
                update[attr.name]
                if attr.name in update
                else copy(getattr(source, attr.name, attr.default))
            )
            for attr in fields(mini_cls)
        }
        return mini_cls(**clone_dict)

    raise AttributeError(
        f"Unable to create clone: {source} not compatible with {mini_cls}."
    )

def copy_from_mini(
    source: "_AnyMini", target: "_AnyProto", update: dict | None = None
) -> None:
    """Copy attributes from a Mini instance to matching other one.

    This function [copies][copy.copy] all attributes in the `source` Mini class
    instance to a compatible `target` instance.

    Args:
        source: The Mini instance to copy attributes from.
        target: Compatible target instance.
        update: Update or add attributes in the target instance.

    Raises:
        AttributeError: If the `target` instance does not contain all
            attributes in the `source` instance (unless they are
            provided with the `update` keyword argument).

    Tip: See Also
        [`clone_to_mini`][pysmo.functions.clone_to_mini]: Create a new
        instance of a Mini class from a matching other one.
    """

    update = update or dict()

    attributes = unstructure(source).keys() | set()
    attributes.update(update.keys())

    if all(map(lambda x: hasattr(target, x), attributes)):
        for attribute in attributes:
            if attribute in update:
                setattr(target, attribute, update[attribute])
            else:
                setattr(target, attribute, copy(getattr(source, attribute)))
    else:
        raise AttributeError(
            f"Unable to copy to target: {type(target)} not compatible with {type(source)}."
        )

def crop[T: Seismogram](
    seismogram: T, begin_time: pd.Timestamp, end_time: pd.Timestamp, clone: bool = False
) -> None | T:
    """Shorten a seismogram by providing new begin and end times.

    This function calculates the indices corresponding to the provided new
    begin and end times using [`time2index`][pysmo.functions.time2index], then
    slices the seismogram `data` array accordingly and updates the
    `begin_time`.

    Args:
        seismogram: [`Seismogram`][pysmo.Seismogram] object.
        begin_time: New begin time.
        end_time: New end time.
        clone: Operate on a clone of the input seismogram.

    Returns:
        Cropped [`Seismogram`][pysmo.Seismogram] object if called with `clone=True`.

    Raises:
        ValueError: If new begin time is after new end time.

    Examples:
        ```python
        >>> from pysmo.functions import crop
        >>> from pysmo.classes import SAC
        >>> import pandas as pd
        >>> sac_seis = SAC.from_file("example.sac").seismogram
        >>> new_begin_time = sac_seis.begin_time + pd.Timedelta(seconds=10)
        >>> new_end_time = sac_seis.end_time - pd.Timedelta(seconds=10)
        >>> crop(sac_seis, new_begin_time, new_end_time)
        >>>
        ```
    """

    if begin_time > end_time:
        raise ValueError("New begin_time cannot be after new end_time")

    start_index = time2index(seismogram, begin_time)
    end_index = time2index(seismogram, end_time)

    if clone is True:
        seismogram = deepcopy(seismogram)

    seismogram.data = seismogram.data[start_index : end_index + 1]
    seismogram.begin_time += seismogram.delta * start_index

    return seismogram if clone is True else None

def detrend[T: Seismogram](seismogram: T, clone: bool = False) -> None | T:
    """Remove linear and/or constant trends from a seismogram.

    Args:
        seismogram: Seismogram object.
        clone: Operate on a clone of the input seismogram.

    Returns:
        Detrended [`Seismogram`][pysmo.Seismogram] object if called with `clone=True`.

    Examples:
        ```python
        >>> import numpy as np
        >>> import pytest
        >>> from pysmo.functions import detrend
        >>> from pysmo.classes import SAC
        >>> sac_seis = SAC.from_file("example.sac").seismogram
        >>> 0 == pytest.approx(np.mean(sac_seis.data), abs=1e-8)
        np.False_
        >>> detrend(sac_seis)
        >>> 0 == pytest.approx(np.mean(sac_seis.data), abs=1e-8)
        np.True_
        >>>
        ```
    """
    if clone is True:
        seismogram = deepcopy(seismogram)

    seismogram.data = scipy.signal.detrend(seismogram.data)

    if clone is True:
        return seismogram
    return None

def estimate_delta(deltas: Sequence[PositiveTimedelta]) -> PositiveTimedelta:
    """Estimate a canonical sampling interval from a set of near-equal deltas.

    Useful when several seismograms nominally share a sampling interval but
    report values that differ only by measurement noise (e.g. clock drift
    reflected in a reported sample rate) or floating-point noise. Returns the low
    median of `deltas`: an order-independent choice that is always one of
    the input values, rather than a synthetic average that none of the
    seismograms actually have.

    This does not check how close the given deltas are to each other; for a
    set of genuinely different sampling intervals it simply returns the low
    median of the sorted values.

    Args:
        deltas: Sampling intervals to estimate a canonical value from.

    Returns:
        The estimated canonical sampling interval.

    Raises:
        ValueError: If `deltas` is empty.

    Examples:
        ```python
        >>> import pandas as pd
        >>> from pysmo.functions import estimate_delta
        >>> deltas = [
        ...     pd.Timedelta(seconds=0.01),
        ...     pd.Timedelta(seconds=0.010000000000001),
        ...     pd.Timedelta(seconds=0.01),
        ... ]
        >>> estimate_delta(deltas)
        Timedelta('0 days 00:00:00.010000')
        >>>
        ```
    """
    if not deltas:
        raise ValueError("No deltas to estimate from.")
    return statistics.median_low(deltas)

def merge[T: Seismogram](
    seismograms: Sequence[Seismogram],
    *,
    delta: PositiveTimedelta | None = None,
    auto_delta: bool = False,
    gap_tolerance_factor: NonNegativeNumber = 0.5,
    clone: bool = False,
) -> None | T:
    """Merge contiguous seismograms into a single seismogram.

    Empty seismograms take no part in the merge arithmetic (they never
    contribute data and never constrain sampling-interval or gap/overlap
    checks) and are absent from the result if there are non-empty
    seismograms to merge with. The remaining, non-empty seismograms are
    merged in chronological order of `begin_time`, regardless of the order
    they are given in, and must lie on a single regular sampling grid. By
    default, this requires equal sampling intervals; when `delta` is
    provided, each non-empty seismogram is first resampled to that common
    interval using [`resample`][pysmo.functions.resample]. If `delta` is
    `None` and `auto_delta` is `True`, a common interval is estimated with
    [`estimate_delta`][pysmo.functions.estimate_delta] instead of requiring
    an exact match — useful when sampling intervals only disagree by
    measurement or floating-point noise.

    A small amount of boundary timestamp jitter is allowed, bounded by
    `gap_tolerance_factor` sampling intervals, so metadata rounding noise does
    not block otherwise valid merges. If consecutive seismograms overlap
    within this tolerance, the overlapping samples must match (compared with
    [`allclose`][numpy.allclose] and its default tolerances, to accommodate
    floating-point noise from e.g. prior resampling); they are verified and
    the duplicates are discarded rather than concatenated.

    When `clone=False`, the first seismogram in `seismograms` (as given —
    not necessarily the chronologically first, and regardless of whether it
    is itself empty) is modified in place and becomes the merged result: its
    `begin_time` and `data` are overwritten to reflect the full,
    chronologically-ordered merge of the non-empty seismograms. Other input
    seismograms are never modified.

    Args:
        seismograms: Seismograms to merge. May be given in any order; any mix
            of types satisfying the [`Seismogram`][pysmo.Seismogram] protocol
            works at runtime. When `clone=True`, the return type is inferred
            from `seismograms`; for a bare list/tuple literal mixing concrete
            types, annotate it as `Sequence[Seismogram]` to keep the call
            type-checked (see Examples).
        delta: Sampling interval to resample all non-empty seismograms to
            before merging. If `None`, all non-empty input seismograms must
            already share the same sampling interval, unless `auto_delta`
            is `True`.
        auto_delta: Estimate a common sampling interval from the non-empty
            seismograms with
            [`estimate_delta`][pysmo.functions.estimate_delta] instead of
            requiring an exact match. Mutually exclusive with `delta`; type
            checkers reject passing both.
        gap_tolerance_factor: Maximum allowed boundary timestamp jitter between
            consecutive seismograms, as a fraction of the sampling interval.
        clone: Operate on a clone of the first input seismogram.

    Returns:
        Merged [`Seismogram`][pysmo.Seismogram] object if called with
        `clone=True`.

    Raises:
        ValueError: If `seismograms` is empty, contains no non-empty
            seismograms, the sampling intervals of the non-empty seismograms
            differ and neither `delta` nor `auto_delta` is provided, the
            boundary between consecutive non-empty seismograms contains a
            gap or overlap exceeding the allowed tolerance, overlapping
            samples do not match, or `gap_tolerance_factor` is negative.

    Examples:
        ```python
        >>> import numpy as np
        >>> import pandas as pd
        >>> from pysmo import MiniSeismogram
        >>> from pysmo.functions import merge
        >>> first = MiniSeismogram(
        ...     begin_time=pd.Timestamp("2010-02-27T06:30:00Z"),
        ...     delta=pd.Timedelta(seconds=1),
        ...     data=np.array([1.0, 2.0, 3.0]),
        ... )
        >>> second = MiniSeismogram(
        ...     begin_time=pd.Timestamp("2010-02-27T06:30:03Z"),
        ...     delta=pd.Timedelta(seconds=1),
        ...     data=np.array([4.0, 5.0]),
        ... )
        >>> merged = merge([first, second], clone=True)
        >>> merged.data
        array([1., 2., 3., 4., 5.])
        >>> merged.begin_time
        Timestamp('2010-02-27 06:30:00+0000', tz='UTC')

        ```

        Merging seismograms of different concrete types works the same way
        at runtime. A bare list literal's inferred type comes from its
        elements, though, and for a mix of concrete types that inferred type
        may not satisfy the `Seismogram` bound at all, making the call fail
        to type-check. Annotate the list as `Sequence[Seismogram]` to keep
        the result type-checked:

        ```python
        >>> from collections.abc import Sequence
        >>> from pysmo import Seismogram
        >>> from pysmo.classes import GeoCsvSeismogram
        >>> geocsv_seis = GeoCsvSeismogram(
        ...     begin_time=pd.Timestamp("2010-02-27T06:30:05Z"),
        ...     delta=pd.Timedelta(seconds=1),
        ...     data=np.array([6.0, 7.0]),
        ...     sid="IU_ANMO_00_LHZ",
        ... )
        >>> mixed: Sequence[Seismogram] = [merged, geocsv_seis]
        >>> merged_mixed = merge(mixed, clone=True)
        >>> merged_mixed.data
        array([1., 2., 3., 4., 5., 6., 7.])
        >>>
        ```

        The merged object's actual class is always `seismograms[0]`'s class,
        regardless of what a type checker can infer — this is purely a
        static-typing concern. If downstream code depends on the concrete
        type, merging a single concrete type (the common case) lets it be inferred
        automatically, without needing the annotation above.

        Seismograms whose sampling intervals only disagree by measurement or
        floating-point noise (see
        [`estimate_delta`][pysmo.functions.estimate_delta]) can be merged
        with `auto_delta=True` instead of requiring an exact match:

        ```python
        >>> steady = MiniSeismogram(
        ...     begin_time=pd.Timestamp("2010-02-27T06:30:00Z"),
        ...     delta=pd.Timedelta(seconds=1),
        ...     data=np.array([1.0, 2.0, 3.0]),
        ... )
        >>> jittery = MiniSeismogram(
        ...     begin_time=pd.Timestamp("2010-02-27T06:30:03Z"),
        ...     delta=pd.Timedelta(seconds=1) + pd.Timedelta(nanoseconds=1),
        ...     data=np.array([4.0, 5.0, 6.0]),
        ... )
        >>> auto_merged = merge(
        ...     [steady, jittery], auto_delta=True, clone=True
        ... )
        >>> auto_merged.delta
        Timedelta('0 days 00:00:01')
        >>> auto_merged.data
        array([1., 2., 3., 4., 5., 6.])
        >>>
        ```

        `auto_delta` estimates a canonical interval with
        [`estimate_delta`][pysmo.functions.estimate_delta]; it does not
        verify that the seismograms genuinely belong on the same sampling
        grid. Users are encouraged to inspect the resulting `delta` (as
        above), or call
        [`estimate_delta`][pysmo.functions.estimate_delta] directly
        beforehand, to confirm the estimate is the value expected rather
        than assuming it silently.
    """
    if gap_tolerance_factor < 0:
        raise ValueError("gap_tolerance_factor must be non-negative.")

    if not seismograms:
        raise ValueError("No seismograms to merge.")

    working = (
        [deepcopy(seismogram) for seismogram in seismograms]
        if clone
        else list(seismograms)
    )

    non_empty = [seismogram for seismogram in working if len(seismogram.data)]
    if not non_empty:
        raise ValueError("No non-empty seismograms to merge.")

    if delta is None and auto_delta:
        delta = estimate_delta([seismogram.delta for seismogram in non_empty])

    if delta is None:
        reference_delta = non_empty[0].delta
        for seismogram in non_empty[1:]:
            if seismogram.delta != reference_delta:
                raise ValueError(
                    "Cannot merge seismograms with different sampling intervals "
                    f"without resampling: {reference_delta} vs {seismogram.delta}."
                )
    else:
        reference_delta = delta
        for index, seismogram in enumerate(working):
            if len(seismogram.data) == 0:
                continue
            if seismogram.delta == delta:
                continue
            if clone or index > 0:
                working[index] = resample(seismogram, delta, clone=True)
            else:
                resample(seismogram, delta)
        non_empty = [seismogram for seismogram in working if len(seismogram.data)]

    ordered = sorted(non_empty, key=lambda seismogram: seismogram.begin_time)

    overlap_samples = [0] * len(ordered)
    for index, (prev, curr) in enumerate(pairwise(ordered), start=1):
        expected_next = prev.end_time + prev.delta
        gap = curr.begin_time - expected_next
        tolerance = prev.delta * gap_tolerance_factor
        if abs(gap) > tolerance:
            description = (
                f"gap of {gap.total_seconds():.6f} s"
                if gap > pd.Timedelta(0)
                else f"overlap of {-gap.total_seconds():.6f} s"
            )
            raise ValueError(
                f"Data {description} detected between seismogram ending at "
                f"{prev.end_time} and seismogram starting at {curr.begin_time}."
            )
        if gap < pd.Timedelta(0):
            samples = min(round(-gap / prev.delta), len(prev.data), len(curr.data))
            if samples > 0 and not np.allclose(
                prev.data[-samples:], curr.data[:samples]
            ):
                raise ValueError(
                    f"Overlapping samples between seismogram ending at "
                    f"{prev.end_time} and seismogram starting at "
                    f"{curr.begin_time} do not match; cannot merge."
                )
            overlap_samples[index] = samples

    merged = cast(T, working[0])
    merged.begin_time = ordered[0].begin_time
    merged.delta = reference_delta
    merged.data = np.concatenate(
        [ordered[0].data]
        + [
            seismogram.data[samples:]
            for seismogram, samples in zip(ordered[1:], overlap_samples[1:])
        ]
    )

    if clone:
        return merged
    return None

def normalize[T: Seismogram](
    seismogram: T,
    t1: pd.Timestamp | None = None,
    t2: pd.Timestamp | None = None,
    clone: bool = False,
) -> None | T:
    """Normalise a seismogram with its absolute max value.

    Args:
        seismogram: Seismogram object.
        t1: Start of the window used to find the maximum. If `None`, the search
            starts from the beginning of the seismogram.
        t2: End of the window used to find the maximum. If `None`, the search
            continues to the end of the seismogram.
        clone: Operate on a clone of the input seismogram.

    Returns:
        Normalised [`Seismogram`][pysmo.Seismogram] object if `clone=True`.

    Raises:
        ValueError: If the absolute maximum of the data (within the optional
            time window) is zero, as normalisation would produce undefined results.

    Examples:
        ```python
        >>> import numpy as np
        >>> from pysmo.functions import normalize
        >>> from pysmo.classes import SAC
        >>> sac_seis = SAC.from_file("example.sac").seismogram
        >>> normalize(sac_seis)
        >>> -1 <= np.max(sac_seis.data) <= 1
        np.True_
        >>>
        ```
    """

    start_index, end_index = None, None

    if t1 is not None:
        start_index = time2index(seismogram, t1)

    if t2 is not None:
        end_index = time2index(seismogram, t2)

    abs_max = np.max(np.abs(seismogram.data[start_index:end_index]))
    if abs_max == 0:
        raise ValueError(
            "Cannot normalise a seismogram because the absolute maximum "
            "within the selected time window (or entire trace if no window "
            "is given) is zero."
        )

    if clone is True:
        seismogram = deepcopy(seismogram)

    seismogram.data /= abs_max

    if clone is True:
        return seismogram

    return None

def pad[T: Seismogram](
    seismogram: T,
    begin_time: pd.Timestamp,
    end_time: pd.Timestamp,
    mode: "_ModeKind | _ModeFunc" = "constant",
    clone: bool = False,
    **kwargs: Any,
) -> None | T:
    """Pad seismogram data.

    This function calculates the indices corresponding to the provided new
    begin and end times using [`time2index`][pysmo.functions.time2index], then
    pads the [`data`][pysmo.Seismogram.data] array using [`numpy.pad`][] and
    updates the [`begin_time`][pysmo.Seismogram.begin_time]. Note that the
    actual begin and end times are set by indexing, so they may be slightly
    different than the provided input begin and end times.

    Args:
        seismogram: [`Seismogram`][pysmo.Seismogram] object.
        begin_time: New begin time.
        end_time: New end time.
        mode: Pad mode to use (see [`numpy.pad`][] for all modes).
        clone: Operate on a clone of the input seismogram.
        kwargs: Keyword arguments to pass to [`numpy.pad`][].

    Returns:
        Padded [`Seismogram`][pysmo.Seismogram] object if called with `clone=True`.

    Raises:
        ValueError: If new begin time is after new end time.

    Examples:
        ```python
        >>> from pysmo.functions import pad
        >>> from pysmo.classes import SAC
        >>> import pandas as pd
        >>> import numpy as np
        >>>
        >>> sac_seis = SAC.from_file("example.sac").seismogram
        >>> original_length = len(sac_seis.data)
        >>> sac_seis.data
        array([-47201., -47361., -47511., ..., -82144., -71072., -59960.],
              shape=(57465,))
        >>> new_begin_time = sac_seis.begin_time - pd.Timedelta(seconds=10)
        >>> new_end_time = sac_seis.end_time + pd.Timedelta(seconds=10)
        >>> pad(sac_seis, new_begin_time, new_end_time)
        >>> np.isclose(len(sac_seis.data), original_length + 20 / sac_seis.delta.total_seconds())
        np.True_
        >>> sac_seis.data
        array([0., 0., 0., ..., 0., 0., 0.], shape=(57865,))
        >>>
        ```
    """

    if begin_time > end_time:
        raise ValueError("New begin_time cannot be after new end_time")

    start_index = time2index(seismogram, begin_time, allow_out_of_bounds=True)
    end_index = time2index(seismogram, end_time, allow_out_of_bounds=True)

    if clone is True:
        seismogram = deepcopy(seismogram)

    pad_before = max(0, -start_index)
    pad_after = max(0, end_index - (len(seismogram.data) - 1))

    if pad_before > 0 or pad_after > 0:
        seismogram.data = np.pad(
            seismogram.data,
            pad_width=(pad_before, pad_after),
            mode=mode,
            **kwargs,
        )
        seismogram.begin_time += seismogram.delta * min(0, start_index)

    return seismogram if clone else None

def resample[T: Seismogram](
    seismogram: T, delta: PositiveTimedelta, clone: bool = False
) -> None | T:
    """Resample Seismogram data using the Fourier method.

    This function uses [`scipy.signal.resample`][] to resample the data to a
    new sampling interval. If the new sampling interval is identical to the
    current one, no action is taken.

    Args:
        seismogram: Seismogram object.
        delta: New sampling interval.
        clone: Operate on a clone of the input seismogram.

    Returns:
        Resampled [`Seismogram`][pysmo.Seismogram] object if called with `clone=True`.

    Examples:
        ```python
        >>> from pysmo.functions import resample
        >>> from pysmo.classes import SAC
        >>> sac_seis = SAC.from_file("example.sac").seismogram
        >>> len(sac_seis.data)
        57465
        >>> original_delta = sac_seis.delta
        >>> new_delta = original_delta * 2
        >>> resample(sac_seis, new_delta)
        >>> len(sac_seis.data)
        28732
        >>>
        ```
    """
    if clone is True:
        seismogram = deepcopy(seismogram)

    if delta != seismogram.delta:
        npts = int(len(seismogram.data) * seismogram.delta / delta)
        seismogram.data = scipy.signal.resample(seismogram.data, npts)
        seismogram.delta = delta

    if clone is True:
        return seismogram
    return None

def taper[T: Seismogram](
    seismogram: T,
    taper_width: NonNegativeTimedelta | UnitFloat,
    window_type: _WindowType = "hann",
    clone: bool = False,
) -> None | T:
    """Apply a symmetric taper to the ends of a Seismogram.

    The taper width is understood as the portion of the seismogram affected
    by the taper window function. It can be provided as an absolute duration
    (non-negative [`Timedelta`][pandas.Timedelta]), or as a fraction of
    seismogram length ([`float`][] between `0` and `1`). Internally, absolute
    durations are converted to fractions by dividing by the total seismogram
    duration, and absolute durations should therefore not exceed the total
    seismogram duration.

    The shape of the windowing function is calculated by calling the scipy
    [`get_window()`][scipy.signal.windows.get_window] function using the number
    of samples corresponding to the fraction specified above, then it is split
    in half and applied to the beginning and end of the seismogram data. Thus
    `taper_width=0` corresponds to a rectangular window (i.e. no tapering), and
    `taper_width=1` to a symmetric taper applied to the entire length of the
    seismogram. A value of e.g. `0.5` applies the "ramp up" portion of the
    window to the first quarter of the seismogram, while the "ramp down" portion
    of the window is applied to the last quarter.

    Warning:
        The scipy [`get_window()`][scipy.signal.windows.get_window] function
        is a helper function that calculates a large variety of window shapes,
        which do not all make sense in this application (e.g. boxcar or tukey).
        Users are encouraged to read the documentation of the actual window
        functions available via
        [`get_window()`][scipy.signal.windows.get_window] to see if they can be
        split in the middle and used as "ramp up" and "ramp down" functions.

    Args:
        seismogram: Seismogram object.
        taper_width: Width of the taper to use.
        window_type: Function to calculate taper shape (see
            [`get_window`][scipy.signal.windows.get_window] for valid inputs).
        clone: Operate on a clone of the input seismogram.

    Returns:
        Tapered [`Seismogram`][pysmo.Seismogram] object if called with `clone=True`.

    Note:
        If `taper_width` resolves to fewer than 2 samples, no taper is applied.
        This can occur when a very small [`Timedelta`][pandas.Timedelta] is
        provided.

    Examples:
        ```python
        >>> from pysmo.functions import taper, detrend
        >>> from pysmo.classes import SAC
        >>> sac_seis = SAC.from_file("example.sac").seismogram
        >>> detrend(sac_seis)
        >>> sac_seis.data
        array([   821.53861155,    661.55931267,    511.58001379, ...,
               -32931.93353333, -21859.9128322 , -10747.89213108], shape=(57465,))
        >>> taper(sac_seis, 0.2)
        >>> sac_seis.data
        array([ 0.00000000e+00,  4.94398663e-05,  1.52926246e-04, ...,
               -9.84431924e-03, -1.63364213e-03, -0.00000000e+00], shape=(57465,))
        >>>
        ```
    """

    nsamples: int
    if isinstance(taper_width, pd.Timedelta):
        nsamples = taper_width // seismogram.delta
    else:
        nsamples = floor(len(seismogram.data) * taper_width)

    if nsamples > len(seismogram.data):
        raise ValueError(
            "'taper_width' is too large. Total taper width exceeds the duration of the seismogram."
        )

    if clone is True:
        seismogram = deepcopy(seismogram)

    # Need at least 2 samples to apply a taper
    if nsamples >= 2:
        window = scipy.signal.windows.get_window(window_type, nsamples, fftbins=False)
        ramp_samples = nsamples // 2
        seismogram.data[:ramp_samples] *= window[:ramp_samples]
        seismogram.data[-ramp_samples:] *= window[-ramp_samples:]

    if clone is True:
        return seismogram
    return None