scifor 0.1.0__tar.gz

scifor-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv
+.DS_Store
+*/*/__pycache__
+others_projects/sciforge
+scistack-gui/extension/node_modules/
+scistack-gui/frontend/node_modules/__pycache__/ 
+*.pyc 
+__pycache__/ 
+*.pyc 
+*.pyo 

scifor-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: scifor
+Version: 0.1.0
+Summary: Standalone for_each batch execution utilities for data pipelines
+Author: SciStack Contributors
+License-Expression: MIT
+Keywords: automation,batch,data-science,execution,pipeline
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: numpy; extra == 'dev'
+Requires-Dist: pandas; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# scifor
+
+## Stop Writing Loops, Start Writing Analysis
+
+`scifor` is the batch execution engine behind SciDB. It takes a function you've already written and runs it across every combination of experimental conditions — subjects, sessions, trials, whatever your data is organized by — automatically slicing your data to match each combination and collecting the results into a clean table.
+
+It works in both **Python** and **MATLAB**, and it works standalone — no database required, just plain tables.
+
+## The Problem
+
+Scientific data is almost always organized by conditions: subjects, sessions, trials, limbs, speeds. Processing it means writing nested loops that slice, call a function, and collect results:
+
+```matlab
+for i = 1:numel(subjects)
+    for j = 1:numel(sessions)
+        rows = tbl(tbl.subject == subjects(i) & tbl.session == sessions(j), :);
+        result = my_analysis(rows.emg);
+        % ...now figure out where to put the result
+    end
+end
+```
+
+This gets worse as the number of conditions grows, and the loop logic buries the actual analysis. Every scientist writes some version of this, and it's never the interesting part.
+
+## How scifor Works
+
+You tell scifor two things:
+
+1. **Schema** — which columns in your tables represent experimental conditions (the things you iterate over)
+2. **Inputs** — which tables to slice, and which values are just constants
+
+Then scifor handles the rest: it loops over every combination, filters each table to the matching rows, calls your function, and collects the results.
+
+**MATLAB**
+
+```matlab
+scifor.set_schema(["subject", "session"]);
+
+results = scifor.for_each(@my_analysis, ...
+    struct('emg', data_table, 'cutoff_hz', 20), ...
+    subject=[1, 2, 3], session=["pre", "post"]);
+```
+
+**Python**
+
+```python
+from scifor import set_schema, for_each
+
+set_schema(["subject", "session"])
+
+results = for_each(
+    my_analysis,
+    inputs={"emg": data_table, "cutoff_hz": 20},
+    subject=[1, 2, 3],
+    session=["pre", "post"],
+)
+```
+
+For each of the 6 combinations (3 subjects x 2 sessions), scifor filters `data_table` to the matching rows, passes the `emg` column to `my_analysis` along with the constant `cutoff_hz=20`, and collects the return value. The result is a table with `subject`, `session`, and `output` columns — one row per combination.
+
+Your function doesn't need to know about looping, filtering, or metadata. It just receives data and returns a result.
+
+## What You Get Back
+
+`for_each` returns a MATLAB table (or pandas DataFrame in Python) with one row per combination. Metadata columns come first, then the output:
+
+| subject | session | output |
+|---------|---------|--------|
+| 1       | pre     | 0.82   |
+| 1       | post    | 1.47   |
+| 2       | pre     | 0.91   |
+| 2       | post    | 1.38   |
+| 3       | pre     | 0.76   |
+| 3       | post    | 1.22   |
+
+If your function returns a table, its columns are flattened into the result alongside the metadata. If your function returns multiple outputs, you get multiple result tables.
+
+## Beyond the Basics
+
+The examples above cover the most common case, but real pipelines have real-world complications. scifor has tools for each of them:
+
+- **Fixed inputs** — Pin one input to a specific condition while the others iterate. The classic case: comparing every session against a fixed baseline.
+
+- **Merging tables** — When your function needs columns from two separate tables (say, kinematics and force data), combine them into a single input per combination.
+
+- **Column selection** — Extract just the columns you need from a multi-column table before your function sees it.
+
+- **File paths from metadata** — When your data lives in files organized by condition (e.g., `data/subject_1/trial_3.mat`), generate the right file path for each combination automatically.
+
+- **Row filtering** — Apply column-based filters (like "only right-side trials" or "speed > 1.5") on top of the metadata filtering.
+
+- **Dry run** — Preview which combinations would be processed and what data would be passed, without actually running anything.
+
+- **Distribute** — When a function returns a vector of values that should each become their own row at a deeper schema level (e.g., splitting a trial into individual gait cycles), scifor can expand the output automatically.
+
+See the [API reference](../docs/api/for-each.md) and [batch processing guide](../docs/guide/for_each.md) for details on all of these.
+
+## Relationship to SciDB
+
+scifor is the engine that powers `scidb.for_each()`. When used through SciDB, inputs are loaded from the database and outputs are saved back automatically. When used standalone (as `scifor.for_each()`), it works with plain MATLAB tables or pandas DataFrames — no database needed.
+
+If you're already using SciDB, you're already using scifor under the hood. If you just want the loop orchestration without the database, use the `scifor` namespace directly.

scifor-0.1.0/README.md

@@ -0,0 +1,102 @@
+# scifor
+
+## Stop Writing Loops, Start Writing Analysis
+
+`scifor` is the batch execution engine behind SciDB. It takes a function you've already written and runs it across every combination of experimental conditions — subjects, sessions, trials, whatever your data is organized by — automatically slicing your data to match each combination and collecting the results into a clean table.
+
+It works in both **Python** and **MATLAB**, and it works standalone — no database required, just plain tables.
+
+## The Problem
+
+Scientific data is almost always organized by conditions: subjects, sessions, trials, limbs, speeds. Processing it means writing nested loops that slice, call a function, and collect results:
+
+```matlab
+for i = 1:numel(subjects)
+    for j = 1:numel(sessions)
+        rows = tbl(tbl.subject == subjects(i) & tbl.session == sessions(j), :);
+        result = my_analysis(rows.emg);
+        % ...now figure out where to put the result
+    end
+end
+```
+
+This gets worse as the number of conditions grows, and the loop logic buries the actual analysis. Every scientist writes some version of this, and it's never the interesting part.
+
+## How scifor Works
+
+You tell scifor two things:
+
+1. **Schema** — which columns in your tables represent experimental conditions (the things you iterate over)
+2. **Inputs** — which tables to slice, and which values are just constants
+
+Then scifor handles the rest: it loops over every combination, filters each table to the matching rows, calls your function, and collects the results.
+
+**MATLAB**
+
+```matlab
+scifor.set_schema(["subject", "session"]);
+
+results = scifor.for_each(@my_analysis, ...
+    struct('emg', data_table, 'cutoff_hz', 20), ...
+    subject=[1, 2, 3], session=["pre", "post"]);
+```
+
+**Python**
+
+```python
+from scifor import set_schema, for_each
+
+set_schema(["subject", "session"])
+
+results = for_each(
+    my_analysis,
+    inputs={"emg": data_table, "cutoff_hz": 20},
+    subject=[1, 2, 3],
+    session=["pre", "post"],
+)
+```
+
+For each of the 6 combinations (3 subjects x 2 sessions), scifor filters `data_table` to the matching rows, passes the `emg` column to `my_analysis` along with the constant `cutoff_hz=20`, and collects the return value. The result is a table with `subject`, `session`, and `output` columns — one row per combination.
+
+Your function doesn't need to know about looping, filtering, or metadata. It just receives data and returns a result.
+
+## What You Get Back
+
+`for_each` returns a MATLAB table (or pandas DataFrame in Python) with one row per combination. Metadata columns come first, then the output:
+
+| subject | session | output |
+|---------|---------|--------|
+| 1       | pre     | 0.82   |
+| 1       | post    | 1.47   |
+| 2       | pre     | 0.91   |
+| 2       | post    | 1.38   |
+| 3       | pre     | 0.76   |
+| 3       | post    | 1.22   |
+
+If your function returns a table, its columns are flattened into the result alongside the metadata. If your function returns multiple outputs, you get multiple result tables.
+
+## Beyond the Basics
+
+The examples above cover the most common case, but real pipelines have real-world complications. scifor has tools for each of them:
+
+- **Fixed inputs** — Pin one input to a specific condition while the others iterate. The classic case: comparing every session against a fixed baseline.
+
+- **Merging tables** — When your function needs columns from two separate tables (say, kinematics and force data), combine them into a single input per combination.
+
+- **Column selection** — Extract just the columns you need from a multi-column table before your function sees it.
+
+- **File paths from metadata** — When your data lives in files organized by condition (e.g., `data/subject_1/trial_3.mat`), generate the right file path for each combination automatically.
+
+- **Row filtering** — Apply column-based filters (like "only right-side trials" or "speed > 1.5") on top of the metadata filtering.
+
+- **Dry run** — Preview which combinations would be processed and what data would be passed, without actually running anything.
+
+- **Distribute** — When a function returns a vector of values that should each become their own row at a deeper schema level (e.g., splitting a trial into individual gait cycles), scifor can expand the output automatically.
+
+See the [API reference](../docs/api/for-each.md) and [batch processing guide](../docs/guide/for_each.md) for details on all of these.
+
+## Relationship to SciDB
+
+scifor is the engine that powers `scidb.for_each()`. When used through SciDB, inputs are loaded from the database and outputs are saved back automatically. When used standalone (as `scifor.for_each()`), it works with plain MATLAB tables or pandas DataFrames — no database needed.
+
+If you're already using SciDB, you're already using scifor under the hood. If you just want the loop orchestration without the database, use the `scifor` namespace directly.

scifor-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "scifor"
+version = "0.1.0"
+description = "Standalone for_each batch execution utilities for data pipelines"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "SciStack Contributors" }
+]
+keywords = [
+    "batch",
+    "pipeline",
+    "execution",
+    "data-science",
+    "automation",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "pandas",
+    "numpy",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/scifor"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

scifor-0.1.0/src/scifor/__init__.py

@@ -0,0 +1,56 @@
+"""scifor: Standalone for_each batch execution for data pipelines.
+
+Works with plain DataFrames. No database required.
+
+Example:
+    import pandas as pd
+    from scifor import set_schema, for_each, Col
+
+    set_schema(["subject", "session"])
+
+    raw_df = pd.DataFrame({
+        "subject": [1, 1, 2, 2],
+        "session": ["pre", "post", "pre", "post"],
+        "emg":     [0.1,  0.2,  0.3,  0.4],
+    })
+
+    result = for_each(
+        lambda signal: signal.mean(),
+        inputs={"signal": raw_df},
+        subject=[1, 2],
+        session=["pre", "post"],
+    )
+"""
+
+from .schema import set_schema, get_schema
+from .foreach import for_each, ColumnFunctionError, ForColumnsError
+from .fixed import Fixed
+from .merge import Merge
+from .column_selection import ColumnSelection
+from .colname import ColName
+from .pathinput import PathInput
+from .pathoutput import PathOutput
+from .filters import Col, ColFilter, CompoundFilter, NotFilter
+__version__ = "0.1.0"
+
+__all__ = [
+    # Schema
+    "set_schema",
+    "get_schema",
+    # Batch execution
+    "for_each",
+    "ColumnFunctionError",
+    "ForColumnsError",
+    # Input wrappers
+    "Fixed",
+    "Merge",
+    "ColumnSelection",
+    "ColName",
+    "PathInput",
+    "PathOutput",
+    # Filters
+    "Col",
+    "ColFilter",
+    "CompoundFilter",
+    "NotFilter",
+]

scifor-0.1.0/src/scifor/colname.py

@@ -0,0 +1,60 @@
+"""ColName wrapper — resolves to the single non-schema data column name of a DataFrame."""
+
+from typing import Any
+
+
+class ColName:
+    """
+    Marker that resolves to a data column name string at for_each time.
+
+    Two forms:
+
+    1. ``ColName(df)`` — *static*. Resolves once, up front, to the single
+       non-schema data column name of ``df``. Use when a function needs to know
+       the name of the one data column in a DataFrame but should stay
+       framework-agnostic. Raises ValueError if ``df`` has 0 or 2+ non-schema
+       data columns.
+
+    2. ``ColName()`` — *deferred*. Resolves per-column inside a ``for_columns``
+       iteration to the name of the column currently being fed to the function.
+       Requires at least one iterate input (``for_columns`` /
+       ``ColumnSelection(..., iterate=True)``); using it without one is an error.
+
+    As a convenience, passing the bare class ``ColName`` (no parentheses) is
+    accepted and treated as the deferred ``ColName()`` form — the only form it
+    can mean, since there is no DataFrame to attach.
+
+    Example (static):
+        set_schema(["subject", "session"])
+        result = for_each(
+            analyze,
+            inputs={"table": raw_df, "col_name": ColName(raw_df)},
+            subject=[1, 2],
+            session=["pre", "post"],
+        )
+
+        # The function is pure — no framework imports:
+        def analyze(table, col_name):
+            return table[col_name].mean()
+
+    Example (deferred, current for_columns column):
+        for_each(
+            analyze,
+            inputs={"df": means_df.for_columns(), "col_name": ColName()},
+            subject=[],
+        )
+    """
+
+    def __init__(self, data: Any = None):
+        """
+        Args:
+            data: A pandas DataFrame whose single data column name will be
+                resolved (static form). Omit it for the deferred form, which
+                resolves to the current ``for_columns`` column.
+        """
+        self.data = data
+
+    @property
+    def is_deferred(self) -> bool:
+        """True for the no-arg form (resolves to the current for_columns column)."""
+        return self.data is None

scifor-0.1.0/src/scifor/column_selection.py

@@ -0,0 +1,96 @@
+"""Column selection wrapper for DataFrame inputs in for_each."""
+
+from typing import Any
+
+
+class ColumnSelection:
+    """
+    Wraps a DataFrame with column selection for use in for_each() inputs.
+
+    After filtering the DataFrame for the current combo, extracts only the
+    specified columns. Single column -> returns numpy array of values.
+    Multiple columns -> returns a sub-DataFrame.
+
+    Example:
+        for_each(
+            fn,
+            inputs={"speed": ColumnSelection(data_df, ["speed"])},
+            subject=[1, 2, 3],
+        )
+
+    When ``iterate=True`` the selection means "run fn once per column" rather
+    than "pass these columns as one argument." The per-combo loop feeds each
+    column (as a single-column array) to fn in turn and reassembles the
+    per-column results into one wide row. All iterate selections in a single
+    for_each() call must share the same column set (zipped by name).
+
+    An **empty** ``columns`` (the default, e.g. ``ColumnSelection(df)``) means
+    "all data columns" — every column that is not a schema key — resolved at
+    for_each time from the DataFrame. This mirrors how an empty iteration list
+    (``subject=[]``) means "all values from the data". (``None`` is accepted as
+    an alias for the empty/all sentinel for backward compatibility.)
+
+    ``excl_columns`` drops named columns from whatever ``columns`` resolves to
+    (explicit list or the all-columns expansion). This is the natural companion
+    to the all-columns/iterate mode: take the non-numeric (or otherwise
+    unwanted) columns surfaced in a failure and exclude them, so they are
+    skipped during iteration and absent from the aggregated result.
+    """
+
+    def __init__(
+        self,
+        data: Any,
+        columns: "list[str] | None" = [],
+        iterate: bool = False,
+        excl_columns: "list[str] | None" = None,
+    ):
+        """
+        Args:
+            data: A pandas DataFrame.
+            columns: List of column names to extract after filtering. An empty
+                list ``[]`` (the default) means "all data columns", resolved at
+                for_each time. ``None`` is accepted as an alias for ``[]``.
+            iterate: If True, iterate over the columns (one fn call each) and
+                reassemble; if False (default), pass the column(s) as a single
+                argument.
+            excl_columns: Column names to remove from the resolved selection
+                (after the all-columns expansion). Useful for dropping the
+                non-data columns reported by a ``ColumnFunctionError`` without
+                having to enumerate every column you *do* want.
+        """
+        self.data = data
+        # 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
+        self.excl_columns = list(excl_columns) if excl_columns else []
+
+    @property
+    def __name__(self) -> str:
+        """Return a display name for format_inputs and error messages."""
+        data_name = _display_name(self.data)
+        suffix = ", iterate" if self.iterate else ""
+        if self.excl_columns:
+            excl = ", ".join(f'"{c}"' for c in self.excl_columns)
+            suffix = f"{suffix}, excl=[{excl}]"
+        if not self.columns:
+            return f'{data_name}[<all columns>{suffix}]'
+        if len(self.columns) == 1 and not self.iterate and not self.excl_columns:
+            return f'{data_name}["{self.columns[0]}"]'
+        cols = ", ".join(f'"{c}"' for c in self.columns)
+        return f'{data_name}[{cols}{suffix}]'
+
+    def __hash__(self):
+        return hash((id(self.data), tuple(self.columns), self.iterate,
+                     tuple(self.excl_columns)))
+
+
+def _display_name(obj: Any) -> str:
+    """Get a display name for an object."""
+    try:
+        import pandas as pd
+        if isinstance(obj, pd.DataFrame):
+            return f"DataFrame{list(obj.columns)}"
+    except ImportError:
+        pass
+    return getattr(obj, '__name__', type(obj).__name__)

scifor-0.1.0/src/scifor/csv_export.py

@@ -0,0 +1,172 @@
+"""Flat-table export for ``scifor.Merge``: inner-join constituents into one frame.
+
+``merge_to_dataframe`` builds the joined pandas DataFrame; ``export_merge_csv`` is
+a thin wrapper that writes it to a ``.csv``. Both back ``Merge.as_df`` and
+``Merge.to_csv`` respectively.
+
+Unlike the ``for_each`` merge path (``_prepare_merge``/``_merge_parts`` in
+``foreach.py``), which combo-filters each constituent then positionally
+concatenates after *dropping* the schema columns, this performs a real
+``pd.merge(how="inner")`` across the constituents and keeps a single copy of the
+shared schema columns. There is no per-combo iteration here — the whole
+constituent DataFrames are joined at once.
+
+Non-schema columns are assumed not to overlap between constituents (caller
+guarantee), so the columns common to any two constituents are exactly the shared
+schema columns, which become the join keys.
+"""
+
+from typing import Any
+
+
+def merge_to_dataframe(
+    merge: Any,
+    where=None,
+    _log_fn: "Any" = None,
+    **metadata: Any,
+) -> "Any":
+    """Inner-join a ``Merge``'s constituents and return the joined DataFrame.
+
+    Args:
+        merge: A ``scifor.Merge`` instance.
+        where: Optional scifor ColName/Col filter applied once to the joined
+            table (so it may reference columns from any constituent).
+        _log_fn: Optional ``Callable[[str], None]`` for diagnostics (NOTE 2).
+        **metadata: Row filters applied per constituent on any matching schema
+            column. A scalar matches by equality; a list/tuple/set matches by
+            membership. Keys absent from a given constituent are skipped.
+
+    Returns:
+        The inner-joined pandas DataFrame with one copy of the shared schema
+        columns plus every selected data column.
+    """
+    import pandas as pd
+
+    from .foreach import (
+        _resolve_data_spec,
+        _apply_where_filter,
+        _all_data_columns,
+        _apply_exclusions,
+        _excluded_columns,
+    )
+    from .schema import get_schema
+
+    def _log(msg: str) -> None:
+        if _log_fn is not None:
+            _log_fn(f"[scifor] {msg}")
+
+    schema_keys = get_schema()
+    _log(f"merge: schema keys = {schema_keys or '(unset)'}")
+
+    parts: list[tuple[str, "pd.DataFrame"]] = []
+    for i, spec in enumerate(merge.tables):
+        label = f"merge[{i}]"
+
+        df, effective_metadata, column_selection = _resolve_data_spec(spec, metadata)
+        excl = _excluded_columns(spec)
+
+        filtered = _filter_rows_by_metadata(df, effective_metadata)
+
+        if column_selection is not None:
+            # An empty selection means "all data columns".
+            cols = column_selection or _all_data_columns(filtered, schema_keys)
+            cols = _apply_exclusions(cols, excl)
+            missing = [c for c in cols if c not in filtered.columns]
+            if missing:
+                raise KeyError(
+                    f"Column(s) {missing} not found in {label}. "
+                    f"Available: {list(filtered.columns)}"
+                )
+        else:
+            cols = _all_data_columns(filtered, schema_keys)
+
+        # Keep schema columns present (needed as join keys) plus the selected
+        # data columns, preserving original column order.
+        schema_present = [c for c in filtered.columns if c in schema_keys]
+        data_cols = [c for c in cols if c not in schema_present]
+        keep = schema_present + data_cols
+        part_df = filtered[keep].reset_index(drop=True)
+
+        _log(
+            f"merge: {label} -> {part_df.shape[0]} row(s) x {part_df.shape[1]} "
+            f"col(s); schema={schema_present}, data={data_cols}"
+        )
+        parts.append((label, part_df))
+
+    # Fold an inner join across the constituents on their shared schema columns.
+    acc_label, acc = parts[0]
+    for label, part in parts[1:]:
+        join_keys = [c for c in acc.columns if c in part.columns]
+        if schema_keys:
+            join_keys = [c for c in join_keys if c in schema_keys]
+        if not join_keys:
+            raise ValueError(
+                f"Cannot inner-join {acc_label} and {label}: no shared schema "
+                f"column to join on. {acc_label} columns: {list(acc.columns)}; "
+                f"{label} columns: {list(part.columns)}. Schema keys: "
+                f"{schema_keys or '(unset — call set_schema())'}."
+            )
+        _log(f"merge: joining {label} into {acc_label} on {join_keys}")
+        acc = pd.merge(acc, part, on=join_keys, how="inner")
+        acc_label = f"{acc_label}+{label}"
+
+    # The where= predicate spans the merged row, so apply it once to the joined
+    # table (a constituent need not contain every column the filter references).
+    if where is not None:
+        before = len(acc)
+        acc = _apply_where_filter(acc, where)
+        _log(f"merge: where= filter kept {len(acc)}/{before} row(s)")
+
+    _log(f"merge: result {acc.shape[0]} row(s) x {acc.shape[1]} col(s)")
+    return acc
+
+
+def export_merge_csv(
+    merge: Any,
+    filename: str,
+    where=None,
+    _log_fn: "Any" = None,
+    **metadata: Any,
+) -> None:
+    """Inner-join a ``Merge``'s constituents and write the result to ``filename``.
+
+    Thin wrapper over ``merge_to_dataframe``; ``filename`` must end with ``.csv``.
+    """
+    if not isinstance(filename, str) or not filename.endswith(".csv"):
+        raise ValueError(
+            f"to_csv() filename must be a string ending with '.csv', got {filename!r}."
+        )
+
+    df = merge_to_dataframe(merge, where=where, _log_fn=_log_fn, **metadata)
+
+    if _log_fn is not None:
+        _log_fn(
+            f"[scifor] to_csv: writing {df.shape[0]} row(s) x {df.shape[1]} "
+            f"col(s) to {filename!r}"
+        )
+    df.to_csv(filename, index=False)
+
+
+def _filter_rows_by_metadata(
+    df: "Any", metadata: dict
+) -> "Any":
+    """Filter df rows by metadata for any matching column (scalar or list).
+
+    Mirrors ``_filter_df_for_combo`` but accepts list/tuple/set values (matched
+    by membership) in addition to scalars (matched by equality). Keys not
+    present as columns in ``df`` are skipped.
+    """
+    import pandas as pd
+
+    if len(df.columns) == 0:
+        return df.reset_index(drop=True)
+
+    mask = pd.Series([True] * len(df), index=df.index)
+    for key, val in metadata.items():
+        if key not in df.columns:
+            continue
+        if isinstance(val, (list, tuple, set)):
+            mask = mask & df[key].isin(list(val))
+        else:
+            mask = mask & (df[key] == val)
+    return df[mask].reset_index(drop=True)