eemkit 0.1.0__py3-none-any.whl

eemkit/gui/indices_tab.py

@@ -0,0 +1,228 @@
+"""Tab 3: fluorescence indices, Coble peaks and CDOM (absorbance) metrics."""
+
+from __future__ import annotations
+
+import warnings
+
+import pandas as pd
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import (
+    QCheckBox,
+    QComboBox,
+    QFileDialog,
+    QFormLayout,
+    QGroupBox,
+    QHBoxLayout,
+    QLabel,
+    QMessageBox,
+    QPushButton,
+    QSplitter,
+    QTableView,
+    QVBoxLayout,
+    QWidget,
+)
+
+from eemkit import plot
+from eemkit.errors import EEMKitWarning
+from eemkit.gui.common import DataFrameModel, PlotPanel, TaskBar, note, pair, primary, spin
+from eemkit.gui.state import Project
+from eemkit.pipeline import compute_absorbance, compute_indices
+
+INDEX_COLUMNS = ("FI", "HIX", "BIX", "peak_B", "peak_T", "peak_A", "peak_M", "peak_C")
+CDOM_COLUMNS = ("a254", "a350", "S275_295", "S350_400", "SR", "E2_E3", "SUVA254")
+
+
+class IndicesTab(QWidget):
+    def __init__(self, project: Project, tasks: TaskBar, parent=None):
+        super().__init__(parent)
+        self.project, self.tasks = project, tasks
+
+        self.ex_method = QComboBox()
+        self.ex_method.addItems(["linear", "nearest", "exact"])
+        self.bix_den = spin(430, 300, 600, 1, 0, " nm")
+        settings = QGroupBox("Settings")
+        f = QFormLayout(settings)
+        f.addRow("Excitations off the grid", self.ex_method)
+        f.addRow("BIX denominator emission", self.bix_den)
+        f.addRow(note("FI: Cory & McKnight 2005 (ex 370, em 470/520). HIX: Ohno 2002. BIX: "
+                      "Huguet et al. 2009. Peaks: Coble 1996. Computed after Raman units, "
+                      "before scatter removal."))
+
+        self.cdom = QCheckBox("Compute CDOM metrics from the absorbance spectra")
+        self.cdom.setChecked(True)
+        self.use_base = QCheckBox("Subtract the mean absorbance over")
+        self.base_lo = spin(680, 200, 1100, 1, 0, " nm")
+        self.base_hi = spin(700, 200, 1100, 1, 0, " nm")
+        self.min_r2 = spin(0.95, 0.0, 1.0, 0.01, 2)
+        self.doc = QComboBox()
+        cdom = QGroupBox("Absorbance (CDOM)")
+        f = QFormLayout(cdom)
+        f.addRow(self.cdom)
+        f.addRow("Baseline", pair(self.use_base, self.base_lo, QLabel("–"), self.base_hi))
+        f.addRow("Minimum R² of slope fits", self.min_r2)
+        f.addRow("DOC column (mg/L)", self.doc)
+        f.addRow(note("a254, a350: Napierian absorption coefficients (m⁻¹). S275–295, "
+                      "S350–400, SR: log-linear fits (Helms et al. 2008). E2:E3 = A250/A365. "
+                      "SUVA254 (L mg⁻¹ m⁻¹, Weishaar et al. 2003) needs a DOC column. Values "
+                      "that need a non-positive absorbance or a poor fit are left empty, with "
+                      "the reason in cdom_notes. The R² threshold is an eemkit quality "
+                      "setting, not a literature value: report it."))
+        self.b_compute = primary(QPushButton("Compute indices"))
+        self.b_compute.clicked.connect(self.compute)
+        self.b_export = QPushButton("Save table…")
+        self.b_export.clicked.connect(self.export)
+
+        self.model = DataFrameModel()
+        view = QTableView()
+        view.setModel(self.model)
+        view.setSortingEnabled(False)
+        self.view = view
+
+        self.what = QComboBox()
+        self.x = QComboBox()
+        self.by = QComboBox()
+        for c in (self.what, self.x, self.by):
+            c.currentIndexChanged.connect(self.draw)
+        self.plot = PlotPanel()
+        controls = QHBoxLayout()
+        for lab, w in (("Show", self.what), ("along", self.x), ("grouped by", self.by)):
+            controls.addWidget(QLabel(lab))
+            controls.addWidget(w, 1)
+
+        left = QWidget()
+        ll = QVBoxLayout(left)
+        ll.addWidget(settings)
+        ll.addWidget(cdom)
+        buttons = QHBoxLayout()
+        buttons.addWidget(self.b_compute)
+        buttons.addWidget(self.b_export)
+        ll.addLayout(buttons)
+        ll.addWidget(view, 1)
+        right = QWidget()
+        rl = QVBoxLayout(right)
+        rl.addLayout(controls)
+        rl.addWidget(self.plot, 1)
+        split = QSplitter(Qt.Horizontal)
+        split.addWidget(left)
+        split.addWidget(right)
+        split.setStretchFactor(1, 1)
+        QVBoxLayout(self).addWidget(split)
+        project.changed.connect(self._on_changed)
+        tasks.busy_changed.connect(lambda b: self.b_compute.setEnabled(not b))
+        self.load_settings()
+
+    def load_settings(self) -> None:
+        s = self.project.settings["indices"]
+        self.ex_method.setCurrentText(s["ex_method"])
+        self.bix_den.setValue(float(s["bix_em_den"]))
+        a = self.project.settings["absorbance"]
+        self.use_base.setChecked(bool(a.get("baseline")))
+        if a.get("baseline"):
+            self.base_lo.setValue(float(a["baseline"][0]))
+            self.base_hi.setValue(float(a["baseline"][1]))
+        self.min_r2.setValue(float(a["min_r2"]))
+        self._fill_doc()
+
+    def _fill_doc(self) -> None:
+        ds = self.project.after_raman if self.project.after_raman is not None \
+            else self.project.raw
+        cols = [] if ds is None else [c for c in ds.coords if ds[c].dims == ("sample",)
+                                      and c != "sample"]
+        want = self.project.settings["absorbance"].get("doc_column", "")
+        self.doc.blockSignals(True)
+        self.doc.clear()
+        self.doc.addItems(["(none)"] + sorted(set(cols) | ({want} if want else set())))
+        self.doc.setCurrentText(want or "(none)")
+        self.doc.blockSignals(False)
+
+    def _on_changed(self, what: str) -> None:
+        if what == "settings":
+            self.load_settings()
+        if what in ("raw", "corrected"):
+            self._fill_doc()
+        if what in ("indices", "corrected") and self.project.indices is None:
+            self.model.set_frame(pd.DataFrame())
+            self.plot.clear("Compute the indices to plot them.")
+
+    def compute(self) -> None:
+        if self.project.after_raman is None:
+            QMessageBox.information(self, "eemkit", "Apply the corrections first.")
+            return
+        self.project.set_settings("indices", {"ex_method": self.ex_method.currentText(),
+                                              "bix_em_den": self.bix_den.value()}, "indices")
+        doc = self.doc.currentText()
+        self.project.set_settings("absorbance", {
+            "baseline": [self.base_lo.value(), self.base_hi.value()]
+            if self.use_base.isChecked() else [],
+            "min_r2": self.min_r2.value(),
+            "doc_column": "" if doc == "(none)" else doc}, "indices")
+        ds, settings = self.project.after_raman, self.project.settings
+        with_cdom = self.cdom.isChecked() and "absorbance" in ds
+
+        def work(progress, cancelled):
+            with warnings.catch_warnings(record=True) as caught:
+                warnings.simplefilter("always", EEMKitWarning)
+                df = compute_indices(ds, settings)
+                if with_cdom:
+                    df = df.join(compute_absorbance(ds, settings))
+            return df, [str(w.message) for w in caught]
+
+        def done(result):
+            df, warns = result
+            self.project.indices = df
+            self.project.changed.emit("indices")
+            self.model.set_frame(df)
+            self.view.resizeColumnsToContents()
+            values = [c for c in INDEX_COLUMNS + CDOM_COLUMNS if c in df]
+            meta = [c for c in df.columns if not pd.api.types.is_numeric_dtype(df[c])
+                    and c != "cdom_notes"]
+            # default axes: the campaign columns if chosen, else a column with few values
+            c = self.project.settings["campaigns"]
+            few = [m for m in meta if df[m].nunique() <= len(plot.CATEGORICAL)]
+            timeish = [m for m in meta if any(k in m.lower() for k in
+                                              ("campaign", "date", "month", "time"))]
+            x0 = c.get("time") if c.get("time") in meta else next(
+                (m for m in timeish + meta if 1 < df[m].nunique() <= 40),
+                meta[0] if meta else "")
+            by0 = c.get("group") if c.get("group") in meta else next(
+                (m for m in few if m != x0 and df[m].nunique() > 1), "(none)")
+            for box, items, cur in ((self.what, values, None), (self.x, meta, x0),
+                                    (self.by, ["(none)"] + meta, by0)):
+                box.blockSignals(True)
+                box.clear()
+                box.addItems(items)
+                if cur:
+                    box.setCurrentText(cur)
+                box.blockSignals(False)
+            self.draw()
+            if warns:
+                QMessageBox.information(self, "eemkit", "\n".join(warns))
+
+        self.tasks.run(work, done, "Computing indices…")
+
+    def draw(self) -> None:
+        df = self.project.indices
+        if df is None or not self.what.currentText() or not self.x.currentText():
+            return
+        by = self.by.currentText()
+        data = df.reset_index()
+        if by == "(none)":
+            data["all samples"] = "all"
+            by = "all samples"
+        if data[by].nunique() > len(plot.CATEGORICAL):
+            self.plot.clear(f"'{by}' has more than {len(plot.CATEGORICAL)} groups; choose "
+                            "another grouping.")
+            return
+        fig = plot.scores_over(data, [self.what.currentText()], x=self.x.currentText(), by=by,
+                               width=6.5)
+        self.plot.show_figure(fig)
+
+    def export(self) -> None:
+        if self.project.indices is None:
+            return
+        path, _ = QFileDialog.getSaveFileName(self, "Save indices", "indices.csv", "CSV (*.csv)")
+        if path and self.project.in_data_root(path):
+            QMessageBox.warning(self, "eemkit", "The data folder is read only; choose another "
+                                "folder.")
+        elif path:
+            self.project.indices.to_csv(path, float_format="%.6g")

eemkit/gui/main_window.py

@@ -0,0 +1,258 @@
+"""The main window: a sidebar of steps, one page per step, menus and the shared progress bar."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from PySide6.QtGui import QAction, QActionGroup, QKeySequence
+from PySide6.QtWidgets import (
+    QApplication,
+    QFileDialog,
+    QHBoxLayout,
+    QLabel,
+    QListWidget,
+    QListWidgetItem,
+    QMainWindow,
+    QMessageBox,
+    QStackedWidget,
+    QVBoxLayout,
+    QWidget,
+)
+
+from eemkit import __version__
+from eemkit.gui import theme
+from eemkit.gui.campaigns_tab import CampaignsTab
+from eemkit.gui.common import TaskBar
+from eemkit.gui.corrections_tab import CorrectionsTab
+from eemkit.gui.export_tab import ExportTab
+from eemkit.gui.indices_tab import IndicesTab
+from eemkit.gui.parafac_tab import ParafacTab
+from eemkit.gui.project_tab import ProjectTab
+from eemkit.gui.state import Project
+from eemkit.pipeline import versions
+
+#: Sidebar entries: (title, one-line description).
+STEPS = (("Project and pairing", "Data folder, pairing table"),
+         ("Corrections", "Inner filter, Raman units, scatter"),
+         ("Indices and CDOM", "FI, HIX, BIX, peaks, absorbance"),
+         ("PARAFAC", "Models, validation, outliers"),
+         ("Rivers and dates", "Campaigns, sites, covariates"),
+         ("Export", "Tables, figures, OpenFluor"))
+THEME_NAMES = {"system": "Follow the system", "light": "Light", "dark": "Dark"}
+
+ABOUT = f"""<b>eemkit {__version__}</b><br>
+Processing and PARAFAC modelling of fluorescence excitation-emission matrices
+(EEMs) of dissolved organic matter.<br><br>
+Every result can be reproduced from the saved project file with
+<code>eemkit.pipeline</code>.<br><br>
+Methods: inner filter, Kothawala et al. 2013; Raman units, Lawaetz &amp; Stedmon 2009;
+PARAFAC and split-half validation, Murphy et al. 2013; core consistency,
+Bro &amp; Kiers 2003."""
+
+#: Choices of the View > EEM colours menu (names of eemkit.plot.COLORMAPS).
+EEM_COLOURS = {"eclipse": "Cary Eclipse (violet, blue, green, yellow, red)",
+               "blues": "Single-hue blue (perceptually ordered, for print)"}
+
+
+class MainWindow(QMainWindow):
+    def __init__(self, project_file: str | Path | None = None):
+        super().__init__()
+        self.project = Project()
+        self.tasks = TaskBar()
+        self.project_tab = ProjectTab(self.project, self.tasks)
+        self.corrections_tab = CorrectionsTab(self.project, self.tasks)
+        self.indices_tab = IndicesTab(self.project, self.tasks)
+        self.parafac_tab = ParafacTab(self.project, self.tasks)
+        self.campaigns_tab = CampaignsTab(self.project, self.tasks)
+        self.export_tab = ExportTab(self.project, self.tasks)
+        self.pages = QStackedWidget()
+        self.nav = QListWidget()
+        self.nav.setObjectName("nav")
+        for i, (page, (title, _)) in enumerate(zip(
+                (self.project_tab, self.corrections_tab, self.indices_tab, self.parafac_tab,
+                 self.campaigns_tab, self.export_tab), STEPS, strict=True)):
+            self.pages.addWidget(page)
+            self.nav.addItem(QListWidgetItem(f"{i + 1}   {title}"))
+        self.nav.currentRowChanged.connect(self.pages.setCurrentIndex)
+        self.nav.setCurrentRow(0)
+        self.summary = QLabel("")
+        self.summary.setObjectName("summary")
+        self.summary.setWordWrap(True)
+
+        sidebar = QWidget()
+        sidebar.setObjectName("sidebar")
+        sidebar.setFixedWidth(250)
+        sl = QVBoxLayout(sidebar)
+        sl.setContentsMargins(0, 0, 0, 0)
+        sl.setSpacing(0)
+        brand = QLabel("eemkit")
+        brand.setObjectName("brand")
+        tagline = QLabel("EEM processing and PARAFAC")
+        tagline.setObjectName("tagline")
+        for w in (brand, tagline):
+            sl.addWidget(w)
+        sl.addWidget(self.nav, 1)
+        sl.addWidget(self.summary)
+        central = QWidget()
+        cl = QHBoxLayout(central)
+        cl.setContentsMargins(0, 0, 0, 0)
+        cl.setSpacing(0)
+        cl.addWidget(sidebar)
+        cl.addWidget(self.pages, 1)
+        self.setCentralWidget(central)
+        self.statusBar().addPermanentWidget(self.tasks, 1)
+        self._menus()
+        self.project.changed.connect(lambda _: self._title())
+        self.project.changed.connect(lambda _: self._status())
+        self.resize(1440, 900)
+        if project_file:
+            self.open_project(project_file)
+        self._title()
+        self._status()
+
+    def _status(self) -> None:
+        """Mark finished steps in the sidebar and summarise the project under it."""
+        p = self.project
+        done = (p.raw is not None, p.corrected is not None, p.indices is not None,
+                p.model is not None, p.campaign is not None, False)
+        partial = (p.pairing is not None, p.after_raman is not None, False,
+                   p.exploration is not None, False, False)
+        for i, (title, desc) in enumerate(STEPS):
+            mark = "  ✓" if done[i] else ("  •" if partial[i] else "")
+            item = self.nav.item(i)
+            item.setText(f"{i + 1}   {title}{mark}")
+            item.setToolTip(desc)
+        lines = []
+        if p.pairing is not None and "include" in p.pairing:
+            inc = int((p.pairing["include"].astype(str).str.lower() == "yes").sum())
+            lines.append(f"{len(p.pairing)} rows in the pairing table, {inc} included")
+        if p.raw is not None:
+            lines.append(f"{p.raw.sizes['sample']} samples loaded")
+        if p.model is not None:
+            lines.append(f"Final model: {p.model.sizes['component']} components")
+        self.summary.setText("\n".join(lines) or "Open a project or choose a data folder.")
+
+    def _menus(self) -> None:
+        m = self.menuBar().addMenu("&File")
+        for text, key, slot in (("&New project", QKeySequence.New, self.new_project),
+                                ("&Open project…", QKeySequence.Open, self.open_dialog),
+                                ("&Save project", QKeySequence.Save, self.save_project),
+                                ("Save project &as…", QKeySequence.SaveAs, self.save_as),
+                                (None, None, None),
+                                ("&Quit", QKeySequence.Quit, self.close)):
+            if text is None:
+                m.addSeparator()
+                continue
+            act = QAction(text, self)
+            act.setShortcut(key)
+            act.triggered.connect(slot)
+            m.addAction(act)
+        view = self.menuBar().addMenu("&View")
+        t = view.addMenu("&Theme")
+        tgroup = QActionGroup(self)
+        self.theme_actions = {}
+        current = theme.saved_theme()
+        for name, text in THEME_NAMES.items():
+            act = QAction(text, self, checkable=True)
+            act.setChecked(name == current)
+            act.triggered.connect(lambda _, n=name: self.set_theme(n))
+            tgroup.addAction(act)
+            t.addAction(act)
+            self.theme_actions[name] = act
+        v = view.addMenu("&EEM colours")
+        group = QActionGroup(self)
+        self.colour_actions = {}
+        for name, text in EEM_COLOURS.items():
+            act = QAction(text, self, checkable=True)
+            act.triggered.connect(lambda _, n=name: self.project.set_eem_colours(n))
+            group.addAction(act)
+            v.addAction(act)
+            self.colour_actions[name] = act
+        self.project.changed.connect(self._sync_colours)
+        self._sync_colours("display")
+        h = self.menuBar().addMenu("&Help")
+        act = QAction("&About eemkit", self)
+        act.triggered.connect(self.about)
+        h.addAction(act)
+
+    def set_theme(self, name: str) -> None:
+        """Switch the light/dark theme; a user preference, not part of the project."""
+        theme.save_theme(name)
+        app = QApplication.instance()
+        if app is not None:
+            theme.apply_theme(app, name)
+
+    def _sync_colours(self, what: str) -> None:
+        if what in ("settings", "display"):
+            act = self.colour_actions.get(self.project.eem_colours)
+            if act is not None:
+                act.setChecked(True)
+
+    def _title(self) -> None:
+        name = self.project.path.name if self.project.path else "untitled project"
+        self.setWindowTitle(f"eemkit - {name}{' *' if self.project.dirty else ''}")
+
+    # project files ------------------------------------------------------- #
+
+    def _confirm_discard(self) -> bool:
+        if not self.project.dirty:
+            return True
+        ans = QMessageBox.question(self, "eemkit", "Save the changes to the project first?",
+                                   QMessageBox.Save | QMessageBox.Discard | QMessageBox.Cancel)
+        if ans == QMessageBox.Save:
+            return self.save_project()
+        return ans == QMessageBox.Discard
+
+    def new_project(self) -> None:
+        if self._confirm_discard():
+            self.project.__init__()  # reset in place: the tabs keep their reference
+            self.project.invalidate("pairing")
+            self.project.changed.emit("settings")
+            self.project.changed.emit("display")
+
+    def open_dialog(self) -> None:
+        if not self._confirm_discard():
+            return
+        path, _ = QFileDialog.getOpenFileName(self, "Open project", "", "eemkit project (*.toml)")
+        if path:
+            self.open_project(path)
+
+    def open_project(self, path: str | Path) -> None:
+        try:
+            self.project.open(path)
+        except Exception as exc:  # noqa: BLE001 - shown to the user
+            QMessageBox.warning(self, "eemkit", f"Cannot open {path}:\n{exc}")
+        self._title()
+
+    def save_project(self) -> bool:
+        if self.project.path is None:
+            return self.save_as()
+        self.project.save()
+        self._title()
+        return True
+
+    def save_as(self) -> bool:
+        path, _ = QFileDialog.getSaveFileName(self, "Save project", "project.toml",
+                                              "eemkit project (*.toml)")
+        if not path:
+            return False
+        if self.project.in_data_root(path):
+            QMessageBox.warning(self, "eemkit", "The data folder is read only; save the project "
+                                "elsewhere.")
+            return False
+        self.project.save(path)
+        self.project.changed.emit("settings")
+        self._title()
+        return True
+
+    def about(self) -> None:
+        v = ", ".join(f"{k} {x}" for k, x in versions().items())
+        QMessageBox.about(self, "About eemkit", f"{ABOUT}<br><br><small>{v}</small>")
+
+    def closeEvent(self, event) -> None:  # noqa: N802 (Qt API)
+        if self.tasks.busy:
+            self.tasks.cancel()
+        if self._confirm_discard():
+            event.accept()
+        else:
+            event.ignore()