eemkit 0.1.0__py3-none-any.whl

eemkit/io/cary_eclipse.py

@@ -0,0 +1,140 @@
+"""Reader for Agilent Cary Eclipse 3-D (EEM) CSV exports."""
+
+from __future__ import annotations
+
+import re
+import warnings
+from pathlib import Path
+
+import numpy as np
+import xarray as xr
+
+from eemkit.core.grid import DEFAULT_TOLERANCE, interp_on_grid
+from eemkit.core.history import with_history
+from eemkit.errors import EEMKitWarning, FileFormatError
+from eemkit.io._cary_csv import common_params, parse_cary_csv, scan_times, time_attrs
+
+LABEL_RE = re.compile(r"^(?P<name>.*)_EX_(?P<ex>[0-9]+(?:\.[0-9]+)?)$")
+
+#: dataset attribute -> key in the 'Parameter List' of the scan log
+LOG_PARAMS = {
+    "instrument": "Instrument",
+    "instrument_serial": "Instrument Serial Number",
+    "data_mode": "Data mode",
+    "scan_mode": "Scan mode",
+    "em_start_nm": "Start (nm)",
+    "em_stop_nm": "Stop (nm)",
+    "ex_slit_nm": "Ex. Slit (nm)",
+    "em_slit_nm": "Em. Slit (nm)",
+    "scan_rate_nm_per_min": "Scan rate (nm/min)",
+    "data_interval_nm": "Data interval (nm)",
+    "averaging_time_s": "Averaging Time (s)",
+    "ex_filter": "Excitation filter",
+    "em_filter": "Emission filter",
+    "pmt_voltage": "PMT voltage (V)",
+    "corrected_spectra": "Corrected spectra",
+}
+
+
+def read_cary_eclipse(
+    path: str | Path,
+    em_grid: np.ndarray | None = None,
+    tolerance: float = DEFAULT_TOLERANCE,
+) -> xr.Dataset:
+    """Read one EEM exported by the Cary Eclipse software as CSV with log.
+
+    Parameters
+    ----------
+    path
+        CSV file with one emission scan per excitation wavelength.
+    em_grid
+        If given, each emission scan is linearly interpolated onto this grid
+        (nm). If omitted, the native emission axis is kept, which requires all
+        scans of the file to share it.
+    tolerance
+        See :func:`eemkit.core.grid.interp_on_grid`; used only with ``em_grid``.
+
+    Returns
+    -------
+    xarray.Dataset
+        ``intensity`` with dims ``(ex, em)`` in instrument units, coordinate
+        ``scan_time(ex)`` and the instrument settings as attributes. Values
+        are exactly as exported: no correction of any kind is applied.
+    """
+    path = Path(path)
+    raw = parse_cary_csv(path)
+
+    names, ex = [], []
+    for lab in raw.labels:
+        m = LABEL_RE.match(lab)
+        if not m:
+            raise FileFormatError(
+                f"{path}: column label {lab!r} is not '<sample>_EX_<nm>'; "
+                "is this a Cary Eclipse 3-D scan?"
+            )
+        names.append(m.group("name"))
+        ex.append(float(m.group("ex")))
+    if len(set(names)) > 1:
+        raise FileFormatError(f"{path}: several sample names in one file: {sorted(set(names))}")
+    if len(set(ex)) != len(ex):
+        raise FileFormatError(f"{path}: duplicated excitation wavelengths")
+    if raw.titles[:2] != ["Wavelength (nm)", "Intensity (a.u.)"]:
+        raise FileFormatError(f"{path}: unexpected column titles {raw.titles[:2]}")
+
+    order = np.argsort(ex)
+    ex_arr = np.asarray(ex)[order]
+    x, y = raw.x[:, order], raw.y[:, order]
+    labels = [raw.labels[i] for i in order]
+
+    if em_grid is None:
+        keep = ~np.all(np.isnan(x), axis=1)
+        x, y = x[keep], y[keep]
+        em = x[:, 0]
+        if not np.allclose(x, em[:, None], atol=1e-6, equal_nan=True) or np.isnan(em).any():
+            raise FileFormatError(
+                f"{path}: the emission axis differs between excitation scans; "
+                "pass em_grid= to resample each scan onto a common grid"
+            )
+        em_order = np.argsort(em)
+        em, intensity = em[em_order], y[em_order].T
+        if np.any(np.diff(em) <= 0):
+            raise FileFormatError(f"{path}: repeated emission wavelengths")
+    else:
+        em = np.asarray(em_grid, dtype=float)
+        intensity = np.vstack(
+            [interp_on_grid(x[:, j], y[:, j], em, tolerance) for j in range(len(ex_arr))]
+        )
+
+    logs = [raw.log_for(lab) for lab in labels]
+    missing = [lab for lab, lg in zip(labels, logs, strict=True) if lg is None]
+    if missing:
+        warnings.warn(f"{path.name}: no log block for {len(missing)} scan(s), e.g. {missing[0]}",
+                      EEMKitWarning, stacklevel=2)
+    present = [lg for lg in logs if lg is not None]
+    times = scan_times(logs)
+
+    attrs = {
+        "sample_name": names[0],
+        "source_file": str(path),
+        "file_format": "Cary Eclipse CSV (ASCII with log)",
+        **common_params(path, present, LOG_PARAMS),
+        **time_attrs(times),
+        "method_name": "|".join(dict.fromkeys(lg.method_name for lg in present)),
+    }
+    if attrs.get("data_mode", "Fluorescence") != "Fluorescence" or \
+            attrs.get("scan_mode", "Emission") != "Emission":
+        raise FileFormatError(f"{path}: not a fluorescence emission scan")
+
+    ds = xr.Dataset(
+        {"intensity": (("ex", "em"), intensity,
+                       {"units": "a.u.", "long_name": "fluorescence intensity"})},
+        coords={
+            "ex": ("ex", ex_arr, {"units": "nm", "long_name": "excitation wavelength"}),
+            "em": ("em", em, {"units": "nm", "long_name": "emission wavelength"}),
+            "scan_time": ("ex", times),
+        },
+        attrs=attrs,
+    )
+    return with_history(ds, "read_cary_eclipse",
+                        em_grid=em if em_grid is not None else "native",
+                        tolerance_nm=tolerance if em_grid is not None else None)

eemkit/io/discover.py

@@ -0,0 +1,176 @@
+"""Find measurement files in a data folder and draft a pairing table from them.
+
+:func:`scan_folder` classifies every CSV from its first two lines (scan labels
+and column titles), without reading the data, and never writes anything.
+
+:func:`suggest_pairing` drafts a pairing table from that inventory. The draft
+is a starting point for a person to check: every row is written with
+``include = no`` and ``pairing_status = suggested``, and each choice it made
+(or could not make) is explained in ``pairing_notes``. :func:`load_dataset`
+reads only rows that someone has switched to ``include = yes``.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from pathlib import Path
+
+import pandas as pd
+
+from eemkit.io import cary60, cary_eclipse
+
+#: Sample or file names matching this (case-insensitive) are treated as blanks.
+DEFAULT_BLANK_PATTERN = r"blank|bianc|milli-?q|\bmq\b|ultrapure"
+
+INVENTORY_COLUMNS = ("file", "kind", "sample_name", "n_scans", "first_x", "last_x",
+                     "is_blank", "problem")
+
+
+def _head(path: Path, n: int = 2) -> list[str]:
+    raw = path.open("rb").read(65536)
+    for enc in ("utf-8-sig", "cp1252", "latin-1"):
+        try:
+            return raw.decode(enc).splitlines()[:n]
+        except UnicodeDecodeError:
+            continue
+    return []  # pragma: no cover - latin-1 decodes anything
+
+
+def classify(path: str | Path) -> dict:
+    """Kind of one CSV ('eem', 'absorbance' or 'unknown') from its header lines."""
+    path = Path(path)
+    out = {"kind": "unknown", "sample_name": "", "n_scans": 0, "first_x": None,
+           "last_x": None, "problem": ""}
+    try:
+        lines = _head(path)
+    except OSError as exc:
+        out["problem"] = f"cannot read: {exc}"
+        return out
+    if len(lines) < 2:
+        out["problem"] = "fewer than two lines"
+        return out
+    labels = [t.strip() for t in lines[0].split(",") if t.strip()]
+    titles = [t.strip() for t in lines[1].split(",")][:2]
+    out["n_scans"] = len(labels)
+    for kind, regex, title, xgroup in (
+        ("eem", cary_eclipse.LABEL_RE, "Intensity (a.u.)", "ex"),
+        ("absorbance", cary60.LABEL_RE, "Abs", "cycle"),
+    ):
+        matches = [regex.match(lab) for lab in labels]
+        if labels and all(matches) and titles == ["Wavelength (nm)", title]:
+            names = {m.group("name") for m in matches}
+            if len(names) > 1:
+                out["problem"] = f"several sample names: {sorted(names)}"
+                return out
+            xs = sorted(float(m.group(xgroup)) for m in matches)
+            out.update(kind=kind, sample_name=names.pop(), first_x=xs[0], last_x=xs[-1])
+            return out
+    out["problem"] = f"not a Cary Eclipse 3-D or Cary 60 absorbance export (titles {titles})"
+    return out
+
+
+def scan_folder(
+    root: str | Path,
+    *,
+    blank_pattern: str = DEFAULT_BLANK_PATTERN,
+    progress: Callable[[int, int], None] | None = None,
+) -> pd.DataFrame:
+    """Classify every ``*.csv`` below ``root`` (recursively); read-only.
+
+    Returns one row per file with :data:`INVENTORY_COLUMNS`; ``file`` is
+    relative to ``root`` with forward slashes. ``first_x``/``last_x`` are
+    the excitation range (EEM) or cycle numbers (absorbance).
+    """
+    root = Path(root)
+    files = sorted(p for p in root.rglob("*") if p.is_file() and p.suffix.lower() == ".csv")
+    blank = re.compile(blank_pattern, re.IGNORECASE)
+    rows = []
+    for i, p in enumerate(files):
+        info = classify(p)
+        rel = p.relative_to(root).as_posix()
+        info["file"] = rel
+        info["is_blank"] = bool(blank.search(info["sample_name"]) or blank.search(p.name))
+        rows.append(info)
+        if progress:
+            progress(i + 1, len(files))
+    return pd.DataFrame(rows, columns=list(INVENTORY_COLUMNS))
+
+
+def _key(name: str) -> str:
+    return re.sub(r"[\s_\-.]+", "", name).lower()
+
+
+def _folder(file: str) -> str:
+    parent = Path(file).parent.as_posix()
+    return "" if parent == "." else parent
+
+
+def _unique_in_folder(candidates: pd.DataFrame, folder: str) -> tuple[str, str]:
+    """(file, note) for the single candidate in ``folder``, else ('', reason)."""
+    here = candidates[candidates["folder"] == folder]
+    if len(here) == 1:
+        return here["file"].iloc[0], ""
+    if len(here) > 1:
+        return "", f"{len(here)} candidates in {folder or '.'}"
+    return "", f"none in {folder or '.'}"
+
+
+def suggest_pairing(inventory: pd.DataFrame) -> pd.DataFrame:
+    """Draft a pairing table from :func:`scan_folder` output, for a person to check.
+
+    One row per non-blank EEM. Suggestions, all marked as such:
+
+    * ``abs_file``: the non-blank absorbance file with the same sample name
+      (ignoring case, spaces, ``_``, ``-`` and ``.``), preferring the EEM's
+      folder; left empty if there is no single match;
+    * ``eem_blank_file``: the only blank EEM in the EEM's folder;
+    * ``abs_blank_file``: the only blank absorbance file in the absorbance
+      file's folder.
+
+    Every row has ``include = no``.
+    """
+    inv = inventory.copy()
+    inv["folder"] = inv["file"].map(_folder)
+    eems = inv[(inv["kind"] == "eem") & ~inv["is_blank"]]
+    absb = inv[(inv["kind"] == "absorbance") & ~inv["is_blank"]]
+    eem_blanks = inv[(inv["kind"] == "eem") & inv["is_blank"]]
+    abs_blanks = inv[(inv["kind"] == "absorbance") & inv["is_blank"]]
+    abs_keys = absb["sample_name"].map(_key)
+
+    rows, used = [], {}
+    for _, e in eems.iterrows():
+        notes = []
+        sid = e["sample_name"] or Path(e["file"]).stem
+        if sid in used:
+            used[sid] += 1
+            notes.append(f"sample name also used by another file; renamed to {sid}_{used[sid]}")
+            sid = f"{sid}_{used[sid]}"
+        else:
+            used[sid] = 1
+
+        cands = absb[abs_keys == _key(e["sample_name"])]
+        same = cands[cands["folder"] == e["folder"]]
+        pick = same if len(same) == 1 else cands
+        if len(pick) == 1:
+            abs_file = pick["file"].iloc[0]
+            notes.append("absorbance matched by sample name")
+        else:
+            abs_file = ""
+            notes.append("no absorbance with this sample name" if cands.empty
+                         else f"{len(cands)} absorbance files with this sample name")
+
+        eem_blank, why = _unique_in_folder(eem_blanks, e["folder"])
+        notes.append(f"EEM blank: {'only blank in folder' if eem_blank else why}")
+        abs_blank = ""
+        if abs_file:
+            abs_blank, why = _unique_in_folder(abs_blanks, _folder(abs_file))
+            notes.append(f"absorbance blank: {'only blank in folder' if abs_blank else why}")
+
+        rows.append({"sample_id": sid, "include": "no", "eem_file": e["file"],
+                     "eem_blank_file": eem_blank, "abs_file": abs_file,
+                     "abs_blank_file": abs_blank, "pairing_status": "suggested",
+                     "pairing_notes": "; ".join(notes)})
+    return pd.DataFrame(rows, columns=["sample_id", "include", "eem_file", "eem_blank_file",
+                                       "abs_file", "abs_blank_file", "pairing_status",
+                                       "pairing_notes"])

eemkit/io/loader.py

@@ -0,0 +1,158 @@
+"""Build one multi-sample dataset from a pairing table."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import xarray as xr
+
+from eemkit.core.dataset import SAMPLE_DIM, stack
+from eemkit.core.grid import DEFAULT_TOLERANCE, infer_common_grid, resample
+from eemkit.core.history import HISTORY_ATTR, describe_grid, get_history, make_entry
+from eemkit.errors import GridError
+from eemkit.io.cary60 import mean_cycles, read_cary60
+from eemkit.io.cary_eclipse import read_cary_eclipse
+from eemkit.io.pairing import read_pairing
+
+READERS = {"cary_eclipse": read_cary_eclipse}
+ABS_READERS = {"cary60": read_cary60}
+
+
+def load_dataset(
+    pairing: str | Path | pd.DataFrame,
+    data_root: str | Path | None = None,
+    em_grid: np.ndarray | None = None,
+    wavelength_grid: np.ndarray | None = None,
+    tolerance: float = DEFAULT_TOLERANCE,
+    eem_format: str = "cary_eclipse",
+    abs_format: str = "cary60",
+) -> xr.Dataset:
+    """Read every included row of a pairing table into one dataset.
+
+    Parameters
+    ----------
+    pairing
+        Path to the pairing CSV, or a table already returned by
+        :func:`eemkit.io.pairing.read_pairing`.
+    data_root
+        Folder the file paths are relative to (see ``read_pairing``).
+    em_grid, wavelength_grid
+        Common emission grid for EEMs and wavelength grid for absorbance (nm).
+        If omitted they are inferred with
+        :func:`eemkit.core.grid.infer_common_grid` from all files read, and
+        the choice is recorded in the history.
+    tolerance
+        Edge tolerance of the linear resampling (nm).
+
+    Returns
+    -------
+    xarray.Dataset
+        Dimensions ``sample``, ``ex``, ``em`` and, when any absorbance is
+        paired, ``wavelength``. Variables:
+
+        * ``intensity`` (sample, ex, em): raw sample EEMs on ``em_grid``
+        * ``blank_intensity`` (sample, ex, em): the paired blank, NaN if none
+        * ``absorbance``, ``absorbance_sd`` (sample, wavelength): mean and SD
+          of the instrument cycles, NaN if none
+        * ``blank_absorbance`` (sample, wavelength)
+
+        All pairing-table columns become ``sample`` coordinates. File and
+        instrument metadata are prefixed ``eem_``, ``eem_blank_``, ``abs_``
+        and ``abs_blank_``.
+    """
+    table = pairing if isinstance(pairing, pd.DataFrame) else read_pairing(pairing, data_root)
+    root = Path(data_root if data_root is not None else table.attrs.get("data_root", "."))
+    rows = table[table["include"]].reset_index(drop=True)
+    if rows.empty:
+        raise ValueError("no included rows in the pairing table")
+    ids = list(rows["sample_id"])
+
+    read_eem = READERS[eem_format]
+    read_abs = ABS_READERS[abs_format]
+    cache: dict[str, xr.Dataset] = {}
+
+    def load(col: str, reader) -> list[xr.Dataset | None]:
+        out = []
+        for rel in rows[col]:
+            if not rel:
+                out.append(None)
+                continue
+            if rel not in cache:
+                cache[rel] = reader(root / rel)
+            out.append(cache[rel])
+        return out
+
+    eems = load("eem_file", read_eem)
+    eem_blanks = load("eem_blank_file", read_eem)
+    abss = [mean_cycles(a) if a is not None else None for a in load("abs_file", read_abs)]
+    abs_blanks = [mean_cycles(a) if a is not None else None
+                  for a in load("abs_blank_file", read_abs)]
+
+    all_eems = [e for e in eems + eem_blanks if e is not None]
+    ex0 = all_eems[0]["ex"].values
+    for e in all_eems:
+        if e.sizes["ex"] != ex0.size or not np.allclose(e["ex"].values, ex0):
+            raise GridError(f"{e.attrs['source_file']}: excitation wavelengths differ from "
+                            f"{all_eems[0].attrs['source_file']}")
+    em_inferred = em_grid is None
+    if em_inferred:
+        em_grid = infer_common_grid(e["em"].values for e in all_eems)
+
+    def on_grid(items, dim, grid):
+        return [resample(it, dim, grid, tolerance) if it is not None else None for it in items]
+
+    ds = stack(on_grid(eems, "em", em_grid), ids, prefix="eem_")
+    history = get_history(ds)
+    ds.attrs.pop(HISTORY_ATTR, None)
+    if any(b is not None for b in eem_blanks):
+        blanks = stack(on_grid(eem_blanks, "em", em_grid), ids, prefix="eem_blank_")
+        ds["blank_intensity"] = blanks["intensity"]
+        ds = _merge_meta(ds, blanks, "eem_blank_")
+
+    params = {"em_grid": describe_grid(em_grid), "em_grid_inferred": em_inferred,
+              "tolerance_nm": tolerance, "n_samples": len(ids),
+              "n_with_eem_blank": sum(b is not None for b in eem_blanks),
+              "n_with_absorbance": sum(a is not None for a in abss)}
+
+    all_abs = [a for a in abss + abs_blanks if a is not None]
+    if all_abs:
+        wl_inferred = wavelength_grid is None
+        if wl_inferred:
+            wavelength_grid = infer_common_grid(a["wavelength"].values for a in all_abs)
+        params.update(wavelength_grid=describe_grid(wavelength_grid),
+                      wavelength_grid_inferred=wl_inferred)
+        for items, prefix, names in (
+            (abss, "abs_", {"absorbance": "absorbance", "absorbance_sd": "absorbance_sd"}),
+            (abs_blanks, "abs_blank_", {"absorbance": "blank_absorbance"}),
+        ):
+            if all(it is None for it in items):
+                continue
+            part = stack(on_grid(items, "wavelength", wavelength_grid), ids, prefix=prefix)
+            for src, dst in names.items():
+                ds[dst] = part[src]
+            ds = _merge_meta(ds, part, prefix)
+
+    meta = {c: (SAMPLE_DIM, rows[c].to_numpy(dtype=object))
+            for c in rows.columns if c not in ("sample_id", "include")}
+    ds = ds.assign_coords(meta)
+    ds.attrs["pairing_source"] = table.attrs.get("source", "")
+    ds.attrs["data_root"] = str(root)
+    ds.attrs["spectral_correction"] = (
+        "instrument ('Corrected spectra' ON)"
+        if str(ds.attrs.get("eem_corrected_spectra", "")).upper() == "ON" else "none")
+    ds.attrs[HISTORY_ATTR] = json.dumps(history + [make_entry("load_dataset", **params)])
+    return ds
+
+
+def _merge_meta(ds: xr.Dataset, part: xr.Dataset, prefix: str) -> xr.Dataset:
+    """Copy the prefixed coordinates and attributes of ``part`` into ``ds``.
+
+    The history of ``part`` is kept as ``<prefix>history``.
+    """
+    ds = ds.assign_coords({k: v for k, v in part.coords.items() if k not in part.dims})
+    for k, v in part.attrs.items():
+        ds.attrs[f"{prefix}history" if k == HISTORY_ATTR else k] = v
+    return ds

eemkit/io/pairing.py

@@ -0,0 +1,115 @@
+"""The pairing table: which EEM, absorbance and blank files belong together.
+
+Pairing is never guessed by eemkit. A CSV table, written or checked by a
+person, lists one sample per row:
+
+=================  ========  ==================================================
+column             required  content
+=================  ========  ==================================================
+``sample_id``      yes       unique identifier used throughout the analysis
+``eem_file``       yes       fluorescence file, relative to ``data_root``
+``include``        yes       yes/no (also true/false, 1/0, si/sì)
+``eem_blank_file`` no        blank EEM (e.g. Milli-Q) measured with the sample
+``abs_file``       no        absorbance file of the same sample
+``abs_blank_file`` no        absorbance blank
+any other column   no        kept as sample metadata (river, site, date, ...)
+=================  ========  ==================================================
+
+Comma or semicolon separators are accepted, so the table can be edited in a
+spreadsheet with an Italian or other comma-decimal locale.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+
+from eemkit.errors import PairingError
+
+REQUIRED_COLUMNS = ("sample_id", "eem_file", "include")
+FILE_COLUMNS = ("eem_file", "eem_blank_file", "abs_file", "abs_blank_file")
+_TRUE = {"yes", "y", "true", "1", "si", "sì"}
+_FALSE = {"no", "n", "false", "0", ""}
+
+
+def read_pairing(
+    path: str | Path,
+    data_root: str | Path | None = None,
+    check_files: bool = True,
+) -> pd.DataFrame:
+    """Read and validate a pairing table.
+
+    Parameters
+    ----------
+    path
+        CSV file.
+    data_root
+        Folder the file paths are relative to; defaults to the table's folder.
+    check_files
+        Verify that every file referenced by an included row exists.
+
+    Returns
+    -------
+    pandas.DataFrame
+        All rows (included or not), every column as text except ``include``
+        (bool). ``df.attrs`` holds ``source`` and ``data_root``.
+
+    Raises
+    ------
+    PairingError
+        Listing every problem found, not only the first.
+    """
+    path = Path(path)
+    root = Path(data_root) if data_root is not None else path.parent
+    df = _read_csv(path)
+    df.columns = [str(c).strip() for c in df.columns]
+
+    missing = [c for c in REQUIRED_COLUMNS if c not in df.columns]
+    if missing:
+        raise PairingError(f"{path}: missing required column(s) {missing}")
+    for col in FILE_COLUMNS:
+        if col not in df.columns:
+            df[col] = ""
+    df = df.apply(lambda s: s.str.strip())
+
+    problems = []
+    flags = df["include"].str.lower()
+    bad = ~flags.isin(_TRUE | _FALSE)
+    for i in df.index[bad]:
+        problems.append(f"row {i + 2}: include={df.at[i, 'include']!r} is not yes/no")
+    df["include"] = flags.isin(_TRUE)
+
+    inc = df[df["include"]]
+    for i in inc.index[inc["sample_id"] == ""]:
+        problems.append(f"row {i + 2}: empty sample_id")
+    for i in inc.index[inc["eem_file"] == ""]:
+        problems.append(f"row {i + 2}: included but eem_file is empty")
+    dup = inc["sample_id"][inc["sample_id"].duplicated(keep=False) & (inc["sample_id"] != "")]
+    for sid in sorted(set(dup)):
+        rows = [str(i + 2) for i in dup.index[dup == sid]]
+        problems.append(f"sample_id {sid!r} used by rows {', '.join(rows)}")
+
+    if check_files:
+        for i, row in inc.iterrows():
+            for col in FILE_COLUMNS:
+                if row[col] and not (root / row[col]).is_file():
+                    problems.append(f"row {i + 2}: {col} not found: {row[col]}")
+
+    if problems:
+        raise PairingError(f"{path}: {len(problems)} problem(s)\n  " + "\n  ".join(problems))
+    df.attrs["source"] = str(path)
+    df.attrs["data_root"] = str(root)
+    return df
+
+
+def _read_csv(path: Path) -> pd.DataFrame:
+    for enc in ("utf-8-sig", "cp1252"):
+        try:
+            with open(path, encoding=enc) as fh:
+                header = fh.readline()
+            sep = ";" if header.count(";") > header.count(",") else ","
+            return pd.read_csv(path, sep=sep, dtype=str, keep_default_na=False, encoding=enc)
+        except UnicodeDecodeError:
+            continue
+    raise PairingError(f"{path}: cannot decode as UTF-8 or Windows-1252")

eemkit/parafac/__init__.py

@@ -0,0 +1,28 @@
+"""Non-negative PARAFAC with the diagnostics of Murphy et al. (2013)."""
+
+from eemkit.parafac._cp import nn_parafac
+from eemkit.parafac.diagnostics import (
+    core_consistency,
+    leverage,
+    match_components,
+    tucker_congruence,
+)
+from eemkit.parafac.export import to_openfluor
+from eemkit.parafac.model import fit_parafac, fit_ranks, model_eem, residuals, summary_table
+from eemkit.parafac.validation import split_groups, split_half
+
+__all__ = [
+    "core_consistency",
+    "fit_parafac",
+    "fit_ranks",
+    "leverage",
+    "match_components",
+    "model_eem",
+    "nn_parafac",
+    "residuals",
+    "split_groups",
+    "split_half",
+    "summary_table",
+    "to_openfluor",
+    "tucker_congruence",
+]