pyavs.save_population_codes_h5

pyavs.save_population_codes_h5(population_codes: Dict[str, ndarray], metadata: DataFrame, subject_id: int, session: int, event_type: str = 'saccade', blocks: List[int] | None = None, times: ndarray | None = None, rois: List[str] | None = None, random_epochs: ndarray | None = None, sampling_rate: int = 500, filter_params: Dict[str, float] | None = None, data_path: str | None = None, hemi: str = 'both', compression: str = 'gzip', data_type: str = 'population_codes', chunk_epochs: int | None = 1, **kwargs) → str[source]

Save population codes to HDF5 file in standardized format.

This is the core saving function that all other save functions ultimately use. It maintains compatibility with the original analysis pipelines.

Parameters:

  • population_codes (dict) – Dictionary where keys are ROI names and values are data arrays with shape (n_epochs, n_sources, n_timepoints)

  • metadata (pd.DataFrame) – Metadata for each epoch

  • subject_id (int) – Subject ID

  • session (int) – Session number

  • event_type (str, optional) – Event type (‘saccade’, ‘fixation’, etc.) (default: ‘saccade’)

  • blocks (list of int, optional) – List of blocks processed (default: None)

  • times (np.ndarray, optional) – Time points array in seconds (default: None)

  • rois (list of str, optional) – List of ROI names (default: None, will use population_codes.keys())

  • random_epochs (np.ndarray, optional) – Indices of randomly selected epochs (default: None)

  • sampling_rate (int, optional) – Sampling rate in Hz (default: 500)

  • filter_params (dict, optional) – Filter parameters with ‘l_freq’ and ‘h_freq’ keys (default: None)

  • data_path (str, optional) – Path to data directory (default: None, uses configured path)

  • hemi (str, optional) – Hemisphere processed (‘lh’, ‘rh’, ‘both’) (default: ‘both’)

  • compression (str, optional) – HDF5 compression method (default: ‘gzip’)

  • data_type (str, optional) – Type of data being saved (default: ‘population_codes’)

  • chunk_epochs (int or None, optional) – Number of epochs per HDF5 chunk (default: 1 – one chunk spans a full epoch’s channel x time extent). Without this, h5py auto-chunks and fragments the channel/time axes too (observed on shipped data: a (2668, 204, 651) array chunked at (84, 13, 41)), so selecting an arbitrary subset of epochs – e.g. a content-filtered query across subjects – ends up touching most of the file’s chunks regardless of how few epochs are wanted. chunk_epochs=1 makes an N-epoch selection cost close to N chunk reads. Pass None to fall back to h5py’s auto-chunking (the previous, unchunked-by-epoch behavior). Larger values trade some of that partial-read benefit for a better gzip ratio (compression sees more redundancy per chunk).

  • **kwargs – Additional parameters

Returns:

Path to saved HDF5 file

Return type:

str

Notes

This function creates standardized HDF5 files for neuroscience data analysis.