rt-anchor 0.1.0__py3-none-any.whl

rt_anchor/__init__.py

@@ -0,0 +1,45 @@
+"""rt_anchor — standard-panel retention-index (iRT) calibration for LC-MS lipidomics.
+
+Unifies feature tables from MS-DIAL, MZmine, MassCube and LipidScreener, then
+warps retention time onto a dimensionless iRT scale anchored by a spiked lipid
+standard panel. Outputs are CSV / JSON / log (no visualisation).
+
+Quick start
+-----------
+>>> from rt_anchor import calibrate, write_results
+>>> res = calibrate("samples.txt", polarity="positive", standards_table="std.txt")
+>>> write_results(res, "out/run1")
+"""
+
+from __future__ import annotations
+
+from .calibrate import MonotoneWarp, apply_warp, fit_warp
+from .config import CalibrationConfig
+from .errors import (
+    AnchorIdentificationError,
+    CalibrationError,
+    ColumnResolutionError,
+    ConfigError,
+    InputFormatError,
+    PanelError,
+    RtAnchorError,
+    RTUnitError,
+)
+from .helpers import describe_input, setup_logger, which_format, write_results
+from .identify import build_native_template, identify_anchors
+from .io import FeatureTable, detect_format, load_feature_table
+from .panel import DEFAULT_MANIFEST, Panel, build_panel, load_manifest_csv, load_reference_csv
+from .pipeline import CalibrationResult, calibrate
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "calibrate", "CalibrationResult", "CalibrationConfig",
+    "load_feature_table", "detect_format", "FeatureTable",
+    "build_panel", "Panel", "DEFAULT_MANIFEST", "load_manifest_csv", "load_reference_csv",
+    "build_native_template", "identify_anchors",
+    "fit_warp", "apply_warp", "MonotoneWarp",
+    "describe_input", "which_format", "write_results", "setup_logger",
+    "RtAnchorError", "InputFormatError", "ColumnResolutionError", "RTUnitError",
+    "PanelError", "AnchorIdentificationError", "CalibrationError", "ConfigError",
+]

rt_anchor/calibrate.py

@@ -0,0 +1,149 @@
+"""The calibration itself: a monotone RT->iRT warp plus numeric uncertainty.
+
+* :class:`MonotoneWarp` — shape-preserving monotone interpolation (PCHIP) with
+  ``extrapolate=False`` so features beyond the anchor span become NaN (never a
+  fabricated value). Leave-one-anchor-out residuals give the honest in-domain
+  interpolation error.
+* :func:`apply_warp` — turn a warp + a config into per-feature ``RI``,
+  ``RI_uncertainty``, ``RI_reliability`` and ``is_extrapolated``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+import numpy as np
+import pandas as pd
+from scipy.interpolate import PchipInterpolator
+
+from .config import CalibrationConfig
+from .errors import CalibrationError
+
+
+@dataclass
+class MonotoneWarp:
+    rt: np.ndarray          # anchor observed RT (minutes), strictly increasing
+    irt: np.ndarray         # anchor iRT values
+    _pchip: PchipInterpolator
+    loo_resid: np.ndarray   # per-anchor leave-one-out residual (iRT units)
+
+    @property
+    def rt_min(self) -> float:
+        return float(self.rt[0])
+
+    @property
+    def rt_max(self) -> float:
+        return float(self.rt[-1])
+
+    def predict(self, rt_min: np.ndarray, extrapolate: bool = False,
+                max_extrap_min: float = 1.0) -> np.ndarray:
+        rt_min = np.asarray(rt_min, dtype=float)
+        out = self._pchip(rt_min)  # NaN outside [rt_min, rt_max] (extrapolate=False)
+        if extrapolate:
+            below = rt_min < self.rt_min
+            above = rt_min > self.rt_max
+            # linear terminal-slope extrapolation, capped
+            if below.any():
+                s = (self.irt[1] - self.irt[0]) / (self.rt[1] - self.rt[0])
+                d = np.clip(self.rt_min - rt_min[below], 0, max_extrap_min)
+                out[below] = self.irt[0] - s * d
+            if above.any():
+                s = (self.irt[-1] - self.irt[-2]) / (self.rt[-1] - self.rt[-2])
+                d = np.clip(rt_min[above] - self.rt_max, 0, max_extrap_min)
+                out[above] = self.irt[-1] + s * d
+        return out
+
+
+def fit_warp(anchor_rt_min: np.ndarray, anchor_irt: np.ndarray,
+             config: CalibrationConfig) -> MonotoneWarp:
+    rt = np.asarray(anchor_rt_min, dtype=float)
+    irt = np.asarray(anchor_irt, dtype=float)
+    order = np.argsort(rt)
+    rt, irt = rt[order], irt[order]
+
+    # strict-increase guard (PCHIP requires strictly increasing x)
+    keep = np.concatenate([[True], np.diff(rt) > config.tie_epsilon_min])
+    rt, irt = rt[keep], irt[keep]
+    if rt.size < max(2, config.min_anchors_hard):
+        raise CalibrationError(
+            f"Only {rt.size} usable anchors after the monotonicity guard "
+            f"(need >= {max(2, config.min_anchors_hard)}). Loosen mz_tol_ppm / RT "
+            f"window, provide a standard-panel run, or check the polarity."
+        )
+    if not np.all(np.diff(irt) > 0):
+        raise CalibrationError("Anchor iRT values are not strictly increasing — reference baseline is inconsistent.")
+
+    pchip = PchipInterpolator(rt, irt, extrapolate=False)
+    loo = _loo_residuals(rt, irt)
+    return MonotoneWarp(rt=rt, irt=irt, _pchip=pchip, loo_resid=loo)
+
+
+def _loo_residuals(rt: np.ndarray, irt: np.ndarray) -> np.ndarray:
+    """Leave-one-anchor-out residual (iRT) at each anchor; NaN for the two ends
+    (holding out an endpoint is extrapolation, not interpolation)."""
+    n = rt.size
+    res = np.full(n, np.nan)
+    for i in range(1, n - 1):  # interior only
+        m = np.ones(n, bool); m[i] = False
+        f = PchipInterpolator(rt[m], irt[m], extrapolate=True)
+        res[i] = float(f(rt[i]) - irt[i])
+    return res
+
+
+def apply_warp(rt_min: np.ndarray, warp: MonotoneWarp, config: CalibrationConfig,
+               scope: str, warp_source: str = "self") -> pd.DataFrame:
+    """Compute RI + uncertainty for an array of feature RTs (minutes)."""
+    rt_min = np.asarray(rt_min, dtype=float)
+    ri = warp.predict(rt_min, extrapolate=config.extrapolate,
+                      max_extrap_min=config.max_extrapolation_min)
+    in_span = (rt_min >= warp.rt_min) & (rt_min <= warp.rt_max)
+    is_extrap = ~in_span & np.isfinite(rt_min)
+
+    sigma = _sigma_ri(rt_min, warp, config)
+    conf = _reliability(sigma, is_extrap, config)
+
+    # keep sigma / confidence consistent with RI: an uncalibrated feature (RI NaN,
+    # e.g. beyond the anchor span with extrapolate=False) gets sigma NaN + 'none'.
+    uncal = ~np.isfinite(ri)
+    sigma[uncal] = np.nan
+    conf[uncal] = "none"
+
+    return pd.DataFrame({
+        "RI": ri,
+        "RI_uncertainty": sigma,
+        "RI_reliability": conf,
+        "is_extrapolated": is_extrap,
+        "calibration_scope": scope,
+        "warp_source": warp_source,
+    })
+
+
+def _sigma_ri(rt_min: np.ndarray, warp: MonotoneWarp, config: CalibrationConfig) -> np.ndarray:
+    slope = config.slope_irt_per_min()
+    # interior LOO residual as a function of RT (|resid|, iRT units)
+    interior = np.isfinite(warp.loo_resid)
+    if interior.any():
+        loo_interp = np.interp(rt_min, warp.rt[interior], np.abs(warp.loo_resid[interior]),
+                               left=np.abs(warp.loo_resid[interior][0]),
+                               right=np.abs(warp.loo_resid[interior][-1]))
+        sigma_scale = float(np.nanmedian(np.abs(warp.loo_resid[interior])))
+    else:
+        loo_interp = np.zeros_like(rt_min)
+        sigma_scale = 0.0
+    # nearest-anchor gap term (minutes -> iRT)
+    nearest_gap = np.min(np.abs(rt_min[:, None] - warp.rt[None, :]), axis=1)
+    gap_term = slope * config.sigma_gap_factor * nearest_gap
+    sigma_local = np.maximum(loo_interp, gap_term)
+    sigma = np.sqrt(sigma_local ** 2 + sigma_scale ** 2)
+    sigma[~np.isfinite(rt_min)] = np.nan
+    return sigma
+
+
+def _reliability(sigma: np.ndarray, is_extrap: np.ndarray, config: CalibrationConfig) -> np.ndarray:
+    conf = np.full(sigma.shape, "medium", dtype=object)
+    conf[sigma < config.conf_high_irt] = "high"
+    conf[sigma > config.conf_low_irt] = "low"
+    conf[is_extrap] = "low"
+    conf[~np.isfinite(sigma)] = "none"
+    return conf

rt_anchor/cli.py

@@ -0,0 +1,137 @@
+"""Command-line interface.
+
+    rt-anchor describe  <table>
+    rt-anchor calibrate --samples <table> --standards <run> --polarity positive [options] --out <prefix>
+
+Outputs are CSV / JSON / log only (no plots).
+"""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import os
+import sys
+from typing import List, Optional
+
+from .config import CalibrationConfig
+from .errors import RtAnchorError
+from .helpers import describe_input, setup_logger, write_results
+from .panel import load_manifest_csv, load_reference_csv
+from .pipeline import calibrate
+
+
+def _collect_single_files(spec: Optional[str]) -> Optional[List[str]]:
+    if not spec:
+        return None
+    if os.path.isdir(spec):
+        files = sorted(glob.glob(os.path.join(spec, "*.txt")) +
+                       glob.glob(os.path.join(spec, "*.csv")))
+    else:
+        files = sorted(glob.glob(spec))
+    return files or None
+
+
+def _build_config(args) -> CalibrationConfig:
+    if args.config:
+        with open(args.config) as fh:
+            cfg = CalibrationConfig.from_dict(json.load(fh))
+    else:
+        cfg = CalibrationConfig()        # sensible defaults; tune with the flags below
+    if args.mz_tol_ppm is not None:
+        cfg.mz_tol_ppm = args.mz_tol_ppm
+    if args.rt_window is not None:
+        cfg.rt_window_min = args.rt_window
+    if args.min_anchors is not None:
+        cfg.min_anchors = args.min_anchors
+    if args.extrapolate:
+        cfg.extrapolate = True
+    return cfg
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    p = argparse.ArgumentParser(prog="rt-anchor", description="Standard-panel iRT calibration for LC-MS lipidomics.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    d = sub.add_parser("describe", help="Detect format + summarise a table (no calibration).")
+    d.add_argument("table")
+    d.add_argument("--format", dest="source_format", default=None)
+    d.add_argument("--polarity", default=None)
+
+    c = sub.add_parser("calibrate", help="Calibrate a feature table to iRT.")
+    c.add_argument("--samples", required=True, help="Feature table to calibrate.")
+    c.add_argument("--standards", required=True,
+                   help="Standard-panel run (required; builds the native anchor template).")
+    c.add_argument("--polarity", required=True, choices=["positive", "negative", "pos", "neg"])
+    c.add_argument("--single-files", default=None,
+                   help="Dir or glob of per-injection tables -> per-sample tier.")
+    c.add_argument("--format", dest="source_format", default=None,
+                   help="Force input format (masscube/lipidscreener/msdial/mzmine).")
+    c.add_argument("--rt-unit", dest="rt_unit", default=None, choices=["min", "sec"])
+    c.add_argument("--manifest", default=None, help="Custom standard manifest CSV (Mode B).")
+    c.add_argument("--reference", default=None, help="Custom reference-baseline CSV.")
+    c.add_argument("--config", default=None,
+                   help="JSON config file (base; the --mz-tol-ppm/--rt-window/--min-anchors flags override individual fields).")
+    # matching / robustness parameters (replace any notion of an 'instrument type')
+    c.add_argument("--mz-tol-ppm", dest="mz_tol_ppm", type=float, default=None,
+                   help="m/z match tolerance in ppm (default 15).")
+    c.add_argument("--rt-window", dest="rt_window", type=float, default=None,
+                   help="RT search window around the native anchor RT, minutes (default 0.5).")
+    c.add_argument("--min-anchors", dest="min_anchors", type=int, default=None,
+                   help="Minimum anchors for a confident warp (default 6).")
+    c.add_argument("--extrapolate", action="store_true",
+                   help="Assign RI beyond the anchor span (capped); default off -> NaN beyond span.")
+    c.add_argument("--no-report", action="store_true", help="Skip the HTML/PDF report (data only).")
+    c.add_argument("--tic-style", default="clean", choices=["clean", "realistic", "both"],
+                   help="Reconstructed-TIC style in the report (default clean; realistic adds simulated noise).")
+    c.add_argument("--report-format", default="html,pdf",
+                   help="Comma list of report formats: html,pdf.")
+    c.add_argument("--out", required=True, help="Output path prefix.")
+
+    args = p.parse_args(argv)
+
+    if args.cmd == "describe":
+        try:
+            print(json.dumps(describe_input(args.table, source_format=args.source_format,
+                                            polarity=args.polarity), indent=2, default=str))
+            return 0
+        except RtAnchorError as e:
+            print(f"ERROR: {e}", file=sys.stderr)
+            return 2
+        except Exception as e:  # e.g. FileNotFoundError -> clean message, no traceback
+            print(f"ERROR: {type(e).__name__}: {e}", file=sys.stderr)
+            return 3
+
+    # calibrate
+    log = setup_logger()
+    try:
+        cfg = _build_config(args)
+        manifest = load_manifest_csv(args.manifest) if args.manifest else None
+        reference = load_reference_csv(args.reference) if args.reference else None
+        single = _collect_single_files(args.single_files)
+        if single:
+            log.info(f"per-sample tier: {len(single)} injection tables")
+        result = calibrate(
+            sample_table=args.samples, polarity=args.polarity,
+            standards_table=args.standards, single_files=single,
+            config=cfg, manifest=manifest, reference=reference,
+            source_format=args.source_format, rt_unit=args.rt_unit,
+        )
+        for line in result.log:
+            log.info(line)
+        fmts = tuple(f.strip() for f in args.report_format.split(",") if f.strip())
+        paths = write_results(result, args.out, report=not args.no_report,
+                              tic_style=args.tic_style, report_formats=fmts)
+        log.info(f"wrote: {json.dumps(paths)}")
+        return 0
+    except RtAnchorError as e:
+        log.error(str(e))
+        return 2
+    except Exception as e:  # unexpected -> surface with type
+        log.error(f"{type(e).__name__}: {e}")
+        return 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rt_anchor/config.py

@@ -0,0 +1,86 @@
+"""Configuration for the calibration.
+
+Defaults are tuned for **QTOF** data (the common case for this project):
+wider m/z tolerance and RT windows than an Orbitrap would need. Every value is
+override-able (constructor kwargs, ``CalibrationConfig.qtof()`` /
+``.orbitrap()`` presets, or ``from_dict``). Nothing here is instrument-locked.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Optional, Tuple
+
+
+@dataclass
+class CalibrationConfig:
+    # ---- m/z matching ----
+    mz_tol_ppm: float = 15.0            # QTOF default (Orbitrap ~8)
+    mz_tol_min_da: float = 0.0          # optional absolute floor on the ppm window
+
+    # ---- RT search window around the native-template anchor RT (minutes) ----
+    rt_window_min: float = 0.5          # QTOF default (Orbitrap ~0.3)
+    # window used when NO native template exists and we must seed from reference RT
+    rt_window_seed_min: float = 2.0
+
+    # ---- iRT scale (fixed method constants; dimensionless, minute-derived) ----
+    scale_rt_lo_min: float = 1.0
+    scale_rt_hi_min: float = 18.4
+
+    # ---- anchor acceptance / warp robustness ----
+    min_anchors: int = 6                # below this -> low-confidence / uncalibrated
+    min_anchors_hard: int = 3           # below this -> refuse to calibrate
+    coverage_gap_min: float = 3.0       # max in-domain inter-anchor RT gap (minutes)
+    tie_epsilon_min: float = 0.005      # equal-RT tolerance for monotonicity guard
+    max_drop_anchors: int = 3           # cap on anchors removed by the guard
+
+    # ---- extrapolation ----
+    extrapolate: bool = False           # if False: RI = NaN beyond anchor span
+    max_extrapolation_min: float = 1.0  # only used when extrapolate=True
+
+    # ---- confidence thresholds (iRT units) ----
+    conf_high_irt: float = 0.6          # RI_uncertainty < this  -> high
+    conf_low_irt: float = 3.0           # RI_uncertainty > this  -> low
+    sigma_gap_factor: float = 0.1       # sigma_local ~= factor * nearest-anchor gap (min) * slope
+
+    # ---- optional peak-quality gate (applied only if the columns exist) ----
+    min_gaussian_similarity: float = 0.0    # 0 disables; spec suggests ~0.7
+    asymmetry_range: Tuple[float, float] = (0.0, 1e9)  # widen -> disabled
+
+    # ---- RT unit handling ----
+    rt_unit: Optional[str] = None       # None = auto (per-format default + range check)
+
+    # ---- misc ----
+    verbose: bool = True
+
+    def slope_irt_per_min(self) -> float:
+        return 100.0 / (self.scale_rt_hi_min - self.scale_rt_lo_min)
+
+    def irt_from_rt(self, rt_min: float) -> float:
+        return 100.0 * (rt_min - self.scale_rt_lo_min) / (self.scale_rt_hi_min - self.scale_rt_lo_min)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "CalibrationConfig":
+        from .errors import ConfigError
+        known = {f for f in cls.__dataclass_fields__}  # type: ignore[attr-defined]
+        unknown = set(d) - known
+        if unknown:
+            raise ConfigError(f"Unknown config keys: {sorted(unknown)}. Known: {sorted(known)}")
+        cfg = cls(**{k: v for k, v in d.items() if k in known})
+        if cfg.asymmetry_range is not None:
+            cfg.asymmetry_range = tuple(cfg.asymmetry_range)  # json gives lists
+        return cfg
+
+    # ---- instrument presets ----
+    @classmethod
+    def qtof(cls, **overrides) -> "CalibrationConfig":
+        return cls(**overrides)
+
+    @classmethod
+    def orbitrap(cls, **overrides) -> "CalibrationConfig":
+        base = dict(mz_tol_ppm=8.0, rt_window_min=0.3)
+        base.update(overrides)
+        return cls(**base)

rt_anchor/errors.py

@@ -0,0 +1,40 @@
+"""Typed exceptions for rt_anchor.
+
+Every error carries an actionable message: what went wrong, which input it
+concerns, and (where possible) how to fix it. Callers can catch the base
+``RtAnchorError`` to handle any package-level failure.
+"""
+
+from __future__ import annotations
+
+
+class RtAnchorError(Exception):
+    """Base class for all rt_anchor errors."""
+
+
+class ConfigError(RtAnchorError):
+    """The configuration is invalid (unknown keys, bad values)."""
+
+
+class InputFormatError(RtAnchorError):
+    """The input file could not be parsed or its format could not be recognised."""
+
+
+class ColumnResolutionError(InputFormatError):
+    """A required logical column (m/z or RT) could not be located in the table."""
+
+
+class RTUnitError(RtAnchorError):
+    """Retention-time units are ambiguous or inconsistent with the declared unit."""
+
+
+class PanelError(RtAnchorError):
+    """The standard manifest / reference baseline is malformed or incomplete."""
+
+
+class AnchorIdentificationError(RtAnchorError):
+    """Too few standards could be identified to build a calibration."""
+
+
+class CalibrationError(RtAnchorError):
+    """The monotone warp could not be fitted (e.g. degenerate anchors)."""

rt_anchor/helpers.py

@@ -0,0 +1,126 @@
+"""User-facing helpers: format inspection, result writers, logging setup.
+
+None of these produce visualisations — outputs are CSV / JSON / plain-text log.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Dict, List, Optional
+
+import pandas as pd
+
+from .io.adapters import detect_format
+from .io.loader import load_feature_table
+from .pipeline import CalibrationResult
+
+
+def describe_input(path: str, source_format: Optional[str] = None,
+                   polarity: Optional[str] = None) -> Dict:
+    """Detect + summarise an input table without calibrating (dry-run helper)."""
+    ft = load_feature_table(path, source_format=source_format, polarity=polarity)
+    info = ft.summary()
+    info["path"] = path
+    if ft.meta:
+        info["meta_keys"] = list(ft.meta.keys())
+    return info
+
+
+def which_format(path: str) -> str:
+    fmt, _, _ = detect_format(path)
+    return fmt
+
+
+def setup_logger(logfile: Optional[str] = None, level: int = logging.INFO) -> logging.Logger:
+    logger = logging.getLogger("rt_anchor")
+    logger.setLevel(level)
+    logger.handlers.clear()
+    fmt = logging.Formatter("%(asctime)s [%(levelname)s] %(message)s", "%Y-%m-%d %H:%M:%S")
+    sh = logging.StreamHandler()
+    sh.setFormatter(fmt)
+    logger.addHandler(sh)
+    if logfile:
+        fh = logging.FileHandler(logfile)
+        fh.setFormatter(fmt)
+        logger.addHandler(fh)
+    return logger
+
+
+def write_results(result: CalibrationResult, out_prefix: str,
+                  write_log: bool = True, report: bool = True,
+                  tic_style: str = "clean", report_formats=("html", "pdf")) -> Dict[str, str]:
+    """Write the calibrated table (CSV), model (JSON), log (txt), and — by
+    default — a visual Report (interactive HTML + static PDF).
+
+    Set ``report=False`` for data-only output. Returns {kind: path}.
+    """
+    os.makedirs(os.path.dirname(os.path.abspath(out_prefix)) or ".", exist_ok=True)
+    paths: Dict[str, str] = {}
+
+    csv_path = f"{out_prefix}_calibrated.csv"
+    result.table.to_csv(csv_path, index=False)
+    paths["calibrated_csv"] = csv_path
+
+    model_path = f"{out_prefix}_model.json"
+    with open(model_path, "w") as fh:
+        # allow_nan=False + a NaN->null sanitiser so the file is *valid* JSON
+        # (bare ``NaN`` is rejected by strict parsers, e.g. JS ``JSON.parse``).
+        json.dump(_sanitize_json(result.model), fh, indent=2,
+                  default=_json_default, allow_nan=False)
+    paths["model_json"] = model_path
+
+    anchors_path = f"{out_prefix}_anchors.csv"
+    result.anchors.to_csv(anchors_path, index=False)
+    paths["anchors_csv"] = anchors_path
+
+    if write_log:
+        log_path = f"{out_prefix}_log.txt"
+        with open(log_path, "w") as fh:
+            fh.write("\n".join(result.log) + "\n")
+        paths["log_txt"] = log_path
+
+    if report:
+        try:
+            from .viz.report import write_report
+            paths.update(write_report(result, out_prefix, tic_style=tic_style,
+                                      formats=report_formats))
+        except ImportError as e:
+            result.log.append(f"report skipped (missing viz deps: {e}); "
+                              f"install rt_anchor[report] for matplotlib+plotly")
+    return paths
+
+
+def _sanitize_json(o):
+    """Recursively replace non-finite floats (NaN/inf) with ``None``.
+
+    Needed because numpy floats are ``float`` subclasses, so the json C-encoder
+    serialises them natively (emitting a bare, invalid ``NaN``) and never calls
+    ``default``. We walk the structure and null-out non-finite values so the
+    written file is valid JSON.
+    """
+    import math
+
+    if isinstance(o, dict):
+        return {k: _sanitize_json(v) for k, v in o.items()}
+    if isinstance(o, (list, tuple)):
+        return [_sanitize_json(v) for v in o]
+    if isinstance(o, float):  # includes np.float64 (a float subclass)
+        return None if not math.isfinite(o) else float(o)
+    return o
+
+
+def _json_default(o):
+    import numpy as np
+    if isinstance(o, (np.integer,)):
+        return int(o)
+    if isinstance(o, (np.floating,)):
+        return None if not np.isfinite(o) else float(o)
+    if isinstance(o, (np.bool_,)):
+        return bool(o)
+    if isinstance(o, np.ndarray):
+        return o.tolist()
+    if isinstance(o, float) and (o != o):  # NaN
+        return None
+    return str(o)