pymovements.Gaze.save#

Gaze.save(dirpath: str | Path, *, save_events: bool | None = None, save_samples: bool | None = None, save_experiment: bool | None = None, save_metadata: bool | None = None, save_messages: bool | None = None, save_calibrations: bool | None = None, save_validations: bool | None = None, verbose: int = 1, extension: str = 'feather') → Gaze[source]#

Save data from the Gaze object in the provided directory.

Depending on parameters, it may save multiple files: * preprocessed gaze in samples (samples) * calculated gaze events (events) * metadata experiment in YAML file (experiment) * additional metadata in YAML file (metadata) * messages from experiment session (messages) * calibrations data (calibrations) * validations data (validations)

Data will be saved as feather or csv files.

Returns:

Returns self, useful for method cascading.

Return type:

Gaze

Parameters:

  • dirpath (str | Path) – Absolute directory name to save data. This argument is used only for this single call and does not alter pymovements.Dataset.events_rootpath().

  • save_events (bool | None) – Save events in events.{extension} file

  • save_samples (bool | None) – Save samples in sample.{extension} file

  • save_experiment (bool | None) – Save experiment metadata in experiment.yaml file

  • save_metadata (bool | None) – Save metadata dictionary in metadata.yaml file

  • save_messages (bool | None) – Save messages in messages.{extension} file

  • save_calibrations (bool | None) – Save calibrations in calibrations.{extension} file

  • save_validations (bool | None) – Save validations in validations.{extension} file

  • verbose (int) – Verbosity level (0: no print output, 1: show progress bar, 2: print saved filepaths) (default: 1)

  • extension (str) – Extension specifies the fileformat to store the data. (default: ‘feather’)

Examples

Save all available data fields to a directory:

>>> import polars as pl
>>> from pymovements import Gaze
>>> gaze = Gaze(
...     samples=pl.DataFrame({'x': [1, 2], 'y': [3, 4]}),
...     pixel_columns=['x', 'y'],
...     metadata={'subject_id': 42},
...     messages=pl.DataFrame({'time': [0], 'content': ['start']}),
...     calibrations=pl.DataFrame({'timestamp': [0], 'num_points': [9]}),
...     validations=pl.DataFrame({'timestamp': [0], 'accuracy_avg': [0.5]}),
... )
>>> _ = gaze.save('./output', save_metadata=True, save_messages=True,
...           save_calibrations=True, save_validations=True, verbose=0)
>>> # Creates: samples.feather, events.feather, metadata.yaml,
>>> #          messages.feather, calibrations.feather, validations.feather
Raises:

  • ValueError – If save_events is True and self.events is None or empty

  • ValueError – If save_experiment is True and self.experiment is None