def calibrate_current(raw: np.ndarray, *, divisor: float = 100.0) -> np.ndarray:
    """Convert a raw probe current record to amperes.

    Parameters
    ----------
    raw : array_like
        Digitized probe signal [V].
    divisor : float, optional
        Shunt or amplifier divisor, non-zero [-].

    Returns
    -------
    np.ndarray
        Probe current [A].

    Raises
    ------
    ValueError
        The divisor is zero.

    Defaults
    --------
    ``divisor = 100.0`` is machine-specific, the VEST current divisor mirrored
    from ``vest.yaml``, and carries the same caveat as the voltage gain: a caller
    on another machine must supply its own.

    Applicability
    -------------
    Machine-independent.  The arithmetic is a scale factor; only the default
    carries a VEST number, and a caller on another machine passes its own.

    Provenance
    ----------
    .. [1] ``vest.yaml`` ``langmuir_probes`` current divisor.
    """
    if float(divisor) == 0:
        raise ValueError("calibrate_current: divisor must be non-zero")
    return np.asarray(raw, dtype=float) / float(divisor)

def calibrate_voltage(raw: np.ndarray, *, gain: float = 22.0) -> np.ndarray:
    """Convert a raw probe voltage record to physical volts.

    Parameters
    ----------
    raw : array_like
        Digitized probe signal [V].
    gain : float, optional
        Multiplicative divider gain [-].

    Returns
    -------
    np.ndarray
        Probe voltage [V].

    Defaults
    --------
    ``gain = 22.0`` is machine-specific: it is the VEST probe divider, mirrored
    from ``vest.yaml``. This module is otherwise machine-independent, so a caller
    on another machine must pass its own value rather than inherit this one.

    Applicability
    -------------
    Machine-independent.  The arithmetic is a scale factor; only the default
    carries a VEST number, and a caller on another machine passes its own.

    Provenance
    ----------
    .. [1] ``vest.yaml`` ``langmuir_probes`` voltage gain.
    """
    return np.asarray(raw, dtype=float) * float(gain)

def median_filter_signal(data: np.ndarray, kernel_size: int) -> np.ndarray:
    """Median-filter a waveform along its only axis.

    Parameters
    ----------
    data : array_like
        The waveform [any].
    kernel_size : int
        Width of the median window in samples; must be odd [-].

    Returns
    -------
    np.ndarray
        The filtered waveform, same length [any].

    Convention
    ----------
    A median filter is zero phase: it moves no feature in time, unlike a causal
    low-pass. It removes isolated spikes without the smoothing a mean filter
    applies to a real edge, which is why a probe trace uses it.

    Applicability
    -------------
    Machine-independent.

    Limitations
    -----------
    The kernel must be odd; SciPy raises otherwise. Edges are handled by zero
    padding, so the first and last half-kernel of samples are pulled toward zero.
    A feature narrower than half the kernel is removed whether or not it is noise.

    Provenance
    ----------
    .. [1] ``scipy.signal.medfilt``. Issue #152 does not record the kernel size the
       original workflow used, which is why the pipeline leaves this unset rather
       than guessing one; see :func:`process_triple_probe`.
    """
    return medfilt(np.asarray(data, dtype=float), kernel_size=int(kernel_size))

def probe_surface_area(*, tip_radius_m: float, tip_length_m: float) -> float:
    """Collection area of a cylindrical probe tip.

    Parameters
    ----------
    tip_radius_m : float
        Tip radius, strictly positive [m].
    tip_length_m : float
        Exposed tip length, strictly positive [m].

    Returns
    -------
    float
        The collecting surface area [m^2].

    Raises
    ------
    ValueError
        Either dimension is not positive.

    Convention
    ----------
    The lateral area of a cylinder, ``2*pi*r*l``. The end cap is excluded, which
    is the usual convention for a probe whose length far exceeds its radius, and
    the sheath is assumed thin enough that the collecting area is the geometric
    one.

    Applicability
    -------------
    Machine-independent.

    Limitations
    -----------
    A thick sheath at low density collects over an area larger than the geometric
    one, which this does not model; the density inferred from it is then an
    overestimate.

    Provenance
    ----------
    .. [1] The standard cylindrical-probe collection area used by the
       triple-probe density relation in :func:`electron_density`.
    """
    if tip_radius_m <= 0 or tip_length_m <= 0:
        raise ValueError("probe_surface_area: tip_radius_m and tip_length_m must be positive")
    return 2.0 * np.pi * float(tip_radius_m) * float(tip_length_m)

def remove_offset(data: np.ndarray, *, n_baseline_samples: int = 500) -> np.ndarray:
    """Subtract a signal's pre-plasma baseline, taken as its leading samples.

    Parameters
    ----------
    data : array_like
        The waveform, in whatever unit it has [any].
    n_baseline_samples : int, optional
        How many leading samples make up the baseline [-].

    Returns
    -------
    np.ndarray
        The waveform with its baseline mean removed [any].

    Raises
    ------
    ValueError
        The record is shorter than the requested baseline.

    Defaults
    --------
    ``n_baseline_samples = 500`` is an acquisition-era value carried from the VEST
    probe digitizer settings, where the leading samples precede the discharge. It
    is a sample count, not a duration, so it means a different interval on a
    different sample rate.

    Convention
    ----------
    The mean of the leading window, not a fitted trend, so a baseline that drifts
    during the shot is not removed.

    Applicability
    -------------
    Machine-independent.

    Limitations
    -----------
    Assumes the leading window is signal-free. A probe already collecting current
    at the start of the record has its baseline biased by that current.

    Provenance
    ----------
    .. [1] ``vest.yaml`` ``langmuir_probes`` processing, which carries the VEST
       sample count this default mirrors.
    """
    values = np.asarray(data, dtype=float)
    if values.size < int(n_baseline_samples):
        raise ValueError(
            f"remove_offset: need at least {n_baseline_samples} samples, got {values.size}"
        )
    baseline = float(np.mean(values[: int(n_baseline_samples)]))
    return values - baseline