Features
April 13, 2026 · View on GitHub
Auto-generated documentation for musicalgestures._features module.
MgFeatures – a named time-series container for motion and audio descriptors.
- Mgt-python / Modules / Musicalgestures / Features
- MgFeatures
- MgFeatures().__array__
- MgFeatures().__getitem__
- MgFeatures().__iter__
- MgFeatures().__len__
- MgFeatures().feature_names
- MgFeatures.from_dataframe
- MgFeatures.from_json
- MgFeatures().n_features
- MgFeatures().n_samples
- MgFeatures().shape
- MgFeatures().times
- MgFeatures().to_dataframe
- MgFeatures().to_json
- MgFeatures().to_numpy
- MgFeatures
class MgFeatures holds one or more named feature arrays (e.g. quantity of
motion, centroid of motion, optical flow statistics, spectral features) together
with shared metadata (sampling rate, time axis, source filename). It is the
primary data structure for feeding MGT-python analysis results into machine-
learning pipelines.
The design follows conventions established by librosa (feature arrays + sample rate) and MNE-Python (named channels + metadata dict).
Examples
>>> import numpy as np
>>> from musicalgestures._features import MgFeatures
>>> t = np.linspace(0, 10, 100)
>>> feat = MgFeatures(
... data={"qom": np.random.rand(100), "com_x": np.random.rand(100)},
... times=t,
... sr=25.0,
... source="dancer.avi",
... )
>>> feat.shape
(2, 100)
>>> arr = feat.to_numpy() # shape (2, 100)
>>> df = feat.to_dataframe() # pandas DataFrame, columns = feature names
## MgFeatures
[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_features.py#L41)
```python
class MgFeatures():
def __init__(
data: dict[str, np.ndarray],
times: np.ndarray | None = None,
sr: float = 1.0,
source: str | Path | None = None,
metadata: dict[str, Any] | None = None,
) -> None:
Named time-series container for motion and audio descriptors.
Parameters
data:
A mapping of {feature_name: 1-D numpy array}. All arrays must
have the same length (number of time samples).
times:
1-D array of time stamps in seconds corresponding to each sample.
If None, integer sample indices are used.
sr:
Sampling rate of the feature time series in Hz (frames per second
for video-derived features, Hz for audio-derived features).
source:
Path to the source file that the features were derived from.
metadata:
Optional free-form dictionary of additional metadata (parameters
used, processing chain description, etc.).
Attributes
feature_names : list[str]
Names of the features stored in this container.
n_features : int
Number of named feature channels.
n_samples : int
Number of time samples per channel.
shape : tuple[int, int]
(n_features, n_samples)
MgFeatures().__array__
def __array__(dtype=None, copy=None) -> np.ndarray:
Return a 2-D array of shape (n_features, n_samples).
MgFeatures().__getitem__
def __getitem__(key: str) -> np.ndarray:
Return a single feature array by name.
MgFeatures().__iter__
def __iter__():
Iterate over feature names.
MgFeatures().__len__
def __len__() -> int:
Return the number of feature channels.
MgFeatures().feature_names
@property
def feature_names() -> list[str]:
Names of the feature channels.
MgFeatures.from_dataframe
@classmethod
def from_dataframe(
df: pd.DataFrame,
sr: float = 1.0,
source: str | Path | None = None,
metadata: dict[str, Any] | None = None,
) -> 'MgFeatures':
Create an :class:MgFeatures from a class pandas.DataFrame.
Parameters
df: DataFrame whose columns are feature names and whose index is the time axis in seconds. sr: Sampling rate in Hz. source: Optional source file path. metadata: Optional metadata dictionary.
Returns
MgFeatures
MgFeatures.from_json
@classmethod
def from_json(path: str | Path) -> 'MgFeatures':
Load an :class:MgFeatures instance from a JSON file.
Parameters
path: Path to the JSON file previously created by :meth:MgFeatures().to_json.
Returns
MgFeatures
MgFeatures().n_features
@property
def n_features() -> int:
Number of feature channels.
MgFeatures().n_samples
@property
def n_samples() -> int:
Number of time samples per channel.
MgFeatures().shape
@property
def shape() -> tuple[int, int]:
(n_features, n_samples).
MgFeatures().times
@property
def times() -> np.ndarray:
Time axis in seconds.
MgFeatures().to_dataframe
def to_dataframe() -> pd.DataFrame:
Return features as a class pandas.DataFrame.
Returns
pd.DataFrame Columns are feature names, index is the time axis in seconds.
MgFeatures().to_json
def to_json(path: str | Path | None = None) -> str:
Serialise to JSON (with metadata).
Parameters
path: Optional file path to write the JSON to. If None, returns the JSON string.
Returns
str JSON-encoded string representation.
MgFeatures().to_numpy
def to_numpy() -> np.ndarray:
Return all features as a 2-D NumPy array (n_features, n_samples).
Returns
np.ndarray
Shape (n_features, n_samples). Row order matches
:attr:MgFeatures().feature_names.