inspect

File inspection and metadata functions.

ChannelInfo dataclass

ChannelInfo(name: str, type: str, dtype: dtype, sample_rate: float, n_samples: int, unit: str)

Metadata about a single channel in a GWF file.

Attributes:

Name	Type	Description
name	str	Channel name (e.g., 'H1:LOSC-STRAIN')
type	str	Channel type: 'adc', 'proc', or 'sim'
dtype	dtype	NumPy dtype of the channel samples (e.g., np.dtype('float64')).
sample_rate	float	Sampling rate in Hz
n_samples	int	Number of samples in the channel
unit	str	Physical unit of the data (e.g., 'strain')

dtype_name property

dtype_name: str

Human-readable name for the data type (e.g., 'float64').

get_channel_details

get_channel_details(filename: str | PathLike[str], frame_index: int = 0) -> list[ChannelInfo]

Get detailed metadata for all channels in a GWF file.

Reads channel headers (without decompressing data) to extract sample rate, data type, sample count, and units for each channel.

Parameters:

Name	Type	Description	Default
filename	str or path - like	Path to the GWF file	required
frame_index	int	Frame index to read metadata from (default: 0)	0

Returns:

Name	Type	Description
details	list[ChannelInfo]	List of channel metadata, ordered by type (adc, proc, sim)

Examples:

>>> details = gwframe.get_channel_details('data.gwf')
>>> for ch in details:
...     print(f"{ch.name}: {ch.dtype_name} @ {ch.sample_rate} Hz")

Source code in gwframe/inspect.py

def get_channel_details(
    filename: str | PathLike[str],
    frame_index: int = 0,
) -> list[ChannelInfo]:
    """
    Get detailed metadata for all channels in a GWF file.

    Reads channel headers (without decompressing data) to extract sample rate,
    data type, sample count, and units for each channel.

    Parameters
    ----------
    filename : str or path-like
        Path to the GWF file
    frame_index : int, optional
        Frame index to read metadata from (default: 0)

    Returns
    -------
    details : list[ChannelInfo]
        List of channel metadata, ordered by type (adc, proc, sim)

    Examples
    --------
    >>> details = gwframe.get_channel_details('data.gwf')
    >>> for ch in details:
    ...     print(f"{ch.name}: {ch.dtype_name} @ {ch.sample_rate} Hz")
    """
    path = fspath(filename)
    stream = _core.IFrameFStream(path)
    toc = stream.get_toc()

    results: list[ChannelInfo] = []
    type_readers = [
        ("adc", list(toc.get_adc()), stream.read_fr_adc_data),
        ("proc", list(toc.get_proc()), stream.read_fr_proc_data),
        ("sim", list(toc.get_sim()), stream.read_fr_sim_data),
    ]

    for ch_type, ch_names, reader in type_readers:
        for ch_name in ch_names:
            fr_data = reader(frame_index, ch_name)

            sample_rate = (
                fr_data.get_sample_rate() if ch_type in ("adc", "sim") else None
            )

            vect = fr_data.get_data_vector(0)

            if sample_rate is None and vect.get_n_dim() > 0:
                dim = vect.get_dim(0)
                dx = dim.dx
                sample_rate = 1.0 / dx if dx > 0 else 0.0

            results.append(
                ChannelInfo(
                    name=ch_name,
                    type=ch_type,
                    dtype=frvect_to_dtype(vect.get_type()),
                    sample_rate=sample_rate or 0.0,
                    n_samples=vect.get_n_data(),
                    unit=vect.get_unit_y(),
                )
            )

    return results

get_channels

get_channels(filename: str | PathLike[str]) -> list[str]

Get a list of all channels in a GWF file.

Parameters:

Name	Type	Description	Default
filename	str or path - like	Path to the GWF file	required

Returns:

Name	Type	Description
channels	list[str]	List of all channel names

Examples:

>>> channels = gwframe.get_channels('data.gwf')
>>> print(f"Found {len(channels)} channels")
>>> for channel in channels:
...     print(channel)

Source code in gwframe/inspect.py

def get_channels(filename: str | PathLike[str]) -> list[str]:
    """
    Get a list of all channels in a GWF file.

    Parameters
    ----------
    filename : str or path-like
        Path to the GWF file

    Returns
    -------
    channels : list[str]
        List of all channel names

    Examples
    --------
    >>> channels = gwframe.get_channels('data.gwf')
    >>> print(f"Found {len(channels)} channels")
    >>> for channel in channels:
    ...     print(channel)
    """
    stream = _core.IFrameFStream(fspath(filename))
    toc = stream.get_toc()
    return [*toc.get_adc(), *toc.get_proc(), *toc.get_sim()]

get_channels_by_type

get_channels_by_type(filename: str | PathLike[str]) -> dict[str, list[str]]

Get channel names grouped by type (adc, proc, sim).

Parameters:

Name	Type	Description	Default
filename	str or path - like	Path to the GWF file	required

Returns:

Name	Type	Description
channels	dict[str, list[str]]	Dictionary with keys 'adc', 'proc', 'sim' mapping to channel name lists

Examples:

>>> by_type = gwframe.get_channels_by_type('data.gwf')
>>> print(f"ADC channels: {len(by_type['adc'])}")
>>> print(f"Proc channels: {len(by_type['proc'])}")

Source code in gwframe/inspect.py

def get_channels_by_type(
    filename: str | PathLike[str],
) -> dict[str, list[str]]:
    """
    Get channel names grouped by type (adc, proc, sim).

    Parameters
    ----------
    filename : str or path-like
        Path to the GWF file

    Returns
    -------
    channels : dict[str, list[str]]
        Dictionary with keys 'adc', 'proc', 'sim' mapping to channel name lists

    Examples
    --------
    >>> by_type = gwframe.get_channels_by_type('data.gwf')
    >>> print(f"ADC channels: {len(by_type['adc'])}")
    >>> print(f"Proc channels: {len(by_type['proc'])}")
    """
    stream = _core.IFrameFStream(fspath(filename))
    toc = stream.get_toc()
    return {
        "adc": list(toc.get_adc()),
        "proc": list(toc.get_proc()),
        "sim": list(toc.get_sim()),
    }

get_info

get_info(filename: str | PathLike[str]) -> FrameFileInfo

Get metadata about a GWF file.

Parameters:

Name	Type	Description	Default
filename	str or path - like	Path to the GWF file	required

Returns:

Name	Type	Description
info	FrameFileInfo	Structured metadata containing: - num_frames: number of frames in file - channels: list of all channel names - frames: list of FrameInfo objects with complete frame metadata

Examples:

>>> info = gwframe.get_info('data.gwf')
>>> print(f"File contains {info.num_frames} frames")
>>> print(f"Frame 0: {info.frames[0].name} at GPS {info.frames[0].start}")
>>> print(f"Channels: {', '.join(info.channels)}")

Source code in gwframe/inspect.py

def get_info(filename: str | PathLike[str]) -> FrameFileInfo:
    """
    Get metadata about a GWF file.

    Parameters
    ----------
    filename : str or path-like
        Path to the GWF file

    Returns
    -------
    info : FrameFileInfo
        Structured metadata containing:
        - num_frames: number of frames in file
        - channels: list of all channel names
        - frames: list of FrameInfo objects with complete frame metadata

    Examples
    --------
    >>> info = gwframe.get_info('data.gwf')
    >>> print(f"File contains {info.num_frames} frames")
    >>> print(f"Frame 0: {info.frames[0].name} at GPS {info.frames[0].start}")
    >>> print(f"Channels: {', '.join(info.channels)}")
    """
    stream = _core.IFrameFStream(fspath(filename))
    num_frames = stream.get_number_of_frames()
    toc = stream.get_toc()

    # Get all channels
    channels = [*toc.get_adc(), *toc.get_proc(), *toc.get_sim()]

    # Detect compression from first available channel in first frame
    compression = _detect_compression(stream, toc)

    # Detect frame specification version
    try:
        frame_spec = int(stream.get_version())
    except (AttributeError, RuntimeError):
        frame_spec = None

    # Read each frame header to get complete metadata
    frames = []
    for i in range(num_frames):
        # Read frame header
        frame_h = stream.read_frame_n(i)

        # Extract metadata from frame header
        time = frame_h.get_gps_time()
        gps_start = float(time.sec) + float(time.nsec) * 1e-9

        frames.append(
            FrameInfo(
                index=i,
                start=gps_start,
                duration=frame_h.get_dt(),
                name=frame_h.get_name(),
                run=frame_h.get_run(),
                frame_number=frame_h.get_frame(),
            )
        )

    return FrameFileInfo(
        num_frames=num_frames,
        channels=channels,
        frames=frames,
        compression=compression,
        frame_spec=frame_spec,
    )