Skip to content

visualdynamics.io.sep005

sep005

Convert between SEP 005 timeseries, the sdypy project's standard, and TimeHistory objects.

SEP 005 (SEP 5 <https://github.com/sdypy/sdypy/blob/main/docs/seps/sep-0005.rst>_) is the interchange standard of the open-source sdypy project: one plain dict per timeseries, with data shaped (n,) or (m, n), a name, per-channel unit_str, and either a sampling frequency fs or a time vector, and a list of dicts for several series. It is a standard for data in memory, not a file format, so this module converts objects and does not register a file importer. from_sep005 turns the dicts into TimeHistory objects, and TimeHistory.to_sep005 converts the other way.

This module imports nothing from sdypy; the standard is the dict.

The standard covers timeseries only, so only TimeHistory converts. FRFs, PSDs and geometry are exchanged as .vdyn or universal files.

Functions:

Name Description
from_sep005

Convert SEP 005 timeseries to TimeHistory objects.

Functions:

from_sep005 

from_sep005(timeseries: dict[str, Any] | list[dict[str, Any]]) -> Any

Convert SEP 005 timeseries to TimeHistory objects.

history = visualdynamics.from_sep005({'data': y, 'fs': 256.0,
                                      'name': 'run 4',
                                      'unit_str': 'm/s²'})

One dict returns one TimeHistory. A list, the standard's form for several series, returns {name: TimeHistory}, with a repeated name numbered 'name (2)' and so on, as in the project tree. The channels are named by channel_name, or numbered from 1 without it, and the series name becomes the comment.

A unit_str entry that parses is declared on its channel, so the values are converted to SI as define_units converts them, since the producer stated the unit. One that does not parse leaves that channel's values as they are and keeps the unit string in dimension_hint, unless the series quantity letter has already put a dimension there. Values are never scaled by a guess.

Raises ValueError, with the reason, for a series with no data, data with more than two dimensions, neither fs nor time, a time vector of the wrong length, or a channel_name list that does not match the channel count.

Parameters:

Name Type Description Default
timeseries dict or list of dict

One SEP 005 series, or a list of them.

 required

Returns:

Type Description
TimeHistory or dict of str to TimeHistory

One for one dict; for a list, every series by name.
Source code in src/visualdynamics/io/sep005.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
def from_sep005(timeseries: dict[str, Any] | list[dict[str, Any]]
                ) -> Any:
    """Convert SEP 005 timeseries to `TimeHistory` objects.

        history = visualdynamics.from_sep005({'data': y, 'fs': 256.0,
                                              'name': 'run 4',
                                              'unit_str': 'm/s²'})

    One dict returns one `TimeHistory`. A list, the standard's form for
    several series, returns ``{name: TimeHistory}``, with a repeated
    name numbered 'name (2)' and so on, as in the project tree. The
    channels are named by ``channel_name``, or numbered from 1 without
    it, and the series ``name`` becomes the comment.

    A ``unit_str`` entry that parses is declared on its channel, so the
    values are converted to SI as `define_units` converts them, since the
    producer stated the unit. One that does not parse leaves that
    channel's values as they are and keeps the unit string in
    `dimension_hint`, unless the series ``quantity`` letter has already
    put a dimension there. Values are never scaled by a guess.

    Raises ValueError, with the reason, for a series with no ``data``,
    ``data`` with more than two dimensions, neither ``fs`` nor ``time``,
    a ``time`` vector of the wrong length, or a ``channel_name`` list
    that does not match the channel count.

    Parameters
    ----------
    timeseries : dict or list of dict
        One SEP 005 series, or a list of them.

    Returns
    -------
    TimeHistory or dict of str to TimeHistory
        One for one dict; for a list, every series by name.
    """
    if isinstance(timeseries, dict):
        return _one(timeseries)
    out: dict[str, Any] = {}
    for series in timeseries:
        name = str(series.get('name', 'Time History')) or 'Time History'
        unique, n = name, 1
        while unique in out:
            n += 1
            unique = f'{name} ({n})'
        out[unique] = _one(series)
    return out