API reference¶

def channel(self, name: ChannelRef) -> ChannelRecord:
    """
    Look up a channel by name.

    Parameters
    ----------
    name : str or tuple of (str, int)
        A plain channel name, or `(name, occurrence)`
        (`occurrence` a 0-based index into every channel sharing
        that name, in `.channels` order) to pick a specific one
        explicitly rather than relying on `name` alone being
        unambiguous.

    Returns
    -------
    ChannelRecord
        The matching channel.

    Raises
    ------
    KeyError
        If no channel has this name.
    ValueError
        If more than one channel shares this name and no
        `occurrence` was given -- a real, if unusual, on-disk
        possibility (confirmed for real on a sample file with two
        channels each named `UTC`, `RADAR`, and `RAWMAG`), for
        which there's no file-wide way to pick the "right" one
        without a line to disambiguate against. `read()` already
        disambiguates this automatically using line context (see
        `_resolve_channel_on_line`).
    """
    if self._channels_by_name is None:
        self.channels  # populate the cache
    if isinstance(name, tuple):
        actual_name, occurrence = name
        return self._nth_by_name(self._channels_by_name, actual_name, occurrence, "channel")
    matches = self._channels_by_name.get(name)
    if not matches:
        raise KeyError(f"{self.path}: no channel named {name!r}")
    if len(matches) > 1:
        raise ValueError(
            f"{self.path}: {len(matches)} channels are named {name!r} -- "
            f"ambiguous without a line to disambiguate against; use "
            f"read(line, name) (which resolves this using the line's "
            f"own data), pass (name, occurrence) to pick a specific "
            f"one explicitly, or pick a ChannelRecord from .channels "
            f"yourself"
        )
    return matches[0]

def channels_on_line(self, line: LineRef) -> List[str]:
    """
    Names of channels that actually have data on `line`.

    Parameters
    ----------
    line : str or tuple or LineRecord
        A line name, a `(name, occurrence)` pair (see `line()`),
        or a `LineRecord`.

    Returns
    -------
    list of str
        Channel names with a real data blob recorded for `line` --
        the format stores a sparse (line, channel) grid
        (docs/spec.md section 1), so most lines only populate a
        subset of this file's full channel list. If two channels
        share a name and both have data on this line, that name
        appears twice here (a list, so nothing is silently
        dropped) -- use `iter_line()` instead if you need the
        actual `ChannelRecord` for each entry, not just its name.
    """
    line_rec = self._resolve_line(line)
    return [c.name for c, _blob in self._channels_with_data_on_line(line_rec)]

def close(self) -> None:
    """Close the underlying file handle. Safe to call more than once."""
    self._file.close()

def iter_line(self, line: LineRef) -> Iterator[Tuple[ChannelRecord, np.ndarray]]:
    """
    Iterate every channel's data on one line.

    Parameters
    ----------
    line : str or tuple or LineRecord
        A line name, a `(name, occurrence)` pair, or a `LineRecord`.

    Yields
    ------
    channel : ChannelRecord
        The channel itself, not just its name -- deliberately, so
        that if two channels share a name and both have data on
        this line, both still come through as distinct,
        fully-identified entries. `dict(db.iter_line(line))` keyed
        by the records themselves preserves that; collapsing to
        `channel.name` yourself reintroduces the same collision
        `read()` raises on, so do that deliberately if you do it
        at all.
    values : numpy.ndarray
        Same as `read(line, channel)` would give for that exact
        channel.

    Notes
    -----
    Uses `_channels_with_data_on_line` directly rather than one
    `read()` call per channel (saving the repeated name lookups).

    A `rayon`-based parallel batch decoder was tried for this and
    removed: benchmarked against this project's real sample
    corpus, it was consistently ~3x *slower* than plain sequential
    calls at every scale tried, since this format's chunks are
    small enough that the Rust decoder (`pygdb._native`) already
    finishes each one in a fraction of a millisecond -- not enough
    work per chunk to amortize rayon's per-task dispatch cost. See
    `rust/src/lib.rs`'s module doc for the full note.
    """
    line_rec = self._resolve_line(line)
    for c, blob in self._channels_with_data_on_line(line_rec):
        values = read_blob_values(
            self.path, blob, c,
            comp_level=self.comp_level or 0, page_size=self.page_size,
            file=self._file,
        )
        yield c, values

def line(self, name: LineRef) -> LineRecord:
    """
    Look up a line by name.

    Parameters
    ----------
    name : str or tuple of (str, int)
        A plain line name, or `(name, occurrence)` (`occurrence` a
        0-based index into every line sharing that name, in
        `.lines` order) to pick a specific one explicitly.

    Returns
    -------
    LineRecord
        The matching line.

    Raises
    ------
    KeyError
        If no line has this name.
    ValueError
        If more than one line shares this name and no `occurrence`
        was given -- the line table has the same on-disk shape as
        the channel table (see `channel()`), with nothing in the
        format forbidding a duplicate name there either; not yet
        observed on a real file, but handled the same way on
        principle rather than left as a silent last-one-wins
        lookup.
    """
    if self._lines_by_name is None:
        self.lines  # populate the cache
    if isinstance(name, tuple):
        actual_name, occurrence = name
        return self._nth_by_name(self._lines_by_name, actual_name, occurrence, "line")
    matches = self._lines_by_name.get(name)
    if not matches:
        raise KeyError(f"{self.path}: no line named {name!r}")
    if len(matches) > 1:
        raise ValueError(
            f"{self.path}: {len(matches)} lines are named {name!r} -- "
            f"ambiguous; pass (name, occurrence) to pick a specific "
            f"one explicitly, or pick a LineRecord from .lines yourself"
        )
    return matches[0]

def read(self, line: LineRef, channel: ChannelRef) -> np.ndarray:
    """
    Random access by name: decode every value recorded for `channel` on `line`.

    Parameters
    ----------
    line : str or tuple or LineRecord
        A line name, a `(name, occurrence)` pair, or a `LineRecord`.
    channel : str or tuple or ChannelRecord
        A channel name, a `(name, occurrence)` pair, or a
        `ChannelRecord`.

    Returns
    -------
    numpy.ndarray
        1-D for an ordinary scalar channel, 2-D `(n_rows,
        channel.array_width)` for a VA/array channel (docs/spec.md
        section 5), dtype matching the channel's `GS_*` type, or a
        fixed-width Unicode dtype for a string-typed channel.

    Raises
    ------
    KeyError
        If `line` or `channel` isn't a name this file has.
    ValueError
        If `channel` is a plain name shared by more than one
        channel (see `channel()`) and it's *still* ambiguous after
        resolving it using `line`'s own data
        (`_resolve_channel_on_line`) -- i.e. more than one
        same-named channel has data on this exact line. Pass
        `(name, occurrence)` or a specific `ChannelRecord` to
        sidestep either lookup.

    Warns
    -----
    GDBParseWarning
        Per `read_blob_values`, if `line`/`channel` are valid
        names but this specific (line, channel) pair has no data
        blob, or its data can't be decoded -- an empty array is
        returned rather than raising, consistent with the rest of
        this package's degrade-gracefully philosophy for
        decode-time problems, as opposed to a plain lookup-by-name
        mistake (which does raise).
    """
    line_rec = self._resolve_line(line)
    if isinstance(channel, ChannelRecord):
        chan_rec = channel
        blob = self._ensure_blob_index().get((line_rec.index, chan_rec.index))
    elif isinstance(channel, tuple):
        chan_rec = self.channel(channel)
        blob = self._ensure_blob_index().get((line_rec.index, chan_rec.index))
    else:
        chan_rec, blob = self._resolve_channel_on_line(line_rec, channel)
    if blob is None:
        warnings.warn(
            f"{self.path}: no data blob for line {line_rec.name!r}, "
            f"channel {chan_rec.name!r} -- this (line, channel) pair "
            f"was likely never recorded (the format's grid is sparse, "
            f"docs/spec.md section 1)",
            GDBParseWarning, stacklevel=2,
        )
        return np.array([])
    return read_blob_values(
        self.path, blob, chan_rec,
        comp_level=self.comp_level or 0, page_size=self.page_size,
        file=self._file,
    )

def to_dataframe(self, line: Optional[LineRef] = None) -> "pd.DataFrame":
    """
    Build a `pandas.DataFrame` -- one row per station.

    Needs the optional `pandas` dependency (`pip install
    python-gdb[pandas]`), imported lazily here so importing
    `pygdb` itself never requires it.

    Parameters
    ----------
    line : str, int, or LineRecord, optional
        If given, scope the export to that one line only,
        mirroring `to_xarray(line)`'s exact scope. `df.attrs` gets
        `line_name`, `line_category` (`line_rec.category_name`),
        and `path` -- the same three keys `to_xarray`'s
        `Dataset.attrs` carries -- rather than a `"line"` column,
        since every row already belongs to the one given line.

        If omitted (the default), export every line with real
        data, concatenated into one table -- `"line"`/
        `"line_category"` columns are added so rows from different
        lines stay distinguishable (`pandas.DataFrame.attrs` is a
        single, frame-level dict, not one per line, so it can't
        hold this the way single-line mode's `df.attrs` does). See
        Warns for what happens if a real channel collides with one
        of these two reserved names.

    Returns
    -------
    pandas.DataFrame

    Raises
    ------
    ImportError
        If the optional `pandas` dependency isn't installed.

    Warns
    -----
    GDBParseWarning
        In whole-file mode, if a real channel collides with the
        reserved `"line"`/`"line_category"` column names --
        confirmed real, not hypothetical: a real Ontario sample
        file has a channel literally named `"line"` -- in which
        case the *channel's* own column is renamed
        `f"channel_{name}"` rather than silently overwriting the
        reserved column every whole-file caller relies on to tell
        rows apart. Also raised for a duplicate channel name (see
        Notes) and a row-count mismatch (see Notes).

    Notes
    -----
    A VA/array channel (docs/spec.md section 5) is exported as one
    column per element, `f"{name}[{j}]"` for `j` in
    `range(array_width)` -- the same flattening `to_geoh5` uses,
    for the same reason: there's no natural "one cell holds an
    array" representation in a plain 2D table.

    If two channels share a name and both have data on a line, the
    second (and any later) occurrence's column is disambiguated as
    `f"{name}[{occurrence}]"`, identical numbering to `to_xarray`/
    `to_geoh5` (see `_disambiguate_names`).

    If channels on one line don't all decode to the same row count
    (a truncated/corrupt file), the short channel's column is
    padded with missing values out to the max row count across
    that line's channels, rather than being dropped or forcing
    other channels to truncate to match -- see `_pad_to_length`'s
    docstring for why padding, specifically, is the right default
    here where it wasn't for `to_xarray`/`to_geoh5`. A channel
    entirely absent on one line in whole-file mode (present on
    some lines, not others -- a normal, sparse case, docs/spec.md
    section 1) needs no special handling here: it's simply missing
    from that line's own per-line frame, and `pandas.concat`'s
    ordinary union-of-columns behavior fills the gap with missing
    values across the whole table -- no warning, since a channel
    simply not being on a line is the format's normal baseline,
    not a sign of trouble.
    """
    try:
        import pandas as pd
    except ImportError as e:
        raise ImportError(
            "to_dataframe() needs the optional 'pandas' dependency -- "
            "install with `pip install python-gdb[pandas]`"
        ) from e

    whole_file = line is None
    line_recs = self.lines if whole_file else [self._resolve_line(line)]

    frames = []
    for line_rec in line_recs:
        pairs = self._channels_with_data_on_line(line_rec)
        if not pairs:
            continue

        decoded = [
            (c, read_blob_values(
                self.path, blob, c,
                comp_level=self.comp_level or 0, page_size=self.page_size,
                file=self._file,
            ))
            for c, blob in pairs
        ]
        row_count = max((len(values) for _c, values in decoded), default=0)

        columns: Dict[str, object] = {}
        if whole_file:
            columns["line"] = [line_rec.name] * row_count
            columns["line_category"] = [line_rec.category_name] * row_count

        for var_name, c, values in self._disambiguate_names(line_rec, decoded):
            if var_name in columns:
                # A real channel can collide with "line"/"line_category"
                # (confirmed real: a real Ontario file has a channel
                # literally named "line") -- caught here generically,
                # not just for those two names, since any future
                # reserved column would hit the same hazard. Rename the
                # channel's own column rather than silently letting it
                # overwrite the reserved one.
                original = var_name
                var_name = f"channel_{var_name}"
                warnings.warn(
                    f"{self.path}: line {line_rec.name!r} has a channel "
                    f"named {original!r}, which collides with a column "
                    f"name this method already uses -- using {var_name!r} "
                    f"for this channel's own data instead",
                    GDBParseWarning, stacklevel=2,
                )
            if c.is_array:
                for j in range(c.array_width):
                    columns[f"{var_name}[{j}]"] = self._pad_to_length(
                        values[:, j], row_count, line_rec, c, f"{var_name}[{j}]", pd,
                    )
            else:
                columns[var_name] = self._pad_to_length(
                    values, row_count, line_rec, c, var_name, pd,
                )
        frames.append(pd.DataFrame(columns))

    if not frames:
        return pd.DataFrame()

    df = pd.concat(frames, ignore_index=True)
    if not whole_file:
        line_rec = line_recs[0]
        df.attrs = {
            "line_name": line_rec.name,
            "line_category": line_rec.category_name,
            "path": self.path,
        }
    return df

def to_geoh5(
    self,
    path: str,
    *,
    x_channel: Optional[str] = None,
    y_channel: Optional[str] = None,
    z_channel: Optional[str] = None,
) -> None:
    """
    Export every line's data to a new `.geoh5` file at `path`.

    One `Points` object per line (holding real per-line data,
    i.e. it has at least one channel with data), grouped under one
    `ContainerGroup` named after this `.gdb` file, inside a
    `geoh5py.Workspace`. Needs the optional `geoh5py` dependency
    (`pip install python-gdb[geoh5]`), imported lazily here so
    importing `pygdb` itself never requires it.

    Unlike `to_xarray` (one line, in memory, no geometry needed),
    this is whole-file and writes directly to disk, since a
    `geoh5py.Workspace` is inherently file-backed and `.geoh5`'s own
    natural unit is one file holding a whole survey's worth of named
    objects, not one line at a time.

    Parameters
    ----------
    path : str
        Path to the `.geoh5` file to create (or append to --
        opened with `Workspace(path, mode="a")`).
    x_channel, y_channel, z_channel : str, optional
        Name the channels providing each line's `Points.vertices`.
        Left unset (`None`, the default for all three), this first
        tries `self.coordinate_channels` -- this file's own
        internal registry of which real channel plays which
        coordinate role (docs/provenance/notes.md section 6.8b),
        directly decoded, not guessed -- confirmed present and
        correct on 100% of this project's real sample corpus for
        X/Y. Only when that registry doesn't confirm a role does
        this fall back to the literal names `"Easting"`/
        `"Northing"` (X/Y) or no channel at all (Z, meaning every
        vertex gets `Z = 0.0`). Passing an explicit channel name
        always wins over both.

    Raises
    ------
    ImportError
        If the optional `geoh5py` dependency isn't installed.

    Warns
    -----
    GDBParseWarning
        A line missing its resolved X or Y channel is **skipped
        entirely** (no `Points` object created for it) rather than
        guessed at or defaulted to `(0, 0)` -- this reader never
        guesses what a channel means when it can't confirm one
        (see `to_xarray`'s docstring); a missing Z, by contrast, is
        normal and never blocks export. Also raised for a
        duplicate channel name (see Notes) and a row-count
        mismatch (see Notes).

    Notes
    -----
    **Array/VA channels** (docs/spec.md section 5): `.geoh5` (per
    `geoh5py`, checked directly against its real `data/` module
    source) has no `Data` type holding more than one value per
    vertex -- the plain numeric types silently `ravel()` anything
    with `ndim > 1`. So each array channel is exported as **one
    `Data` entry per column**, named `f"{name}[{j}]"` for `j` in
    `range(array_width)`, tied back together with a `PropertyGroup`
    named after the channel (`ObjectBase.add_data(...,
    property_group=name)`) -- the same "one `Data` per gate/column,
    grouped" pattern `geoh5py`'s own built-in survey types
    (`AirborneTEMSurvey` et al.) use internally for multi-gate EM
    decay-curve data, not a workaround invented here.

    **Duplicate channel names**: disambiguated exactly like
    `to_xarray` (see `_disambiguate_names`) -- `f"{name}[{occurrence}]"`
    for every occurrence after the first, same numbering as
    `channel(("name", occurrence))`.

    **Row-count mismatches**: `.geoh5` `Data` with `VERTEX`
    association must match the parent object's vertex count
    exactly -- there's no analogue to `to_xarray`'s per-channel
    dimension escape hatch. A channel that decodes to a different
    row count than this line's vertex count (from `x_channel`) is
    **skipped** (that channel only, not the whole line).

    **Not attempted**: coordinate-system/CRS export --
    `self.coordinate_systems` only returns best-effort names (no
    EPSG codes or full projection definitions), which isn't enough
    to populate `.geoh5`'s real CRS metadata correctly.
    """
    try:
        import geoh5py  # noqa: F401 -- import-only check, see below
    except ImportError as e:
        raise ImportError(
            "to_geoh5() needs the optional 'geoh5py' dependency -- "
            "install with `pip install python-gdb[geoh5]`"
        ) from e
    # A bare `import geoh5py` (rather than importing these submodules
    # directly inside the `try`) is what makes the dependency check
    # actually fire in every case, including when `geoh5py`'s own
    # submodules are already cached in `sys.modules` from an earlier
    # import elsewhere in the process: a `from geoh5py.groups import
    # ContainerGroup` reuses an already-imported `geoh5py.groups`
    # without re-checking `geoh5py` itself, so testing for a missing
    # dependency by monkeypatching `sys.modules["geoh5py"] = None`
    # would otherwise silently not trigger this except block.
    from geoh5py.groups import ContainerGroup
    from geoh5py.objects import Points
    from geoh5py.workspace import Workspace

    if x_channel is None or y_channel is None or z_channel is None:
        detected = self.coordinate_channels
        if x_channel is None:
            x_channel = detected["X"] or "Easting"
        if y_channel is None:
            y_channel = detected["Y"] or "Northing"
        if z_channel is None:
            z_channel = detected["Z"]  # stays None (all-zero Z) if unconfirmed

    with Workspace(path, mode="a") as ws:
        file_group = ws.create_entity(ContainerGroup, entity={"name": Path(self.path).stem})

        for line_rec in self.lines:
            pairs = self._channels_with_data_on_line(line_rec)
            if not pairs:
                continue

            decoded = [
                (c, read_blob_values(
                    self.path, blob, c,
                    comp_level=self.comp_level or 0, page_size=self.page_size,
                    file=self._file,
                ))
                for c, blob in pairs
            ]

            def _find(name):
                for c, values in decoded:
                    if c.name == name:
                        return c, values
                return None, None

            x_chan, x_values = _find(x_channel)
            y_chan, y_values = _find(y_channel)
            if x_chan is None or y_chan is None:
                missing = [n for n, c in ((x_channel, x_chan), (y_channel, y_chan)) if c is None]
                warnings.warn(
                    f"{self.path}: line {line_rec.name!r} has no data for "
                    f"{missing!r} -- can't place its points; skipping this "
                    f"line entirely (pass x_channel=/y_channel= if this file "
                    f"uses different coordinate channel names)",
                    GDBParseWarning, stacklevel=2,
                )
                continue

            n_vertices = len(x_values)
            if len(y_values) != n_vertices:
                warnings.warn(
                    f"{self.path}: line {line_rec.name!r}: {x_channel!r} decoded "
                    f"{n_vertices} row(s) but {y_channel!r} decoded "
                    f"{len(y_values)} -- can't build consistent vertices; "
                    f"skipping this line entirely",
                    GDBParseWarning, stacklevel=2,
                )
                continue

            geometry_channels = {x_chan, y_chan}
            z_values = np.zeros(n_vertices)
            if z_channel is not None:
                z_chan, found_z_values = _find(z_channel)
                if z_chan is not None and len(found_z_values) == n_vertices:
                    z_values = found_z_values
                    geometry_channels.add(z_chan)
                elif z_chan is not None:
                    warnings.warn(
                        f"{self.path}: line {line_rec.name!r}: z_channel "
                        f"{z_channel!r} decoded {len(found_z_values)} row(s), "
                        f"expected {n_vertices} -- using all-zero Z for this "
                        f"line instead",
                        GDBParseWarning, stacklevel=2,
                    )

            vertices = np.column_stack(
                [x_values, y_values, z_values]
            ).astype(float)
            points_obj = ws.create_entity(
                Points,
                entity={"name": line_rec.name, "parent": file_group, "vertices": vertices},
            )
            points_obj.add_data({
                "line_category": {"values": line_rec.category_name, "association": "OBJECT"},
            })

            for var_name, c, values in self._disambiguate_names(line_rec, decoded):
                if c in geometry_channels:
                    continue
                if var_name == "line_category":
                    # A real channel can collide with the object-
                    # level metadata key added above (confirmed
                    # real risk -- see the "line"/"line_category"
                    # collisions already found in to_dataframe/
                    # to_xarray). geoh5py's own `add_data` already
                    # auto-renames on a name clash (so this isn't a
                    # data-loss risk the way it was for a plain
                    # dict/Dataset), but it does so silently -- warn
                    # explicitly here too, for the same reason this
                    # reader warns everywhere else a name had to
                    # change unexpectedly.
                    original = var_name
                    var_name = f"channel_{var_name}"
                    warnings.warn(
                        f"{self.path}: line {line_rec.name!r} channel "
                        f"{original!r} collides with the object-level "
                        f"metadata key this method always adds -- using "
                        f"{var_name!r} for this channel's own data instead",
                        GDBParseWarning, stacklevel=2,
                    )
                if len(values) != n_vertices:
                    warnings.warn(
                        f"{self.path}: line {line_rec.name!r} channel {c.name!r} "
                        f"decoded {len(values)} row(s), expected {n_vertices} "
                        f"(this line's vertex count) -- geoh5 data must match "
                        f"the object's vertex count exactly; skipping this "
                        f"channel",
                        GDBParseWarning, stacklevel=2,
                    )
                    continue

                description = f"{c.type_name} / {c.format_name}"
                if c.is_array:
                    description += f" / {c.array_basetype_name}"
                    points_obj.add_data(
                        {
                            f"{var_name}[{j}]": {
                                "values": values[:, j],
                                "association": "VERTEX",
                                "description": description,
                            }
                            for j in range(c.array_width)
                        },
                        property_group=var_name,
                    )
                else:
                    points_obj.add_data({
                        var_name: {
                            "values": values,
                            "association": "VERTEX",
                            "description": description,
                        },
                    })

def to_xarray(self, line: Optional[LineRef] = None) -> "xr.Dataset":
    """
    Build an `xarray.Dataset`.

    Needs the optional `xarray` dependency (`pip install
    python-gdb[xarray]`), imported lazily here so importing
    `pygdb` itself never requires it.

    Parameters
    ----------
    line : str, int, or LineRecord, optional
        If given, scope the export to that one line only -- one
        data variable per channel that has data on that line,
        sharing a common `"station"` dimension. See
        `_to_xarray_one_line`'s docstring for the full single-line
        behavior (array-channel `_bin` dimensions, the `_station`
        dimension-splitting escape hatch for a row-count mismatch,
        `line_name`/`line_category` attrs).

        If omitted (the default), export every line with real
        data, stacked along a new `"line"` dimension into one
        `Dataset` -- see `_to_xarray_whole_file`'s docstring for
        how row-count mismatches and channels missing on some
        lines are filled (`NaN`/`""`/the channel's own Geosoft
        dummy value, recorded as each variable's `_FillValue`
        attr) rather than each getting its own dimension the way
        single-line mode does.

    Returns
    -------
    xarray.Dataset

    Raises
    ------
    ImportError
        If the optional `xarray` dependency isn't installed.

    Notes
    -----
    Either way, a channel name shared by more than one channel in
    this file's table is disambiguated as `f"{name}[{occurrence}]"`
    the same way, resolved **file-wide** (not per line) so a given
    channel's variable name never depends on which line(s) are
    being exported -- see `_disambiguate_names`.
    """
    try:
        import xarray as xr
    except ImportError as e:
        raise ImportError(
            "to_xarray() needs the optional 'xarray' dependency -- "
            "install with `pip install python-gdb[xarray]`"
        ) from e

    if line is not None:
        return self._to_xarray_one_line(self._resolve_line(line), xr)
    return self._to_xarray_whole_file(xr)

def line_channel(self, chans_max: int):
    """
    Decompose `blob_index` into `(line_slot_index, channel_slot_index)`.

    Parameters
    ----------
    chans_max : int
        The file's channel-table capacity (from `header_fields()`).

    Returns
    -------
    tuple of (int, int)
        `(line_slot_index, channel_slot_index)`, both 0-based
        physical slot numbers in their respective symbol tables
        (same indexing as `ChannelRecord.index` and the line table
        walked ad hoc in docs/provenance/notes.md section 6.3),
        via the formula **[CONFIRMED]** in
        docs/provenance/notes.md section 6.6:

        ::

            blob_index == line_slot_index * chans_max + channel_slot_index
    """
    return divmod(self.blob_index, chans_max)

def resolve(self, blob_index: int, blobs_by_offset: dict, first_offset: int, page_size: int):
    """
    Look up the live blob for `blob_index`.

    Parameters
    ----------
    blob_index : int
        The slot, `line_slot * chans_max + channel_slot`.
    blobs_by_offset : dict of {int : BlobHeader}
        Every blob of the chain walk, keyed by absolute `offset`.
    first_offset : int
        Absolute offset of the first blob (`blob_region_start`).
    page_size : int
        The file's page size.

    Returns
    -------
    status : str
        `"live"`: the entry's start page lands on a walked blob
        header whose `blob_index` equals `blob_index` and whose
        `n_pages` equals the entry's page count (the strict
        check). `"absent"`: the slot is all-zero. `"invalid"`: the
        slot is non-zero but fails the strict check. `"outside"`:
        `blob_index` is not a data slot at all (an administrative
        slot), so the directory says nothing about it.
    blob : BlobHeader or None
        The live blob for `"live"`, otherwise `None`.
    """
    if not 0 <= blob_index < self.data_slots:
        return DIRECTORY_OUTSIDE, None
    entry = self.entries.get(blob_index)
    if entry is None:
        return DIRECTORY_ABSENT, None
    word, n_pages = entry
    if not word & _DIRECTORY_LIVE_BIT:
        return DIRECTORY_INVALID, None
    blob = blobs_by_offset.get(first_offset + (word & _DIRECTORY_PAGE_MASK) * page_size)
    if blob is None or blob.blob_index != blob_index or blob.n_pages != n_pages:
        return DIRECTORY_INVALID, None
    return DIRECTORY_LIVE, blob