pysmo.functions

def clone_to_mini[TMini: _AnyMini](
    mini_cls: type[TMini], source: "_AnyProto", update: dict[str, Any] | None = None
) -> TMini:
    """Create a Mini class instance from a compatible object.

    Clones `source` by [copying][copy.copy] the attributes `mini_cls` defines
    from it onto a new `mini_cls` instance. Attributes present only on
    `source` are ignored, so the result can be smaller and faster to work
    with.

    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_cls` instance.

    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 onto a compatible object.
    """

    update = update or {}

    if not all(
        (hasattr(source, x.name) or x.name in update or x.default is not NOTHING)
        for x in fields(mini_cls)
    ):
        raise AttributeError(
            f"Unable to create clone: {source} not compatible with {mini_cls}."
        )

    # Omit a field the source lacks so mini_cls applies its own default:
    # passing attr.default would hand a Factory object to the constructor.
    clone_dict: dict[str, Any] = {}
    for attr in fields(mini_cls):
        if attr.name in update:
            clone_dict[attr.name] = update[attr.name]
        elif hasattr(source, attr.name):
            clone_dict[attr.name] = copy(getattr(source, attr.name))
    return mini_cls(**clone_dict)

def copy_from_mini(
    source: "_AnyMini", target: "_AnyProto", update: dict[str, Any] | None = None
) -> None:
    """Copy attributes from a Mini instance onto a compatible object.

    [Copies][copy.copy] every attribute of the `source` Mini instance onto 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 Mini
        instance from a compatible object.
    """

    update = update or {}

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

    if not all(hasattr(target, x) for x in attributes):
        raise AttributeError(
            f"Unable to copy to target: {type(target)} not compatible with {type(source)}."
        )

    for attribute in attributes:
        if attribute in update:
            setattr(target, attribute, update[attribute])
        else:
            setattr(target, attribute, copy(getattr(source, attribute)))

def crop[T: Seismogram](
    seismogram: T,
    begin_time: pd.Timestamp,
    end_time: pd.Timestamp,
    *,
    replace: bool = False,
) -> T | None:
    """Shorten a seismogram to 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.
        replace: Return a new seismogram and leave the input untouched,
            instead of modifying it in place. Not supported by every
            concrete type (see [`pysmo.functions`][]).

    Returns:
        Cropped [`Seismogram`][pysmo.Seismogram] object if called with `replace=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)

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

    if replace:
        return copy.replace(
            seismogram,  # type: ignore[arg-type]
            data=new_data.copy(),
            begin_time=new_begin_time,
        )

    seismogram.data = new_data
    seismogram.begin_time = new_begin_time
    return None

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

    Args:
        seismogram: Seismogram object.
        replace: Return a new seismogram and leave the input untouched,
            instead of modifying it in place. Not supported by every
            concrete type (see [`pysmo.functions`][]).

    Returns:
        Detrended [`Seismogram`][pysmo.Seismogram] object if called with `replace=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_
        >>>
        ```
    """
    detrended = scipy.signal.detrend(seismogram.data)

    if replace:
        return copy.replace(seismogram, data=detrended)  # type: ignore[arg-type]

    seismogram.data = detrended
    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,
    replace: bool = False,
) -> T | None:
    """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. A sub-tolerance
    positive gap is closed by concatenating the later seismogram's samples
    straight onto the preceding grid, shifting them earlier by up to
    `gap_tolerance_factor` of a sampling interval; no samples are inserted to
    span the gap.

    When `replace=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. When `replace=True`, no input seismogram
    is modified and a new merged seismogram is returned instead (not
    supported by every concrete type; see [`pysmo.functions`][]).

    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 `replace=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, and passing both raises at
            runtime too.
        gap_tolerance_factor: Maximum allowed boundary timestamp jitter between
            consecutive seismograms, as a fraction of the sampling interval.
        replace: Return a new merged seismogram and leave every input
            untouched, instead of modifying the first input in place. Not
            supported by every concrete type (see [`pysmo.functions`][]).

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

    Raises:
        ValueError: If both `delta` and `auto_delta` are given, `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], replace=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]),
        ...     sourceid="IU_ANMO_00_LHZ",
        ... )
        >>> mixed: Sequence[Seismogram] = [merged, geocsv_seis]
        >>> merged_mixed = merge(mixed, replace=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, replace=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 delta is not None and auto_delta:
        raise ValueError("delta and auto_delta are mutually exclusive.")

    if gap_tolerance_factor < 0:
        raise ValueError("gap_tolerance_factor must be non-negative.")

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

    working = 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 replace or index > 0:
                working[index] = resample(seismogram, delta, replace=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(
                    "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_begin_time = ordered[0].begin_time
    merged_data = np.concatenate(
        [ordered[0].data]
        + [
            seismogram.data[samples:]
            for seismogram, samples in zip(ordered[1:], overlap_samples[1:])
        ]
    )

    if replace:
        return copy.replace(
            working[0],  # type: ignore[arg-type]
            data=merged_data,
            begin_time=merged_begin_time,
            delta=reference_delta,
        )

    merged = cast(T, working[0])
    merged.begin_time = merged_begin_time
    merged.delta = reference_delta
    merged.data = merged_data
    return None

def normalize[T: Seismogram](
    seismogram: T,
    t1: pd.Timestamp | None = None,
    t2: pd.Timestamp | None = None,
    *,
    replace: bool = False,
) -> T | None:
    """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.
        replace: Return a new seismogram and leave the input untouched,
            instead of modifying it in place. Not supported by every
            concrete type (see [`pysmo.functions`][]).

    Returns:
        Normalised [`Seismogram`][pysmo.Seismogram] object if `replace=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:
        # +1 because time2index returns the sample nearest t2, which should
        # be included in the search window (matches crop()'s convention).
        end_index = time2index(seismogram, t2) + 1

    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 replace:
        return copy.replace(
            seismogram,  # type: ignore[arg-type]
            data=seismogram.data / abs_max,
        )

    seismogram.data /= abs_max
    return None

def pad[T: Seismogram](
    seismogram: T,
    begin_time: pd.Timestamp,
    end_time: pd.Timestamp,
    mode: "_ModeKind | _ModeFunc" = "constant",
    *,
    replace: bool = False,
    **kwargs: Any,
) -> T | None:
    """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).
        replace: Return a new seismogram and leave the input untouched,
            instead of modifying it in place. Not supported by every
            concrete type (see [`pysmo.functions`][]).
        kwargs: Keyword arguments to pass to [`numpy.pad`][].

    Returns:
        Padded [`Seismogram`][pysmo.Seismogram] object if called with `replace=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)

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

    if replace:
        if padding_needed:
            new_data = np.pad(
                seismogram.data,
                pad_width=(pad_before, pad_after),
                mode=mode,
                **kwargs,
            )
            new_begin_time = seismogram.begin_time + seismogram.delta * min(
                0, start_index
            )
        else:
            # replace=True must always hand back a fully independent object,
            # even when there is nothing to pad.
            new_data = seismogram.data.copy()
            new_begin_time = seismogram.begin_time
        return copy.replace(
            seismogram,  # type: ignore[arg-type]
            data=new_data,
            begin_time=new_begin_time,
        )

    if padding_needed:
        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 None

def resample[T: Seismogram](
    seismogram: T, delta: PositiveTimedelta, *, replace: bool = False
) -> T | None:
    """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.
        replace: Return a new seismogram and leave the input untouched,
            instead of modifying it in place. Not supported by every
            concrete type (see [`pysmo.functions`][]).

    Returns:
        Resampled [`Seismogram`][pysmo.Seismogram] object if called with `replace=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 replace:
        if delta != seismogram.delta:
            npts = int(len(seismogram.data) * seismogram.delta / delta)
            new_data = scipy.signal.resample(seismogram.data, npts)
            new_delta = delta
        else:
            # replace=True must always hand back a fully independent object,
            # even when the sampling interval is unchanged.
            new_data = seismogram.data.copy()
            new_delta = seismogram.delta
        return copy.replace(
            seismogram,  # type: ignore[arg-type]
            data=new_data,
            delta=new_delta,
        )

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

    return None