tofscope 0.1.0__py3-none-any.whl

tofscope/application/explore.py

@@ -0,0 +1,161 @@
+from dataclasses import replace
+from tofscope.science.depth_calibration import DepthAnchor, validate_anchors
+from tofscope.application.commands import CommandEnvelope
+from tofscope.application.models import DisplaySettings, SignalSnapshot
+from tofscope.application.signals import get_signal, normalize_view, usable_frames, valid_name
+from tofscope.application.analyses import Conflict, CapacityError
+from tofscope.science.signals import SignalRecipe
+
+
+class ExploreService:
+    def __init__(self, workspaces, repository):
+        self.analyses = workspaces
+        self.repository = repository
+
+    def stored(self, s, index, frames=None):
+        if not 0 <= index < len(s.peaks):
+            raise ValueError("Unknown stored channel.")
+        coverage = tuple(frames) if frames is not None else (0, s.shape[0] - 1)
+        if not 0 <= coverage[0] <= coverage[1] < s.shape[0]:
+            raise ValueError("Coverage outside acquisition.")
+        p = s.peaks[index]
+        return SignalRecipe(
+            label=f"{p.label} · {p.mass:g} Th",
+            source="stored",
+            stored_index=index,
+            intervals=((p.low, p.high),),
+            frames=coverage,
+        )
+
+    def validate_envelope(self, e, envelope, fingerprint, check_source=True):
+        s = e.snapshot
+        if e.closed:
+            raise KeyError("Analysis unavailable.")
+        if envelope.request_id in e.receipts:
+            old, result = e.receipts[envelope.request_id]
+            if old != fingerprint:
+                raise Conflict("Request ID reused with different content.", s.revision)
+            return result
+        if envelope.expected_revision != s.revision:
+            raise Conflict("Analysis revision changed.", s.revision)
+        if envelope.dataset_generation != s.dataset.generation:
+            raise Conflict("Acquisition generation changed.", s.revision)
+        if check_source:
+            self.repository.assert_current(s.owner, s.dataset)
+        return None
+
+    def receipt(self, e, request_id, fingerprint, result):
+        e.receipts[request_id] = (fingerprint, result)
+        while len(e.receipts) > 256:
+            e.receipts.popitem(last=False)
+
+    def apply(self, owner, analysis_id, envelope):
+        if not isinstance(envelope, CommandEnvelope):
+            envelope = CommandEnvelope(**envelope)
+        fingerprint = envelope.model_dump_json()
+        e = self.analyses.entry(owner, analysis_id)
+        with self.analyses.signal_lock, e.lock:
+            previous = self.validate_envelope(e, envelope, fingerprint)
+            if previous is not None:
+                return previous
+            s = e.snapshot
+            c = envelope.command
+            kind = c.type
+            patch = {}
+            if kind == 'add_stored_signal':
+                recipe = self.stored(s, c.index, c.frames)
+                old = next((r for r in s.signals if r.recipe is not None and
+                            r.recipe.source == 'stored' and r.recipe.stored_index == c.index and
+                            r.recipe.frames == recipe.frames), None)
+                if old and not c.duplicate:
+                    patch['profile_signal_ids'] = tuple(dict.fromkeys((*s.profile_signal_ids, old.id)))
+                else:
+                    self.analyses.admit_signal(owner, len(s.signals))
+                    signal = SignalSnapshot(recipe.id, recipe.label, s.next_style_index, recipe)
+                    patch = dict(signals=(*s.signals, signal), next_style_index=s.next_style_index+1,
+                                 profile_signal_ids=(*s.profile_signal_ids, signal.id))
+            elif kind == 'annotate_signal':
+                from tofscope.application.identification import assignment
+                signal = get_signal(s, c.signal_id)
+                updated = replace(signal, assignment=assignment(c.candidate_id, c.measured_mz))
+                patch['signals'] = tuple(updated if r.id == signal.id else r for r in s.signals)
+            elif kind in ('rename_signal', 'select_image_signal', 'set_profile_visible', 'remove_signal', 'set_stored_coverage'):
+                signal = get_signal(s, c.signal_id)
+                if kind == 'rename_signal':
+                    updated = replace(signal, name=valid_name(c.name), name_revision=signal.name_revision+1)
+                    patch['signals'] = tuple(updated if r.id == signal.id else r for r in s.signals)
+                elif kind == 'select_image_signal':
+                    if not usable_frames(s, signal):
+                        raise ValueError('Signal has no ready coverage in the acquisition.')
+                    patch['image_signal_id'] = signal.id
+                elif kind == 'set_profile_visible':
+                    if signal.id == s.image_signal_id and not c.visible:
+                        raise ValueError('The image signal is included in its depth profile.')
+                    if signal.recipe is None:
+                        raise ValueError('Signal calculation is not ready.')
+                    patch['profile_signal_ids'] = tuple(dict.fromkeys((*s.profile_signal_ids, signal.id))) if c.visible else tuple(x for x in s.profile_signal_ids if x != signal.id)
+                elif kind == 'remove_signal':
+                    patch['signals'] = tuple(r for r in s.signals if r.id != signal.id)
+                    patch['profile_signal_ids'] = tuple(x for x in s.profile_signal_ids if x != signal.id)
+                    if signal.id == s.image_signal_id:
+                        eligible = [r for r in patch['signals'] if usable_frames(s, r)]
+                        if not eligible:
+                            raise ValueError('Add another ready image signal before removing this one.')
+                        patch['image_signal_id'] = eligible[0].id
+                else:
+                    if signal.recipe is None or signal.recipe.source != 'stored':
+                        raise ValueError('Only stored channel coverage can be changed without calculation.')
+                    first, last = c.frames
+                    if not 0 <= first <= last < s.shape[0]:
+                        raise ValueError('Coverage outside acquisition.')
+                    updated = replace(signal, recipe=replace(signal.recipe, frames=tuple(c.frames)), recipe_version=signal.recipe_version+1)
+                    patch['signals'] = tuple(updated if r.id == signal.id else r for r in s.signals)
+            elif kind == 'set_spatial':
+                from tofscope.application.spatial import validate_spatial
+                patch['spatial'] = validate_spatial(c.spatial, s.signals)
+            elif kind == 'set_roi':
+                x0, x1, y0, y1 = c.roi
+                if not 0 <= x0 <= x1 < s.shape[2] or not 0 <= y0 <= y1 < s.shape[1]:
+                    raise ValueError('ROI outside pixel domain.')
+                patch['roi'] = tuple(c.roi)
+            elif kind == 'set_depth':
+                d = c.depth
+                first, last = 0, s.shape[0] - 1
+                if d.mode == 'frame' and not first <= d.index <= last:
+                    raise ValueError('Frame outside acquisition.')
+                if d.mode == 'window' and not first <= d.first <= d.last <= last:
+                    raise ValueError('Window outside acquisition.')
+                patch['depth'] = d
+            elif kind == 'set_depth_anchors':
+                anchors = validate_anchors(tuple(DepthAnchor(x.frame, x.depth_nm) for x in c.anchors), s.shape[0])
+                patch['depth_anchors'] = anchors
+                if len(anchors) < 2:
+                    patch['depth_coordinates'] = 'frame'
+            elif kind == 'set_depth_display':
+                if c.coordinates == 'depth' and len(s.depth_anchors) < 2:
+                    raise ValueError('Add a positive-depth anchor first.')
+                patch.update(depth_unit=c.unit, depth_coordinates=c.coordinates)
+            elif kind == 'set_display':
+                patch['display'] = DisplaySettings(c.log, c.relative, c.image, s.display.spectrum_log if c.spectrum_log is None else c.spectrum_log, s.display.colormap if c.colormap is None else c.colormap)
+            if kind == 'remove_signal':
+                patch['spatial'] = s.spatial.model_copy(update={
+                    'layers': tuple(x for x in s.spatial.layers if x.signal_id != signal.id),
+                    'solo': None if s.spatial.solo == signal.id else s.spatial.solo,
+                })
+            result = normalize_view(replace(s, revision=s.revision+1, **patch))
+            if result.isotope_measurement:
+                from tofscope.application.identification import current_result
+                result = replace(result, isotope_measurement=current_result(result))
+            if kind == 'remove_signal':
+                e.tokens.pop(signal.id, None)
+            # Hidden and removed signals retain metadata without pinned volume leases.
+            visible = set(result.profile_signal_ids) | {result.image_signal_id}
+            for sid in list(e.leases):
+                if sid not in visible or kind == 'set_stored_coverage' and sid == signal.id:
+                    e.leases.pop(sid).release()
+            e.snapshot = result
+            if kind == "remove_signal":
+                for callback in self.analyses.on_remove:
+                    callback(analysis_id, signal.id)
+            self.receipt(e, envelope.request_id, fingerprint, result)
+            return result

tofscope/application/identification.py

@@ -0,0 +1,153 @@
+"""Owner-scoped atomic matching and explicit, bounded isotope measurements."""
+from dataclasses import dataclass, replace, asdict
+import hashlib
+import json
+import numpy as np
+from tofscope.application.identification_models import (
+    AtomicAssignment, CatalogProvenance, CandidateResult, MeasuredSignal, MeasurementResult,
+)
+from tofscope.application.signals import get_signal
+from tofscope.application.analyses import CapacityError
+from tofscope.science.isotopes import CATALOG_PATH, load_catalog, find_candidates, ion_mz, CandidateLimitExceeded
+from tofscope.science.abundance import measure_isotopes
+
+
+def catalog_provenance():
+    meta = json.loads(CATALOG_PATH.read_text())['metadata']
+    return CatalogProvenance(meta['records_sha256'], meta['retrieved'], json.dumps(meta['sources'], sort_keys=True))
+
+
+def assignment(candidate_id, measured_mz=None):
+    if candidate_id is None:
+        return None
+    for isotope in load_catalog():
+        for charge in (-3, -2, -1, 1, 2, 3):
+            if candidate_id == f'{isotope.symbol}-{isotope.mass_number}:{charge:+d}':
+                predicted = ion_mz(isotope, charge)
+                error = measured_mz - predicted if measured_mz is not None else None
+                return AtomicAssignment(candidate_id, isotope, charge, predicted, catalog_provenance(),
+                                        measured_mz, error, error / predicted * 1e6 if error is not None else None)
+    raise ValueError('Atomic candidate unavailable.')
+
+
+def requested_frames(snapshot):
+    depth = snapshot.depth
+    return ((depth.index, depth.index) if depth.mode == 'frame' else
+            (depth.first, depth.last) if depth.mode == 'window' else (0, snapshot.shape[0] - 1))
+
+
+def dependency_key(snapshot, ids):
+    rows = []
+    for sid in ids:
+        signal = get_signal(snapshot, sid)
+        rows.append((sid, signal.recipe_version, asdict(signal.recipe) if signal.recipe else None,
+                     signal.materialization_id, asdict(signal.assignment) if signal.assignment else None))
+    value = (snapshot.dataset.generation, snapshot.roi, requested_frames(snapshot), rows)
+    return hashlib.sha256(json.dumps(value, sort_keys=True).encode()).hexdigest()
+
+
+def current_result(snapshot):
+    result = snapshot.isotope_measurement
+    if result is None:
+        return None
+    try:
+        stale = snapshot.stale or result.dependency_key != dependency_key(snapshot, [r.signal_id for r in result.rows])
+    except ValueError:
+        stale = True
+    return replace(result, out_of_date=stale)
+
+
+@dataclass(frozen=True)
+class MeasurementTask:
+    snapshot: object
+    signal_ids: tuple[str, ...]
+    dependency_key: str
+
+
+class IdentificationService:
+    def __init__(self, analyses, explore, cache, jobs):
+        self.analyses, self.explore, self.cache, self.jobs = analyses, explore, cache, jobs
+        self.catalog = load_catalog()
+        self.provenance = catalog_provenance()
+        jobs.measurement_handler = self.run
+
+    def candidates(self, owner, aid, mz, tolerance, unit, charges):
+        s = self.analyses.get(owner, aid)
+        self.cache.repository.assert_current(owner, s.dataset)
+        limit = min(256, max(0, (self.jobs.settings.response_bytes - 4096) // 2048))
+        try:
+            candidates = find_candidates(mz, tolerance, unit, charges, self.catalog, max_results=limit)
+        except CandidateLimitExceeded as exc:
+            raise CapacityError(str(exc)) from None
+        return CandidateResult(tuple(candidates), self.provenance)
+
+    def measure(self, owner, aid, envelope, recipe_ids):
+        ids = tuple(recipe_ids)
+        fingerprint = json.dumps({'isotopes': ids, 'envelope': envelope.model_dump(mode='json')}, sort_keys=True)
+        e = self.analyses.entry(owner, aid)
+        with e.lock:
+            old = self.explore.validate_envelope(e, envelope, fingerprint)
+            if old is not None:
+                return old
+            s = e.snapshot
+            if not ids or len(ids) > 128 or len(set(ids)) != len(ids):
+                raise ValueError('Choose 1–128 distinct ready signals.')
+            if any(get_signal(s, sid).recipe is None for sid in ids):
+                raise ValueError('Finish signal calculations before measuring.')
+            task = MeasurementTask(s, ids, dependency_key(s, ids))
+            with self.jobs.condition:
+                job = self.jobs.enqueue_task(owner, task, 'measurement', aid)
+                self.jobs.jobs[job.id].referenced = True
+                previous = self.jobs.jobs.get(s.isotope_job_id)
+                if previous:
+                    previous.referenced = False
+                terminal = [jid for jid, item in self.jobs.jobs.items()
+                            if item.owner == owner and not item.referenced and
+                            item.snapshot.status in {'succeeded', 'failed', 'cancelled', 'obsolete'}]
+                for jid in terminal[:-256]:
+                    del self.jobs.jobs[jid]
+            # A new explicit measurement supersedes an earlier pending result.
+            e.snapshot = replace(s, revision=s.revision+1, isotope_job_id=job.id)
+            self.explore.receipt(e, envelope.request_id, fingerprint, job)
+            return job
+
+    def result(self, owner, aid):
+        s = self.analyses.get(owner, aid)
+        self.cache.repository.assert_current(owner, s.dataset)
+        return current_result(s)
+
+    def run(self, job):
+        task = job.task
+        s = task.snapshot
+        e = self.analyses.entry(job.owner, s.id)
+        signals = tuple(get_signal(s, sid) for sid in task.signal_ids)
+
+        def cancelled():
+            return (job.cancelled.is_set() or e.closed or e.snapshot.dataset != s.dataset or
+                    e.snapshot.isotope_job_id != job.snapshot.id)
+
+        def check():
+            if cancelled():
+                raise InterruptedError()
+
+        def read(path, recipe):
+            with e.lock:
+                check()
+            signal = next(row for row in signals if row.recipe.id == recipe.id)
+            return self.cache.load(job.owner, s.id, s.dataset, recipe,
+                materialization_id=signal.materialization_id, cancel=cancelled)
+
+        # The numerical routine owns one lease at a time; it never accumulates volumes.
+        rows = measure_isotopes(None, [r.recipe for r in signals], s.roi, requested_frames(s), reader=read)
+        if any(r.summed_intensity is not None and not np.isfinite(r.summed_intensity) for r in rows):
+            raise ValueError('Non-finite measurement intensity.')
+        result = MeasurementResult(job.snapshot.id, s.dataset.generation, s.roi, requested_frames(s),
+            task.dependency_key, tuple(MeasuredSignal(row.id, row.name, row.assignment, row.recipe.intervals, value)
+                                       for row, value in zip(signals, rows)), self.provenance)
+        with e.lock:
+            check()
+            self.cache.repository.assert_current(job.owner, s.dataset)
+            # Preserve captured results even if ROI/recipes changed while the job ran.
+            updated = replace(e.snapshot, revision=e.snapshot.revision+1, isotope_measurement=result)
+            e.snapshot = replace(updated, isotope_measurement=current_result(updated))
+        return None

tofscope/application/identification_models.py

@@ -0,0 +1,75 @@
+"""Captured atomic assignments and isotope measurement provenance."""
+from dataclasses import dataclass
+import json
+import math
+import re
+from tofscope.science.isotopes import IsotopeRecord, IonCandidate, ion_mz
+from tofscope.science.abundance import IsotopeMeasurement
+
+
+@dataclass(frozen=True)
+class CatalogProvenance:
+    records_sha256: str
+    retrieved: str
+    sources_json: str
+    convention: str = 'Neutral isotope mass minus signed electron mass; binding energies omitted.'
+
+    def __post_init__(self):
+        if not re.fullmatch(r'[0-9a-f]{64}', self.records_sha256) or not self.retrieved or not self.convention:
+            raise ValueError('Incomplete catalog provenance.')
+        if not json.loads(self.sources_json):
+            raise ValueError('Missing catalog sources.')
+
+
+@dataclass(frozen=True)
+class AtomicAssignment:
+    candidate_id: str
+    isotope: IsotopeRecord
+    charge: int
+    predicted_mz: float
+    catalog: CatalogProvenance
+    measured_mz: float | None = None
+    error_Th: float | None = None
+    error_ppm: float | None = None
+
+    def __post_init__(self):
+        expected = ion_mz(self.isotope, self.charge)
+        identity = f'{self.isotope.symbol}-{self.isotope.mass_number}:{self.charge:+d}'
+        if self.candidate_id != identity or not math.isclose(self.predicted_mz, expected, rel_tol=1e-12):
+            raise ValueError('Inconsistent atomic assignment.')
+        if self.measured_mz is None:
+            if self.error_Th is not None or self.error_ppm is not None:
+                raise ValueError('Mass errors require a measured mass.')
+        elif (not math.isfinite(self.measured_mz) or self.measured_mz <= 0 or
+              self.error_Th is None or self.error_ppm is None or
+              not math.isclose(self.error_Th, self.measured_mz - expected, abs_tol=1e-12) or
+              not math.isclose(self.error_ppm, (self.measured_mz - expected) / expected * 1e6, abs_tol=1e-9)):
+            raise ValueError('Inconsistent measured mass error.')
+
+
+@dataclass(frozen=True)
+class CandidateResult:
+    candidates: tuple[IonCandidate, ...]
+    catalog: CatalogProvenance
+
+
+@dataclass(frozen=True)
+class MeasuredSignal:
+    signal_id: str
+    name: str
+    assignment: AtomicAssignment | None
+    intervals: tuple[tuple[float, float], ...]
+    measurement: IsotopeMeasurement
+
+
+@dataclass(frozen=True)
+class MeasurementResult:
+    job_id: str
+    dataset_generation: str
+    roi: tuple[int, int, int, int]
+    frames: tuple[int, int]
+    dependency_key: str
+    rows: tuple[MeasuredSignal, ...]
+    catalog: CatalogProvenance
+    out_of_date: bool = False
+    interpretation: str = 'Selected-set signal fractions; not quantitative composition.'