aggregation.concatenate_channels_data

aggregation.concatenate_channels_data(parquet_files_channels, output_dir=None)

Aggregate and validate channel-level metadata from multiple probe directories into a single DataFrame.

This function reads channel information from a list of Parquet files (one per probe), validates each DataFrame against the ChannelDataFrameSchema, and concatenates them into a single DataFrame. The result is grouped by (‘pid’, ‘channel’) and the first occurrence is kept for each group. If a ‘channel_labels’ column is present, it is dropped with a warning. Optionally, the aggregated DataFrame can be saved to a Parquet file in the specified output directory.

Args: parquet_files_channels (List[pathlib.Path]): List of Path objects, each pointing to a Parquet file containing channel-level metadata for a probe. Each file must be compatible with ChannelDataFrameSchema. output_dir (Path or None, optional): If provided, the aggregated DataFrame is saved as ‘channels.pqt’ in this directory. The directory is created if it does not exist. Default is None (no file is written).

Returns: pandas.DataFrame: A DataFrame containing the concatenated and grouped channel metadata from all input files. Indexed by (‘pid’, ‘channel’).

Example: >>> from pathlib import Path >>> parquet_files = [Path(‘probe1/channels.pqt’), Path(‘probe2/channels.pqt’)] >>> df_channels = concatenate_channels_data(parquet_files, output_dir=Path(‘output’)) >>> print(df_channels.head())

Note: - Each input file is validated using ChannelDataFrameSchema.validate. - If a file lacks a ‘channel’ column, it is created from the DataFrame index. - The result is grouped by (‘pid’, ‘channel’) and the first entry is kept for each group. - If a ‘channel_labels’ column is present, it is dropped with a warning. - If output_dir is provided, the result is saved as ‘channels.pqt’ in that directory.