Skip to content

analogs.py

Analogs

__new__(cls, data=None, channels=None, time=None, **kwargs) special staticmethod

Analogs DataArray with channel and time dimensions used for generic signals such as EMGs, force signals or any other analog signals. analogs

Parameters:

Name Type Description Default
data Optional[Union[<built-in function array>, numpy.ndarray, xarray.core.dataarray.DataArray]]

Array to be passed to xarray.DataArray

None
channels Optional[list]

Channel names

None
time Optional[Union[<built-in function array>, list, pandas.core.series.Series]]

Time vector in seconds associated with the data parameter

None
kwargs

Keyword argument(s) to be passed to xarray.DataArray

{}

Returns:

Type Description
DataArray

Analogs xarray.DataArray with the specified data and coordinates

Example

To instantiate an Analogs with 4 channels and 100 frames filled with some random data:

import numpy as np
from pyomeca import Analogs

n_channels = 4
n_frames = 100
data = np.random.random(size=(n_channels, n_frames))
analogs = Analogs(data)

You can add the channel names:

names = ["A", "B", "C", "D"]
analogs = Analogs(data, channels=names)

And an associate time vector:

rate = 100  # Hz
time = np.arange(start=0, stop=n_frames / rate, step=1 / rate)
analogs = Analogs(data, channels=names, time=time)

Note

Calling Analogs() generate an empty array.

Source code in pyomeca/analogs.py
def __new__(
    cls,
    data: Optional[Union[np.array, np.ndarray, xr.DataArray]] = None,
    channels: Optional[list] = None,
    time: Optional[Union[np.array, list, pd.Series]] = None,
    **kwargs,
) -> xr.DataArray:
    """
    Analogs DataArray with `channel` and `time` dimensions
     used for generic signals such as EMGs, force signals or any other analog signals.
     ![analogs](/images/objects/analogs.svg)

    Arguments:
        data: Array to be passed to xarray.DataArray
        channels: Channel names
        time: Time vector in seconds associated with the `data` parameter
        kwargs: Keyword argument(s) to be passed to xarray.DataArray

    Returns:
        Analogs `xarray.DataArray` with the specified data and coordinates

    !!! example
        To instantiate an `Analogs` with 4 channels and 100 frames filled with some random data:

        ```python
        import numpy as np
        from pyomeca import Analogs

        n_channels = 4
        n_frames = 100
        data = np.random.random(size=(n_channels, n_frames))
        analogs = Analogs(data)
        ```

        You can add the channel names:

        ```python
        names = ["A", "B", "C", "D"]
        analogs = Analogs(data, channels=names)
        ```

        And an associate time vector:

        ```python
        rate = 100  # Hz
        time = np.arange(start=0, stop=n_frames / rate, step=1 / rate)
        analogs = Analogs(data, channels=names, time=time)
        ```

    !!! note
        Calling `Analogs()` generate an empty array.
    """
    coords = {}
    if data is None:
        data = np.ndarray((0, 0))
    if channels is not None:
        coords["channel"] = channels
    if time is not None:
        coords["time"] = time
    return xr.DataArray(
        data=data,
        dims=("channel", "time"),
        coords=coords,
        name="analogs",
        **kwargs,
    )

from_c3d(filename, usecols=None, prefix_delimiter=None, suffix_delimiter=None, attrs=None) classmethod

Analogs DataArray from a c3d file.

Parameters:

Name Type Description Default
filename Union[str, pathlib.Path]

Any valid string path

required
usecols Optional[List[Union[str, int]]]

All elements must either be positional or strings that correspond to column names. For example, a valid list-like usecols parameter would be [0, 1, 2] or ['foo', 'bar', 'baz'].

None
prefix_delimiter Optional[str]

Delimiter that split each column name by its prefix (we keep only the column name)

None
suffix_delimiter Optional[str]

Delimiter that split each column name by its suffix (we keep only the column name)

None
attrs Optional[dict]

attrs to be passed to xr.DataArray

None

Returns:

Type Description
DataArray

Analogs xarray.DataArray with the specified data and coordinates

Example

To read this c3d file, type:

from pyomeca import Analogs

data_path = "./tests/data/markers_analogs.c3d"
analogs = Analogs.from_c3d(data_path)

If you know the channel names, you can retrieve only the ones you are interested in:

channels = ["Voltage.1", "Voltage.2", "Voltage.3"]
analogs = Analogs.from_c3d(data_path, usecols=channels)

Sometimes the channel name is delimited by a suffix or prefix. To access the prefix, you can specify prefix_delimiter and suffix_delimiter for the suffix. For example, if the name is "Voltage.1" and you specify suffix_delimiter=".", you will select "Voltage". Similarly, if you specify `prefix_delimiter=".":

channels = ["1", "2", "3"]
analogs = Analogs.from_c3d(data_path, usecols=channels, prefix_delimiter=".")
Source code in pyomeca/analogs.py
@classmethod
def from_c3d(
    cls,
    filename: Union[str, Path],
    usecols: Optional[List[Union[str, int]]] = None,
    prefix_delimiter: Optional[str] = None,
    suffix_delimiter: Optional[str] = None,
    attrs: Optional[dict] = None,
) -> xr.DataArray:
    """
    Analogs DataArray from a c3d file.

    Arguments:
        filename: Any valid string path
        usecols: All elements must either be positional or strings that correspond to column names.
            For example, a valid list-like usecols parameter would be [0, 1, 2] or ['foo', 'bar', 'baz'].
        prefix_delimiter: Delimiter that split each column name by its prefix (we keep only the column name)
        suffix_delimiter: Delimiter that split each column name by its suffix (we keep only the column name)
        attrs: attrs to be passed to xr.DataArray

    Returns:
        Analogs `xarray.DataArray` with the specified data and coordinates

    !!! example
        To read [this c3d file](https://github.com/pyomeca/pyomeca/blob/master/tests/data/markers_analogs.c3d),
        type:

        ```python
        from pyomeca import Analogs

        data_path = "./tests/data/markers_analogs.c3d"
        analogs = Analogs.from_c3d(data_path)
        ```

        If you know the channel names, you can retrieve only the ones you are interested in:

        ```python
        channels = ["Voltage.1", "Voltage.2", "Voltage.3"]
        analogs = Analogs.from_c3d(data_path, usecols=channels)
        ```

        Sometimes the channel name is delimited by a suffix or prefix.
        To access the prefix, you can specify `prefix_delimiter` and `suffix_delimiter` for the suffix.
        For example, if the name is `"Voltage.1"` and you specify `suffix_delimiter="."`, you will select "Voltage".
        Similarly, if you specify `prefix_delimiter=".":

        ```python
        channels = ["1", "2", "3"]
        analogs = Analogs.from_c3d(data_path, usecols=channels, prefix_delimiter=".")
        ```
    """
    return read.read_c3d(
        cls, filename, usecols, prefix_delimiter, suffix_delimiter, attrs
    )

from_csv(filename, usecols=None, header=None, first_row=0, first_column=None, time_column=None, trailing_columns=None, prefix_delimiter=None, suffix_delimiter=None, skip_rows=None, pandas_kwargs=None, attrs=None) classmethod

Analogs DataArray from a csv file.

Parameters:

Name Type Description Default
filename Union[str, pathlib.Path]

Any valid string path

required
usecols Optional[List[Union[str, int]]]

All elements must either be positional or strings that correspond to column names. For example, a valid list-like usecols parameter would be [0, 1, 2] or ['foo', 'bar', 'baz']

None
header Optional[int]

Row of the header (0-indexed)

None
first_row int

First row of the data (0-indexed)

0
first_column Optional[Union[str, int]]

First column of the data (0-indexed)

None
time_column Optional[Union[str, int]]

Location of the time column. If None, indices are associated

None
trailing_columns Optional[Union[str, int]]

If for some reason the csv reads extra columns, how many should be ignored

None
prefix_delimiter Optional[str]

Delimiter that split each column name by its prefix (we keep only the column name)

None
suffix_delimiter Optional[str]

Delimiter that split each column name by its suffix (we keep only the column name)

None
skip_rows Optional[List[int]]

Line numbers to skip (0-indexed)

None
pandas_kwargs Optional[dict]

Keyword arguments to be passed to pandas.read_csv

None
attrs Optional[dict]

attrs to be passed to xr.DataArray. If attrs['rate'] is provided, compute the time accordingly

None

Returns:

Type Description
DataArray

Analogs xarray.DataArray with the specified data and coordinates

Example

To read this csv file, type:

from pyomeca import Analogs

data_path = "./tests/data/analogs.csv"
analogs = Analogs.from_csv(data_path, header=3, first_row=5, first_column=2)

If you know the channel names, you can retrieve only the ones you are interested in by specifying strings:

channels = ["IM EMG1", "IM EMG2", "IM EMG3"]
analogs = Analogs.from_csv(
    data_path, header=3, first_row=5, first_column=2, usecols=channels
)

Or by position:

channels = [5, 6, 7]
analogs = Analogs.from_csv(
    data_path, header=3, first_row=5, first_column=2, usecols=channels
)

Sometimes the channel name is delimited by a suffix or prefix. To access the prefix, you can specify prefix_delimiter and suffix_delimiter for the suffix. For example, if the name is "IM EMG1" and you specify suffix_delimiter=" ", you will select "IM". Similarly, if you specify `prefix_delimiter=" ":

channels = ["EMG1", "EMG2", "EMG3"]
analogs = Analogs.from_csv(
    data_path,
    header=3,
    first_row=5,
    first_column=2,
    usecols=channels,
    suffix_delimiter=" ",
)

It is also possible to specify a column containing the time vector:

analogs = Analogs.from_csv(
    data_path, header=3, first_row=5, first_column=1, time_column=0
)
Source code in pyomeca/analogs.py
@classmethod
def from_csv(
    cls,
    filename: Union[str, Path],
    usecols: Optional[List[Union[str, int]]] = None,
    header: Optional[int] = None,
    first_row: int = 0,
    first_column: Optional[Union[str, int]] = None,
    time_column: Optional[Union[str, int]] = None,
    trailing_columns: Optional[Union[str, int]] = None,
    prefix_delimiter: Optional[str] = None,
    suffix_delimiter: Optional[str] = None,
    skip_rows: Optional[List[int]] = None,
    pandas_kwargs: Optional[dict] = None,
    attrs: Optional[dict] = None,
) -> xr.DataArray:
    """
    Analogs DataArray from a csv file.

    Arguments:
        filename: Any valid string path
        usecols: All elements must either be positional or strings that correspond to column names.
            For example, a valid list-like usecols parameter would be [0, 1, 2] or ['foo', 'bar', 'baz']
        header: Row of the header (0-indexed)
        first_row: First row of the data (0-indexed)
        first_column: First column of the data (0-indexed)
        time_column: Location of the time column. If None, indices are associated
        trailing_columns: If for some reason the csv reads extra columns, how many should be ignored
        prefix_delimiter: Delimiter that split each column name by its prefix (we keep only the column name)
        suffix_delimiter: Delimiter that split each column name by its suffix (we keep only the column name)
        skip_rows: Line numbers to skip (0-indexed)
        pandas_kwargs: Keyword arguments to be passed to `pandas.read_csv`
        attrs: attrs to be passed to `xr.DataArray`. If attrs['rate'] is provided, compute the time accordingly

    Returns:
        Analogs `xarray.DataArray` with the specified data and coordinates

    !!! example
        To read [this csv file](https://github.com/pyomeca/pyomeca/blob/master/tests/data/analogs.csv),
        type:

        ```python
        from pyomeca import Analogs

        data_path = "./tests/data/analogs.csv"
        analogs = Analogs.from_csv(data_path, header=3, first_row=5, first_column=2)
        ```

        If you know the channel names, you can retrieve only the ones you are interested in by specifying strings:

        ```python
        channels = ["IM EMG1", "IM EMG2", "IM EMG3"]
        analogs = Analogs.from_csv(
            data_path, header=3, first_row=5, first_column=2, usecols=channels
        )
        ```

        Or by position:

        ```python
        channels = [5, 6, 7]
        analogs = Analogs.from_csv(
            data_path, header=3, first_row=5, first_column=2, usecols=channels
        )
        ```

        Sometimes the channel name is delimited by a suffix or prefix.
        To access the prefix, you can specify `prefix_delimiter` and `suffix_delimiter` for the suffix.
        For example, if the name is `"IM EMG1"` and you specify `suffix_delimiter=" "`, you will select "IM".
        Similarly, if you specify `prefix_delimiter=" ":

        ```python
        channels = ["EMG1", "EMG2", "EMG3"]
        analogs = Analogs.from_csv(
            data_path,
            header=3,
            first_row=5,
            first_column=2,
            usecols=channels,
            suffix_delimiter=" ",
        )
        ```

        It is also possible to specify a column containing the time vector:

        ```python
        analogs = Analogs.from_csv(
            data_path, header=3, first_row=5, first_column=1, time_column=0
        )
        ```
    """
    return read.read_csv_or_excel(
        cls,
        "csv",
        filename,
        usecols,
        header,
        first_row,
        first_column,
        time_column,
        trailing_columns,
        prefix_delimiter,
        suffix_delimiter,
        skip_rows,
        pandas_kwargs,
        attrs,
    )

from_excel(filename, sheet_name=0, usecols=None, header=None, first_row=0, first_column=None, time_column=None, trailing_columns=None, prefix_delimiter=None, suffix_delimiter=None, skip_rows=None, pandas_kwargs=None, attrs=None) classmethod

Analogs DataArray from a excel file.

Parameters:

Name Type Description Default
filename Union[str, pathlib.Path]

Any valid string path

required
sheet_name Union[str, int]

Strings are used for sheet names. Integers are used in zero-indexed sheet positions

0
usecols Optional[List[Union[str, int]]]

All elements must either be positional or strings that correspond to column names. For example, a valid list-like usecols parameter would be [0, 1, 2] or ['foo', 'bar', 'baz']

None
header Optional[int]

Row of the header (0-indexed)

None
first_row int

First row of the data (0-indexed)

0
first_column Optional[Union[str, int]]

First column of the data (0-indexed)

None
time_column Optional[Union[str, int]]

Location of the time column. If None, indices are associated

None
trailing_columns Optional[Union[str, int]]

If for some reason the csv reads extra columns, how many should be ignored

None
prefix_delimiter Optional[str]

Delimiter that split each column name by its prefix (we keep only the column name)

None
suffix_delimiter Optional[str]

Delimiter that split each column name by its suffix (we keep only the column name)

None
skip_rows Optional[List[int]]

Line numbers to skip (0-indexed)

None
pandas_kwargs Optional[dict]

Keyword arguments to be passed to pandas.read_excel

None
attrs Optional[dict]

attrs to be passed to xr.DataArray. If attrs['rate'] is provided, compute the time accordingly

None

Returns:

Type Description
DataArray

Analogs xarray.DataArray with the specified data and coordinates

Example

To read this excel file, type:

from pyomeca import Analogs

data_path = "./tests/data/analogs.xlsx"
analogs = Analogs.from_excel(data_path, header=3, first_row=5, first_column=2)

If you know the channel names, you can retrieve only the ones you are interested in by specifying strings:

channels = ["A"]
analogs = Analogs.from_excel(
    data_path, header=3, first_row=5, first_column=2, usecols=channels
)

Or by position:

channels = [1]
analogs = Analogs.from_excel(
    data_path, header=3, first_row=5, first_column=2, usecols=channels
)

It is also possible to specify a column containing the time vector:

analogs = Analogs.from_excel(
    data_path, header=3, first_row=5, first_column=1, time_column=0
)
Source code in pyomeca/analogs.py
@classmethod
def from_excel(
    cls,
    filename: Union[str, Path],
    sheet_name: Union[str, int] = 0,
    usecols: Optional[List[Union[str, int]]] = None,
    header: Optional[int] = None,
    first_row: int = 0,
    first_column: Optional[Union[str, int]] = None,
    time_column: Optional[Union[str, int]] = None,
    trailing_columns: Optional[Union[str, int]] = None,
    prefix_delimiter: Optional[str] = None,
    suffix_delimiter: Optional[str] = None,
    skip_rows: Optional[List[int]] = None,
    pandas_kwargs: Optional[dict] = None,
    attrs: Optional[dict] = None,
) -> xr.DataArray:
    """
    Analogs DataArray from a excel file.

    Arguments:
        filename: Any valid string path
        sheet_name: Strings are used for sheet names. Integers are used in zero-indexed sheet positions
        usecols: All elements must either be positional or strings that correspond to column names.
            For example, a valid list-like usecols parameter would be [0, 1, 2] or ['foo', 'bar', 'baz']
        header: Row of the header (0-indexed)
        first_row: First row of the data (0-indexed)
        first_column: First column of the data (0-indexed)
        time_column: Location of the time column. If None, indices are associated
        trailing_columns: If for some reason the csv reads extra columns, how many should be ignored
        prefix_delimiter: Delimiter that split each column name by its prefix (we keep only the column name)
        suffix_delimiter: Delimiter that split each column name by its suffix (we keep only the column name)
        skip_rows: Line numbers to skip (0-indexed)
        pandas_kwargs: Keyword arguments to be passed to `pandas.read_excel`
        attrs: attrs to be passed to `xr.DataArray`. If attrs['rate'] is provided, compute the time accordingly

    Returns:
        Analogs `xarray.DataArray` with the specified data and coordinates

    !!! example
        To read [this excel file](https://github.com/pyomeca/pyomeca/blob/master/tests/data/analogs.xlsx),
        type:

        ```python
        from pyomeca import Analogs

        data_path = "./tests/data/analogs.xlsx"
        analogs = Analogs.from_excel(data_path, header=3, first_row=5, first_column=2)
        ```

        If you know the channel names, you can retrieve only the ones you are interested in by specifying strings:

        ```python
        channels = ["A"]
        analogs = Analogs.from_excel(
            data_path, header=3, first_row=5, first_column=2, usecols=channels
        )
        ```

        Or by position:

        ```python
        channels = [1]
        analogs = Analogs.from_excel(
            data_path, header=3, first_row=5, first_column=2, usecols=channels
        )
        ```

        It is also possible to specify a column containing the time vector:

        ```python
        analogs = Analogs.from_excel(
            data_path, header=3, first_row=5, first_column=1, time_column=0
        )
        ```

    """
    return read.read_csv_or_excel(
        cls,
        "excel",
        filename,
        usecols,
        header,
        first_row,
        first_column,
        time_column,
        trailing_columns,
        prefix_delimiter,
        suffix_delimiter,
        skip_rows,
        pandas_kwargs,
        attrs,
        sheet_name,
    )

from_mot(filename, end_header=None, **kwargs) classmethod

Analogs DataArray from a mot file.

Parameters:

Name Type Description Default
filename Union[str, pathlib.Path]

Any valid string path

required
end_header Optional[bool]

Index where endheader appears (0 indexed). If not provided, the index is automatically determined.

None
kwargs

Keyword arguments to be passed to from_csv

{}

Returns:

Type Description
DataArray

Analogs xarray.DataArray with the specified data and coordinates

Example

To read this mot file, type:

from pyomeca import Analogs

data_path = "./tests/data/inverse_kin.mot"
analogs = Analogs.from_mot(data_path)

If you know the channel names, you can retrieve only the ones you are interested in by specifying strings:

channels = ["elbow_flexion", "pro_sup"]
analogs = Analogs.from_mot(data_path, usecols=channels)

Or by position:

channels = [3, 4]
analogs = Analogs.from_mot(data_path, usecols=channels)
Source code in pyomeca/analogs.py
@classmethod
def from_mot(
    cls, filename: Union[str, Path], end_header: Optional[bool] = None, **kwargs
) -> xr.DataArray:
    """
    Analogs DataArray from a mot file.

    Arguments:
        filename: Any valid string path
        end_header: Index where `endheader` appears (0 indexed). If not provided, the index is automatically determined.
        kwargs: Keyword arguments to be passed to `from_csv`

    Returns:
        Analogs `xarray.DataArray` with the specified data and coordinates

    !!! example
        To read [this mot file](https://github.com/pyomeca/pyomeca/blob/master/tests/data/inverse_kin.mot),
        type:

        ```python
        from pyomeca import Analogs

        data_path = "./tests/data/inverse_kin.mot"
        analogs = Analogs.from_mot(data_path)
        ```

        If you know the channel names, you can retrieve only the ones you are interested in by specifying strings:

        ```python
        channels = ["elbow_flexion", "pro_sup"]
        analogs = Analogs.from_mot(data_path, usecols=channels)
        ```

        Or by position:

        ```python
        channels = [3, 4]
        analogs = Analogs.from_mot(data_path, usecols=channels)
        ```
    """
    return read.read_sto_or_mot(cls, filename, end_header, **kwargs)

from_random_data(distribution='normal', size=(10, 100), **kwargs) classmethod

Create random data from a specified distribution (normal by default) using random walk.

Parameters:

Name Type Description Default
distribution str

Distribution available in numpy.random

'normal'
size tuple

Shape of the desired array

(10, 100)
kwargs

Keyword argument(s) to be passed to numpy.random.distribution

{}

Returns:

Type Description
DataArray

Random Analogs xarray.DataArray sampled from a given distribution

Example

To instantiate an Analogs with some random data sampled from a normal distribution:

from pyomeca import Analogs

n_channels = 10
n_frames = 100
size = n_channels, n_frames
analogs = Analogs.from_random_data(size=size)

You can choose any distribution available in numpy.random:

analogs = Analogs.from_random_data(distribution="uniform", size=size, low=1, high=10)
Source code in pyomeca/analogs.py
@classmethod
def from_random_data(
    cls, distribution: str = "normal", size: tuple = (10, 100), **kwargs
) -> xr.DataArray:
    """
    Create random data from a specified distribution (normal by default) using random walk.

    Arguments:
        distribution: Distribution available in
            [numpy.random](https://docs.scipy.org/doc/numpy-1.14.0/reference/routines.random.html#distributions)
        size: Shape of the desired array
        kwargs: Keyword argument(s) to be passed to numpy.random.`distribution`

    Returns:
        Random Analogs `xarray.DataArray` sampled from a given distribution

    !!! example
        To instantiate an `Analogs` with some random data sampled from a normal distribution:

        ```python
        from pyomeca import Analogs

        n_channels = 10
        n_frames = 100
        size = n_channels, n_frames
        analogs = Analogs.from_random_data(size=size)
        ```

        You can choose any distribution available in
            [numpy.random](https://docs.scipy.org/doc/numpy-1.14.0/reference/routines.random.html#distributions):

        ```python
        analogs = Analogs.from_random_data(distribution="uniform", size=size, low=1, high=10)
        ```
    """
    return Analogs(getattr(np.random, distribution)(size=size, **kwargs).cumsum(-1))

from_sto(filename, end_header=None, **kwargs) classmethod

Analogs DataArray from a sto file.

Parameters:

Name Type Description Default
filename Union[str, pathlib.Path]

Any valid string path

required
end_header Optional[bool]

Index where endheader appears (0 indexed). If not provided, the index is automatically determined

None
kwargs

Keyword arguments to be passed to from_csv

{}

Returns:

Type Description
DataArray

Analogs xarray.DataArray with the specified data and coordinates

Example

To read this sto file, type:

from pyomeca import Analogs

data_path = "./tests/data/inverse_dyn.sto"
analogs = Analogs.from_sto(data_path)

If you know the channel names, you can retrieve only the ones you are interested in by specifying strings:

channels = ["shoulder_plane_moment", "shoulder_ele_moment"]
analogs = Analogs.from_sto(data_path, usecols=channels)

Or by position:

channels = [3, 4]
analogs = Analogs.from_sto(data_path, usecols=channels)
Source code in pyomeca/analogs.py
@classmethod
def from_sto(
    cls, filename: Union[str, Path], end_header: Optional[bool] = None, **kwargs
) -> xr.DataArray:
    """
    Analogs DataArray from a sto file.

    Arguments:
        filename: Any valid string path
        end_header: Index where `endheader` appears (0 indexed).
            If not provided, the index is automatically determined
        kwargs: Keyword arguments to be passed to `from_csv`

    Returns:
        Analogs `xarray.DataArray` with the specified data and coordinates

    !!! example
        To read [this sto file](https://github.com/pyomeca/pyomeca/blob/master/tests/data/inverse_dyn.sto),
        type:

        ```python
        from pyomeca import Analogs

        data_path = "./tests/data/inverse_dyn.sto"
        analogs = Analogs.from_sto(data_path)
        ```

        If you know the channel names, you can retrieve only the ones you are interested in by specifying strings:

        ```python
        channels = ["shoulder_plane_moment", "shoulder_ele_moment"]
        analogs = Analogs.from_sto(data_path, usecols=channels)
        ```

        Or by position:

        ```python
        channels = [3, 4]
        analogs = Analogs.from_sto(data_path, usecols=channels)
        ```
    """
    return read.read_sto_or_mot(cls, filename, end_header, **kwargs)