PyIncucyte 0.3.0__py3-none-any.whl

pyincucyte/__init__.py

@@ -0,0 +1,113 @@
+"""PyIncucyte - download Incucyte live-cell images from Python.
+
+Two ways in.  A desktop app::
+
+    pyincucyte gui                  # or: pyincucyte-gui, python -m pyincucyte.gui
+
+...and an importable API for an automated pipeline::
+
+    from pyincucyte import IncucyteClient
+
+    with IncucyteClient.from_saved() as incucyte:
+        result = incucyte.fetch(
+            vessel=38, output="./run-01", wells="A1-D6",
+            channels="phase,green", layout="time_channel_stack",
+            start_from="first")
+
+    for image in result.files:
+        segment(image.path, well=image.well, channels=image.channels)
+
+``result.files`` carries the well, channel names, timepoints and axis order for
+every file, and the same information is written to ``pyincucyte-manifest.json``
+next to the images so a later stage can pick up without re-parsing filenames.
+"""
+
+import logging
+
+__version__ = "0.3.0"
+
+# A library should not configure logging for its host application; this only
+# stops "No handlers could be found" warnings when nobody has set one up.
+logging.getLogger("pyincucyte").addHandler(logging.NullHandler())
+
+from .errors import (  # noqa: E402
+    ApiError,
+    AuthenticationError,
+    DeviceUnreachableError,
+    EncryptionUnavailableError,
+    ExportCancelled,
+    ExportError,
+    IncucyteError,
+    NotLoggedInError,
+    TokenExpiredError,
+    VesselNotFoundError,
+)
+from .models import (  # noqa: E402
+    DownloadResult,
+    ExportPlan,
+    LAYOUTS,
+    LAYOUT_AXES,
+    LAYOUT_DESCRIPTIONS,
+    LAYOUT_LABELS,
+    OutputFile,
+    ProgressEvent,
+    Vessel,
+    human_bytes,
+    resolve_layout,
+)
+from .options import ExportOptions  # noqa: E402
+from .config import ConfigStore, Credentials  # noqa: E402
+from .state import StateStore  # noqa: E402
+from .client import IncucyteClient  # noqa: E402
+from .watch import Watcher  # noqa: E402
+from .manifest import load_manifest, write_manifest  # noqa: E402
+from .engine import DEFAULT_HOST, APP_DIR  # noqa: E402
+
+# Import names retired in 0.3 - see pyincucyte.compat.
+from . import compat  # noqa: E402
+
+compat.install()
+
+
+def connect(host=None, username=None, password=None):
+    """Return a ready client - saved login by default, or fresh credentials."""
+    if username and password:
+        return IncucyteClient.connect(host or DEFAULT_HOST, username, password)
+    return IncucyteClient.from_saved(host)
+
+
+__all__ = [
+    "__version__",
+    "connect",
+    "IncucyteClient",
+    "ExportOptions",
+    "ExportPlan",
+    "DownloadResult",
+    "OutputFile",
+    "ProgressEvent",
+    "Vessel",
+    "Watcher",
+    "StateStore",
+    "ConfigStore",
+    "Credentials",
+    "LAYOUTS",
+    "LAYOUT_AXES",
+    "LAYOUT_LABELS",
+    "LAYOUT_DESCRIPTIONS",
+    "resolve_layout",
+    "human_bytes",
+    "load_manifest",
+    "write_manifest",
+    "DEFAULT_HOST",
+    "APP_DIR",
+    "IncucyteError",
+    "ApiError",
+    "AuthenticationError",
+    "NotLoggedInError",
+    "TokenExpiredError",
+    "DeviceUnreachableError",
+    "EncryptionUnavailableError",
+    "VesselNotFoundError",
+    "ExportError",
+    "ExportCancelled",
+]

pyincucyte/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m pyincucyte`` runs the command line interface."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

pyincucyte/cache.py

@@ -0,0 +1,169 @@
+"""A local cache of source image payloads.
+
+Time stacks have an awkward property: a stack must contain every frame, so the
+arrival of one new scan invalidates the whole file.  Rebuilt naively, a watch
+loop re-downloads the entire experiment on every poll — an hour into a five-day
+run that is already thousands of redundant images, and it gets worse every hour.
+
+The cache fixes that by keeping each source payload on disk the first time it is
+fetched.  Rebuilding a stack then costs one disk read per frame instead of one
+network round trip, and only genuinely new frames touch the instrument.
+
+It is a cache, not a record: deleting it only costs time.
+"""
+
+import logging
+import os
+import shutil
+import threading
+import time
+from pathlib import Path
+
+log = logging.getLogger("pyincucyte.cache")
+
+#: Folder created inside the output directory.
+CACHE_DIRNAME = ".pyincucyte-cache"
+
+#: Cached payloads older than this are swept away (14 days).
+DEFAULT_MAX_AGE_SECONDS = 14 * 24 * 3600
+
+
+def payload_key(item):
+    """Return the stable identity of one source image payload."""
+    scan = str(item.get("scan_time", "")).replace(":", "").replace("-", "")
+    scan = scan.replace("+", "_").replace(".", "_")
+    return (f"V{item.get('vessel_id')}_r{item.get('row', 0)}"
+            f"_c{item.get('col', 0)}_s{item.get('site', 0)}"
+            f"_t{item.get('img_type', 1)}_{scan}.tif")
+
+
+class PayloadCache:
+    """Stores raw payload bytes on disk, keyed by well/channel/scan time."""
+
+    def __init__(self, root, max_age_seconds=DEFAULT_MAX_AGE_SECONDS):
+        self.root = Path(root)
+        self.max_age_seconds = max_age_seconds
+        self.hits = 0
+        self.misses = 0
+        self._lock = threading.Lock()
+        self._ready = False
+
+    # -- lifecycle --------------------------------------------------------
+
+    def _ensure(self):
+        if self._ready:
+            return True
+        with self._lock:
+            if self._ready:
+                return True
+            try:
+                self.root.mkdir(parents=True, exist_ok=True)
+                self._ready = True
+            except OSError as exc:
+                log.debug("payload cache unavailable at %s: %s", self.root, exc)
+                return False
+        return True
+
+    # -- access -----------------------------------------------------------
+
+    def get(self, item):
+        """Return cached bytes for this item, or None."""
+        path = self.root / payload_key(item)
+        try:
+            data = path.read_bytes()
+        except OSError:
+            with self._lock:
+                self.misses += 1
+            return None
+        if not data:
+            with self._lock:
+                self.misses += 1
+            return None
+        with self._lock:
+            self.hits += 1
+        return data
+
+    def put(self, item, data):
+        """Store payload bytes. Failures are ignored — it is only a cache."""
+        if not data or not self._ensure():
+            return
+        path = self.root / payload_key(item)
+        tmp = path.with_suffix(".part")
+        try:
+            tmp.write_bytes(data)
+            os.replace(tmp, path)
+        except OSError:
+            try:
+                tmp.unlink()
+            except OSError:
+                pass
+
+    # -- housekeeping -----------------------------------------------------
+
+    def size_bytes(self):
+        try:
+            return sum(f.stat().st_size for f in self.root.glob("*.tif"))
+        except OSError:
+            return 0
+
+    def count(self):
+        try:
+            return sum(1 for _ in self.root.glob("*.tif"))
+        except OSError:
+            return 0
+
+    def sweep(self, max_age_seconds=None):
+        """Delete cached payloads older than the age limit. Returns the count."""
+        limit = self.max_age_seconds if max_age_seconds is None else max_age_seconds
+        if not limit or not self.root.is_dir():
+            return 0
+        cutoff = time.time() - limit
+        removed = 0
+        for path in self.root.glob("*.tif"):
+            try:
+                if path.stat().st_mtime < cutoff:
+                    path.unlink()
+                    removed += 1
+            except OSError:
+                continue
+        return removed
+
+    def clear(self):
+        """Remove the cache folder entirely."""
+        try:
+            shutil.rmtree(self.root)
+        except OSError:
+            pass
+        self._ready = False
+
+    @property
+    def hit_rate(self):
+        total = self.hits + self.misses
+        return (self.hits / total) if total else 0.0
+
+    def summary(self):
+        from .models import human_bytes
+        return (f"{self.count():,} cached payloads ({human_bytes(self.size_bytes())}), "
+                f"{self.hits:,} hits / {self.misses:,} misses")
+
+    def __repr__(self):
+        return f"<PayloadCache {self.root} hits={self.hits} misses={self.misses}>"
+
+
+def cache_for_output(output_dir, mode="auto", layout="separate",
+                     max_age_seconds=DEFAULT_MAX_AGE_SECONDS):
+    """Return the cache to use for a download, or None.
+
+    ``"auto"`` caches only for the layouts that rebuild whole files when a scan
+    arrives — the ones where the cache actually saves work.
+    """
+    if mode == "never":
+        return None
+    if mode == "auto" and "time" not in layout:
+        return None
+    return PayloadCache(Path(output_dir) / CACHE_DIRNAME,
+                        max_age_seconds=max_age_seconds)
+
+
+__all__ = ["PayloadCache", "cache_for_output", "payload_key", "CACHE_DIRNAME",
+           "DEFAULT_MAX_AGE_SECONDS"]

pyincucyte/channels.py

@@ -0,0 +1,89 @@
+"""Channel identity: the Incucyte's three acquisition channels.
+
+The device numbers its channels 1/2/3 ("ImageType").  Channel 1 is the
+transmitted-light Phase image; channels 2 and 3 are the two fluorescence
+"Colors", which the instrument reports as Green and Red respectively but which
+an experiment can rename (e.g. "GFP", "mCherry").
+"""
+
+import re
+
+from .engine import (
+    CHANNEL_HELP,
+    IMAGE_TYPE_LABELS,
+    IMAGE_TYPE_MAP,
+    IMAGE_TYPE_SHORT_LABELS,
+    channel_name_from_channels,
+    channel_tag,
+    image_type_label,
+    image_type_sort_key,
+    parse_channels,
+)
+
+#: Symbolic channel numbers, matching the device's ImageType field.
+PHASE = 1
+COLOR1 = GREEN = 2
+COLOR2 = RED = 3
+
+#: Every channel, in acquisition order.
+ALL_CHANNELS = (PHASE, COLOR1, COLOR2)
+
+
+def channel_token(label):
+    """Return a filename-safe token for a channel display name."""
+    token = re.sub(r"[^a-z0-9]+", "-", str(label).lower()).strip("-")
+    return token or "channel"
+
+
+def format_channels(channels, labels=None):
+    """Return a human-readable channel list, e.g. ``"Phase + GFP"``."""
+    if channels is None:
+        return "all channels"
+    labels = labels or IMAGE_TYPE_LABELS
+    names = [labels.get(c, image_type_label(c))
+             for c in sorted(channels, key=image_type_sort_key)]
+    return " + ".join(names) if names else "no channels"
+
+
+def channel_spec(channels):
+    """Return the CLI ``--channels`` spec string for a set of channel numbers."""
+    if channels is None:
+        return "all"
+    names = [IMAGE_TYPE_SHORT_LABELS.get(c, f"type{c}")
+             for c in sorted(channels, key=image_type_sort_key)]
+    return ",".join(names) or "all"
+
+
+def labels_for_vessel(vessel_channels):
+    """Return ``{channel_number: display name}`` for one vessel's metadata."""
+    labels = dict(IMAGE_TYPE_LABELS)
+    if isinstance(vessel_channels, dict):
+        labels[COLOR1] = channel_name_from_channels(vessel_channels, COLOR1)
+        labels[COLOR2] = channel_name_from_channels(vessel_channels, COLOR2)
+    return labels
+
+
+def active_channels(vessel_channels):
+    """Return the channel numbers actually switched on for a vessel."""
+    if not isinstance(vessel_channels, dict):
+        return set()
+    active = set()
+    if (vessel_channels.get("Phase") or {}).get("On"):
+        active.add(PHASE)
+    colors = vessel_channels.get("Colors") or {}
+    if isinstance(colors, dict):
+        if (colors.get("Color1") or {}).get("On"):
+            active.add(COLOR1)
+        if (colors.get("Color2") or {}).get("On"):
+            active.add(COLOR2)
+    return active
+
+
+__all__ = [
+    "PHASE", "COLOR1", "COLOR2", "GREEN", "RED", "ALL_CHANNELS",
+    "CHANNEL_HELP", "IMAGE_TYPE_LABELS", "IMAGE_TYPE_MAP",
+    "IMAGE_TYPE_SHORT_LABELS", "parse_channels", "channel_name_from_channels",
+    "channel_tag", "image_type_label", "image_type_sort_key",
+    "channel_token", "format_channels", "channel_spec",
+    "labels_for_vessel", "active_channels",
+]