scistack-db 0.1.9.dev0__py3-none-any.whl

scidb/column_selection.py

@@ -0,0 +1,166 @@
+"""Column selection wrapper for variable types in for_each (DB-backed)."""
+
+from typing import Any
+
+
+class ColumnSelection:
+    """
+    Wraps a variable class with column selection for use in for_each() inputs.
+
+    Created automatically by BaseVariable.__class_getitem__ when using bracket
+    syntax:
+
+        MyVar["col_name"]           # single column -> numpy array
+        MyVar[["col_a", "col_b"]]   # multiple columns -> DataFrame subset
+
+    After loading, only the specified columns are extracted from the loaded
+    DataFrame. Single column selection returns a numpy array; multiple columns
+    return a DataFrame subset.
+
+    When ``iterate=True`` (constructed via ``MyVar.for_columns(...)``) the
+    selection means "run fn once per column and reassemble the per-column
+    results into a single wide output variable" rather than "pass the columns
+    as one argument." An **empty** ``columns`` (``[]``, the default) means "all
+    data columns", resolved at for_each time. ``None`` is accepted as an alias
+    for the empty/all sentinel for backward compatibility.
+
+    For standalone DataFrame usage, see scifor.ColumnSelection.
+    """
+
+    def __init__(
+        self, var_type: type, columns: "list[str] | None" = None, iterate: bool = False
+    ):
+        """
+        Args:
+            var_type: The variable class to load.
+            columns: List of column names to extract after loading. An empty
+                list ``[]`` (the default) means "all data columns", resolved at
+                for_each time (only meaningful with ``iterate=True``). ``None``
+                is accepted as an alias for ``[]``.
+            iterate: If True, iterate over the columns (one fn call each) and
+                reassemble into one wide output; if False (default), pass the
+                column(s) as a single argument.
+        """
+        if columns is None:
+            columns = []
+        self.var_type = var_type
+        # Normalize the all-columns sentinel to an empty list (copying any
+        # provided list so a shared default object is never mutated).
+        self.columns = list(columns) if columns else []
+        self.iterate = iterate
+
+    @property
+    def __name__(self) -> str:
+        """Return a display name for format_inputs and error messages."""
+        var_name = getattr(self.var_type, "__name__", type(self.var_type).__name__)
+        suffix = ", iterate" if self.iterate else ""
+        if not self.columns:
+            return f"{var_name}[<all columns>{suffix}]"
+        if len(self.columns) == 1 and not self.iterate:
+            return f'{var_name}["{self.columns[0]}"]'
+        cols = ", ".join(f'"{c}"' for c in self.columns)
+        return f"{var_name}[{cols}{suffix}]"
+
+    def load(self, **metadata) -> Any:
+        """Load from the underlying var_type, then apply column selection."""
+        return self.var_type.load(**metadata)
+
+    def to_csv(self, filename: str, *args, **kwargs) -> None:
+        """Export the selected column(s) to a CSV file in flat table format.
+
+        Writes one row per schema_id with the selected columns as value
+        columns. The underlying variable must be a single-row table per
+        schema_id. ``filename`` must end with ``.csv``. ``kwargs`` mirror
+        ``load()`` (``where=``, ``version=``, ``db=``, metadata).
+
+        Example:
+            GaitData["Speed"].to_csv("speed.csv", subject=1)
+            GaitData[["Speed", "Cadence"]].to_csv("gait.csv", subject=1)
+        """
+        from scidb.csv_export import export_csv
+
+        export_csv(self, filename, *args, **kwargs)
+
+    # --- Comparison operators that produce ColumnFilter objects ---
+
+    def __eq__(self, other):
+        try:
+            from scidb.filters import ColumnFilter
+
+            return ColumnFilter(self.var_type, self.columns[0], "==", other)
+        except ImportError:
+            raise NotImplementedError(
+                "Comparison operators on ColumnSelection require scidb."
+            )
+
+    def __ne__(self, other):
+        try:
+            from scidb.filters import ColumnFilter
+
+            return ColumnFilter(self.var_type, self.columns[0], "!=", other)
+        except ImportError:
+            raise NotImplementedError(
+                "Comparison operators on ColumnSelection require scidb."
+            )
+
+    def __lt__(self, other):
+        try:
+            from scidb.filters import ColumnFilter
+
+            return ColumnFilter(self.var_type, self.columns[0], "<", other)
+        except ImportError:
+            raise NotImplementedError(
+                "Comparison operators on ColumnSelection require scidb."
+            )
+
+    def __le__(self, other):
+        try:
+            from scidb.filters import ColumnFilter
+
+            return ColumnFilter(self.var_type, self.columns[0], "<=", other)
+        except ImportError:
+            raise NotImplementedError(
+                "Comparison operators on ColumnSelection require scidb."
+            )
+
+    def __gt__(self, other):
+        try:
+            from scidb.filters import ColumnFilter
+
+            return ColumnFilter(self.var_type, self.columns[0], ">", other)
+        except ImportError:
+            raise NotImplementedError(
+                "Comparison operators on ColumnSelection require scidb."
+            )
+
+    def __ge__(self, other):
+        try:
+            from scidb.filters import ColumnFilter
+
+            return ColumnFilter(self.var_type, self.columns[0], ">=", other)
+        except ImportError:
+            raise NotImplementedError(
+                "Comparison operators on ColumnSelection require scidb."
+            )
+
+    def isin(self, values):
+        """Create an InFilter for set membership testing."""
+        try:
+            from scidb.filters import InFilter
+
+            return InFilter(self.var_type, self.columns[0], list(values))
+        except ImportError:
+            raise NotImplementedError("isin() on ColumnSelection requires scidb.")
+
+    def to_key(self) -> str:
+        """Return a canonical string for use as a version key.
+
+        Includes ``iterate`` and the resolved column list so that changing the
+        iterated column set (including the empty ``[]`` -> all-columns
+        resolution done before this is called) invalidates cached results.
+        """
+        name = getattr(self.var_type, "__name__", repr(self.var_type))
+        return f"{name}[{self.columns!r}, iterate={self.iterate}]"
+
+    def __hash__(self):
+        return hash((self.var_type, tuple(self.columns), self.iterate))

scidb/constant.py

@@ -0,0 +1,295 @@
+"""
+Constant — a lightweight wrapper for pipeline configuration values.
+
+Scientific pipelines accumulate magic numbers: sampling rates, bandpass limits,
+epoch durations, regularization weights, etc. Wrapping them in ``constant(...)``
+gives each value a description and a source location so the GUI sidebar can
+surface them, while still letting the value behave transparently like its
+underlying type.
+
+Example:
+    from scidb import constant
+
+    SAMPLING_RATE_HZ = constant(
+        1000,
+        description="Default sampling rate for all recordings",
+    )
+
+    DEFAULT_BANDPASS = constant(
+        (1.0, 40.0),
+        description="Standard LFP bandpass (Hz)",
+    )
+
+    # Transparent use:
+    duration = 5 * SAMPLING_RATE_HZ          # 5000
+    low = DEFAULT_BANDPASS[0]                 # 1.0
+
+    # Discovery-side detection:
+    isinstance(SAMPLING_RATE_HZ, Constant)    # True
+    SAMPLING_RATE_HZ.description              # "Default sampling rate ..."
+    SAMPLING_RATE_HZ.source_file              # "/path/to/module.py"
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+
+class Constant:
+    """
+    Transparent wrapper around a pipeline configuration value.
+
+    ``Constant`` instances forward arithmetic, comparison, container, and
+    attribute access to the underlying value so they can be used in place of
+    the raw value at call sites. The wrapper additionally carries a human
+    description and the source file/line where it was constructed, which the
+    scidb discovery scanner uses to populate the GUI sidebar.
+
+    Prefer the :func:`constant` factory over instantiating this class directly
+    — the factory captures the caller's source location automatically.
+    """
+
+    __slots__ = ("_value", "description", "source_file", "source_line")
+
+    def __init__(
+        self,
+        value: Any,
+        description: str = "",
+        source_file: str = "",
+        source_line: int = 0,
+    ) -> None:
+        # Bypass __setattr__ on __slots__ via object.__setattr__ to make the
+        # wrapper feel as immutable as possible from the outside.
+        object.__setattr__(self, "_value", value)
+        object.__setattr__(self, "description", description)
+        object.__setattr__(self, "source_file", source_file)
+        object.__setattr__(self, "source_line", source_line)
+
+    # ------------------------------------------------------------------
+    # Introspection / debugging
+    # ------------------------------------------------------------------
+    @property
+    def value(self) -> Any:
+        """Return the wrapped underlying value."""
+        return self._value
+
+    def __repr__(self) -> str:
+        return f"Constant({self._value!r}, description={self.description!r})"
+
+    # ------------------------------------------------------------------
+    # Attribute passthrough
+    # ------------------------------------------------------------------
+    def __getattr__(self, name: str) -> Any:
+        # __getattr__ is only called when normal lookup fails, so our own
+        # slots (description, source_file, ...) take precedence.
+        return getattr(self._value, name)
+
+    # ------------------------------------------------------------------
+    # Conversions
+    # ------------------------------------------------------------------
+    def __bool__(self) -> bool:
+        return bool(self._value)
+
+    def __int__(self) -> int:
+        return int(self._value)
+
+    def __float__(self) -> float:
+        return float(self._value)
+
+    def __complex__(self) -> complex:
+        return complex(self._value)
+
+    def __str__(self) -> str:
+        return str(self._value)
+
+    def __format__(self, format_spec: str) -> str:
+        return format(self._value, format_spec)
+
+    def __bytes__(self) -> bytes:
+        return bytes(self._value)
+
+    def __index__(self) -> int:
+        # Needed for things like ``range(SAMPLING_RATE_HZ)`` and slicing.
+        return self._value.__index__()
+
+    def __hash__(self) -> int:
+        return hash(self._value)
+
+    # ------------------------------------------------------------------
+    # Comparison
+    # ------------------------------------------------------------------
+    @staticmethod
+    def _unwrap(other: Any) -> Any:
+        return other._value if isinstance(other, Constant) else other
+
+    def __eq__(self, other: Any) -> bool:
+        return self._value == self._unwrap(other)
+
+    def __ne__(self, other: Any) -> bool:
+        return self._value != self._unwrap(other)
+
+    def __lt__(self, other: Any) -> bool:
+        return self._value < self._unwrap(other)
+
+    def __le__(self, other: Any) -> bool:
+        return self._value <= self._unwrap(other)
+
+    def __gt__(self, other: Any) -> bool:
+        return self._value > self._unwrap(other)
+
+    def __ge__(self, other: Any) -> bool:
+        return self._value >= self._unwrap(other)
+
+    # ------------------------------------------------------------------
+    # Arithmetic (left-hand)
+    # ------------------------------------------------------------------
+    def __add__(self, other: Any) -> Any:
+        return self._value + self._unwrap(other)
+
+    def __sub__(self, other: Any) -> Any:
+        return self._value - self._unwrap(other)
+
+    def __mul__(self, other: Any) -> Any:
+        return self._value * self._unwrap(other)
+
+    def __truediv__(self, other: Any) -> Any:
+        return self._value / self._unwrap(other)
+
+    def __floordiv__(self, other: Any) -> Any:
+        return self._value // self._unwrap(other)
+
+    def __mod__(self, other: Any) -> Any:
+        return self._value % self._unwrap(other)
+
+    def __pow__(self, other: Any, mod: Any = None) -> Any:
+        if mod is None:
+            return self._value ** self._unwrap(other)
+        return pow(self._value, self._unwrap(other), mod)
+
+    def __matmul__(self, other: Any) -> Any:
+        return self._value @ self._unwrap(other)
+
+    def __lshift__(self, other: Any) -> Any:
+        return self._value << self._unwrap(other)
+
+    def __rshift__(self, other: Any) -> Any:
+        return self._value >> self._unwrap(other)
+
+    def __and__(self, other: Any) -> Any:
+        return self._value & self._unwrap(other)
+
+    def __xor__(self, other: Any) -> Any:
+        return self._value ^ self._unwrap(other)
+
+    def __or__(self, other: Any) -> Any:
+        return self._value | self._unwrap(other)
+
+    # ------------------------------------------------------------------
+    # Arithmetic (right-hand)
+    # ------------------------------------------------------------------
+    def __radd__(self, other: Any) -> Any:
+        return self._unwrap(other) + self._value
+
+    def __rsub__(self, other: Any) -> Any:
+        return self._unwrap(other) - self._value
+
+    def __rmul__(self, other: Any) -> Any:
+        return self._unwrap(other) * self._value
+
+    def __rtruediv__(self, other: Any) -> Any:
+        return self._unwrap(other) / self._value
+
+    def __rfloordiv__(self, other: Any) -> Any:
+        return self._unwrap(other) // self._value
+
+    def __rmod__(self, other: Any) -> Any:
+        return self._unwrap(other) % self._value
+
+    def __rpow__(self, other: Any) -> Any:
+        return self._unwrap(other) ** self._value
+
+    def __rmatmul__(self, other: Any) -> Any:
+        return self._unwrap(other) @ self._value
+
+    def __rlshift__(self, other: Any) -> Any:
+        return self._unwrap(other) << self._value
+
+    def __rrshift__(self, other: Any) -> Any:
+        return self._unwrap(other) >> self._value
+
+    def __rand__(self, other: Any) -> Any:
+        return self._unwrap(other) & self._value
+
+    def __rxor__(self, other: Any) -> Any:
+        return self._unwrap(other) ^ self._value
+
+    def __ror__(self, other: Any) -> Any:
+        return self._unwrap(other) | self._value
+
+    # ------------------------------------------------------------------
+    # Unary
+    # ------------------------------------------------------------------
+    def __neg__(self) -> Any:
+        return -self._value
+
+    def __pos__(self) -> Any:
+        return +self._value
+
+    def __abs__(self) -> Any:
+        return abs(self._value)
+
+    def __invert__(self) -> Any:
+        return ~self._value
+
+    def __round__(self, ndigits: int | None = None) -> Any:
+        if ndigits is None:
+            return round(self._value)
+        return round(self._value, ndigits)
+
+    # ------------------------------------------------------------------
+    # Container / iteration
+    # ------------------------------------------------------------------
+    def __len__(self) -> int:
+        return len(self._value)
+
+    def __iter__(self):
+        return iter(self._value)
+
+    def __contains__(self, item: Any) -> bool:
+        return self._unwrap(item) in self._value
+
+    def __getitem__(self, key: Any) -> Any:
+        return self._value[self._unwrap(key)]
+
+    def __reversed__(self):
+        return reversed(self._value)
+
+
+def constant(value: Any, description: str = "") -> Constant:
+    """
+    Wrap ``value`` in a :class:`Constant`, capturing the caller's source
+    location so the GUI sidebar can link back to the definition.
+
+    Args:
+        value: The underlying value (scalar, tuple, list, dict, etc.).
+        description: Human-readable description of what the constant is for.
+
+    Returns:
+        A :class:`Constant` instance that behaves transparently as ``value``
+        for arithmetic, comparison, container, and attribute access.
+    """
+    # inspect.stack()[0] is this frame; [1] is the caller.
+    caller = inspect.stack()[1]
+    try:
+        source_file = caller.filename
+        source_line = caller.lineno
+    finally:
+        # Break the frame reference cycle that ``inspect.stack`` creates.
+        del caller
+    return Constant(
+        value,
+        description=description,
+        source_file=source_file,
+        source_line=source_line,
+    )