Skip to content

Mini Classes

Because pysmo is built around its types rather than some all encompassing class, it doesn't have a native class that can be used with the various functions and modules that come as part of this package. As shown in the tutorial, the idea is for you to use a tailor made class for a particular use case. However, should you find yourself needing a class that has exactly the same attributes as a particular type, then pysmo has you covered with its "Mini" classes. These classes are minimal implementations of their respective types and are named accordingly (e.g. for the Seismogram type there is a MiniSeismogram class).

MiniSeismogram

To show what such a Mini class looks like we can look at the code for the MiniSeismogram class:

@beartype
@define(kw_only=True, slots=True)
class MiniSeismogram(Seismogram):
    """Minimal class for use with the [`Seismogram`][pysmo.Seismogram] type.

    The `MiniSeismogram` class provides a minimal implementation of class that
    is compatible with the [`Seismogram`][pysmo.Seismogram] type.

    Examples:
        ```python
        >>> from pysmo import MiniSeismogram, Seismogram
        >>> from datetime import datetime, timedelta, timezone
        >>> import numpy as np
        >>> now = datetime.now(timezone.utc)
        >>> delta = timedelta(seconds=0.1)
        >>> seismogram = MiniSeismogram(begin_time=now, delta=delta, data=np.random.rand(100))
        >>> isinstance(seismogram, Seismogram)
        True
        >>>
        ```
    """

    begin_time: datetime = field(
        default=SEISMOGRAM_DEFAULTS.begin_time.value, validator=datetime_is_utc
    )
    """Seismogram begin time."""

    delta: PositiveTimedelta = SEISMOGRAM_DEFAULTS.delta.value
    """Seismogram sampling interval."""

    data: np.ndarray = field(factory=lambda: np.array([]))
    """Seismogram data."""

At a first glance it looks similar to the examples in the tutorial. However, upon closer inspection you might notice some differences:

  • Instead of using the built-in dataclasses.dataclass it uses attrs.define. They look and work similarly, but we get the option to do things like validating input (here we make sure the begin_time has the expected tzinfo).
  • The delta attribute isn't a simple timedelta. Instead it uses a custom PositiveTimedelta type which is more restrictive; after all, a negative sampling interval doesn't make any sense. In combination with the beartype decorator this ensures no invalid values are accepted at runtime.
  • Some default values are provided. These will typically be replaced in real world usage, but do allow for some convenience while quickly testing things.

Example workflow

Mini classes can be instantiated directly, but it might be convenient to create an instance and populate it at the same time with data from another type. Pysmo provides two functions for this:

  • clone_to_mini creates a new Mini class instance by copying matching attributes from an existing object. Attributes present in the source but not in the Mini class are ignored, resulting in a lightweight copy of the original data.
  • copy_from_mini does the reverse: it copies attributes from a Mini class instance back to a compatible target object.

Together, these two functions enable a workflow where data are cloned into a Mini class for processing, and the results are then copied back to the original object. Here we load data from a SAC file into a MiniSeismogram, do some processing, and then copy it back:

from pysmo import MiniSeismogram
from pysmo.functions import clone_to_mini, copy_from_mini, resample
from pysmo.classes import SAC

# Read SAC file and clone it to a MiniSeismogram
sac = SAC.from_file("testfile.sac")
mini = clone_to_mini(MiniSeismogram, sac.seismogram)

# Process seismogram
resample(mini, mini.delta * 2)  # (1)!
...

# Copy processed seismogram back to the SAC file
copy_from_mini(mini, sac.seismogram)
sac.write("testfile_out.sac")
  1. We could also process sac.seismogram directly. For this example we will therefore assume the processing completes significantly faster using a MiniSeismogram...