scinterop 0.1.0__py3-none-any.whl

scinterop/__init__.py

@@ -0,0 +1,204 @@
+"""scinterop — Single-cell format conversion toolkit.
+
+Convert between H5AD (AnnData), RDS (Seurat), and 10X MTX formats
+while preserving expression data, metadata, dimensional reductions,
+and layer information.
+"""
+
+import logging
+from typing import Any
+
+from . import errors
+from . import cache
+from . import h5ad
+from . import mtx
+from . import rds
+from . import r_runner
+from . import python_runner
+from . import provenance
+from .schema import CanonicalObject
+from .detect import detect, Detection
+from .validate import validate, assert_valid, ValidationResult
+
+__version__ = "0.1.0"
+
+
+def read(path: str, **kwargs: Any) -> CanonicalObject:
+    """Read a single-cell data file into a CanonicalObject.
+
+    Automatically detects format and dispatches to the appropriate
+    reader (H5AD, RDS, or MTX).
+
+    Args:
+        path: Path to a single-cell data file.
+        **kwargs: Forwarded to the format-specific reader.
+
+    Returns:
+        A :class:`CanonicalObject`.
+
+    Raises:
+        DetectionError: If the format is not recognised.
+    """
+    detected = detect(path)
+    fmt = detected.fmt
+    logger = _get_logger()
+
+    logger.info("Detected format '%s' for path '%s'", fmt, path)
+
+    if fmt == "h5ad":
+        return h5ad.read_h5ad(path, **kwargs)
+    elif fmt == "mtx":
+        return mtx.read_mtx(path, **kwargs)
+    elif fmt == "rds":
+        return rds.read_rds(path, **kwargs)
+    else:
+        raise errors.DetectionError(
+            f"Unsupported format '{fmt}' for path: {path}"
+        )
+
+
+def convert(
+    input_path: str,
+    output_path: str,
+    *,
+    r_exe: str = None,
+    python_exe: str = None,
+    seurat: bool = False,
+    **kwargs: Any,
+) -> str:
+    """Convert between single-cell data formats.
+
+    Reads the input, writes the output, and logs a provenance record.
+
+    Args:
+        input_path: Source file path.
+        output_path: Destination file or directory path.
+        r_exe: Path to Rscript executable.
+        python_exe: Path to Python executable.
+        seurat: When writing RDS, create a Seurat object.
+        **kwargs: Forwarded to the format-specific writer.
+
+    Returns:
+        The output path string.
+
+    Raises:
+        FormatAdapterError: If the output format is not recognised or
+            conversion fails.
+    """
+    import time
+    from pathlib import Path
+
+    logger = _get_logger()
+    t0 = time.time()
+
+    obj = read(input_path, **kwargs)
+
+    out = Path(output_path)
+    suffix = _resolve_suffix(out)
+
+    logger.info("Converting to format '%s' at '%s'", suffix, output_path)
+
+    if suffix == "h5ad":
+        h5ad.write_h5ad(obj, output_path, **kwargs)
+    elif suffix == "mtx":
+        mtx.write_mtx(obj, output_path, **kwargs)
+    elif suffix == "rds":
+        rds.write_rds(obj, output_path, seurat=seurat, r_exe=r_exe, **kwargs)
+    else:
+        raise errors.FormatAdapterError(
+            f"Unsupported output format for extension '{suffix}': {output_path}"
+        )
+
+    elapsed = time.time() - t0
+    logger.info("Conversion completed in %.2f seconds", elapsed)
+
+    provenance.write_conversion_record(
+        input_path=str(input_path),
+        input_format=detect(input_path).fmt,
+        output_path=str(output_path),
+        output_format=suffix,
+        success=True,
+        runtime_s=elapsed,
+    )
+
+    return str(output_path)
+
+
+def _resolve_suffix(path):
+    ext = path.suffix.lower()
+    if ext == ".h5ad":
+        return "h5ad"
+    elif ext == ".rds":
+        return "rds"
+    elif ext == ".gz":
+        stem = path.with_suffix("").suffix.lower()
+        if stem == ".mtx":
+            return "mtx"
+    elif ext == ".mtx":
+        return "mtx"
+    if not path.suffix or path.is_dir() or not path.exists():
+        return "mtx"
+    raise errors.FormatAdapterError(
+        f"Cannot determine output format from path: {path}"
+    )
+
+
+def run_r(script, r_exe=None, **kwargs: Any):
+    """Run an R script via the R runner.
+
+    Shortcut for :func:`r_runner.run_r`.
+
+    Args:
+        script: Path to a ``.R`` file or inline R code.
+        r_exe: Path to Rscript executable.
+        **kwargs: Forwarded to :func:`r_runner.run_r`.
+
+    Returns:
+        An :class:`r_runner.RExecResult`.
+    """
+    return r_runner.run_r(script, r_exe=r_exe, **kwargs)
+
+
+def run_python(script, python_exe=None, conda_env=None, **kwargs: Any):
+    """Run a Python script via the Python runner.
+
+    Shortcut for :func:`python_runner.run_python`.
+
+    Args:
+        script: Path to a ``.py`` file or inline Python code.
+        python_exe: Path to Python executable.
+        conda_env: Conda environment name.
+        **kwargs: Forwarded to :func:`python_runner.run_python`.
+
+    Returns:
+        A :class:`python_runner.PythonExecResult`.
+    """
+    return python_runner.run_python(
+        script, python_exe=python_exe, conda_env=conda_env, **kwargs
+    )
+
+
+def _get_logger():
+    return logging.getLogger("scinterop")
+
+
+__all__ = [
+    "CanonicalObject",
+    "Detection",
+    "ValidationResult",
+    "read",
+    "convert",
+    "detect",
+    "validate",
+    "assert_valid",
+    "run_r",
+    "run_python",
+    "errors",
+    "cache",
+    "h5ad",
+    "mtx",
+    "rds",
+    "r_runner",
+    "python_runner",
+    "provenance",
+]

scinterop/cache.py

@@ -0,0 +1,139 @@
+"""Scratch-directory management for intermediate files.
+
+The :class:`ScratchManager` creates, caches, and cleans up temporary
+directories shared across conversion steps.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import uuid
+from pathlib import Path
+from dataclasses import dataclass
+
+from .errors import CacheError
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ScratchContext:
+    """A single scratch directory handle.
+
+    Attributes:
+        root: The filesystem path of this scratch directory.
+        prefix: Human-readable prefix used in the directory name.
+        uid: Unique identifier for this context.
+    """
+
+    root: Path
+    prefix: str
+    uid: str
+
+    @property
+    def path(self) -> Path:
+        """Return the root path of this scratch directory."""
+        return self.root
+
+
+class ScratchManager:
+    """Manage temporary scratch directories for conversion artifacts.
+
+    Args:
+        base: Root directory for scratch dirs. Falls back to
+            ``SCINTEROP_SCRATCH`` env var or ``/tmp/scinterop_<user>``.
+    """
+
+    def __init__(self, base: str | Path | None = None):
+        if base is None:
+            base = os.environ.get(
+                "SCINTEROP_SCRATCH",
+                Path("/tmp") / f"scinterop_{os.environ.get('USER', 'unknown')}",
+            )
+        self._base = Path(base)
+        self._contexts: list[ScratchContext] = []
+        self._keep = os.environ.get("SCINTEROP_DEBUG", "").lower() in ("1", "true", "yes")
+
+    def tempdir(self, prefix: str = "scint") -> ScratchContext:
+        """Create a new scratch subdirectory.
+
+        Args:
+            prefix: Name prefix for the directory.
+
+        Returns:
+            A :class:`ScratchContext` pointing to the new directory.
+
+        Raises:
+            CacheError: If the directory cannot be created.
+        """
+        uid = uuid.uuid4().hex[:12]
+        path = self._base / f"{prefix}_{uid}"
+        try:
+            path.mkdir(parents=True, exist_ok=False)
+        except FileExistsError:
+            uid = uuid.uuid4().hex[:12]
+            path = self._base / f"{prefix}_{uid}"
+            path.mkdir(parents=True, exist_ok=False)
+        except OSError as e:
+            raise CacheError(f"Failed to create scratch dir '{path}': {e}") from e
+
+        ctx = ScratchContext(root=path, prefix=prefix, uid=uid)
+        self._contexts.append(ctx)
+        logger.info("Created scratch directory: %s", path)
+        return ctx
+
+    def cleanup(self, ctx: ScratchContext, *, keep: bool | None = None) -> None:
+        """Remove a specific scratch directory.
+
+        Args:
+            ctx: The context to clean up.
+            keep: Override the debug keep setting. If None, uses
+                the instance-level ``_keep``.
+        """
+        if keep is None:
+            keep = self._keep
+        if keep:
+            logger.info("Keeping scratch directory (debug mode): %s", ctx.path)
+            return
+        if ctx.path.exists():
+            try:
+                shutil.rmtree(ctx.path)
+                logger.info("Removed scratch directory: %s", ctx.path)
+            except OSError as e:
+                logger.warning("Failed to remove scratch directory '%s': %s", ctx.path, e)
+
+    def cleanup_all(self, *, keep: bool | None = None) -> None:
+        """Remove all tracked scratch directories.
+
+        Args:
+            keep: Override the debug keep setting for all contexts.
+        """
+        for ctx in list(self._contexts):
+            self.cleanup(ctx, keep=keep)
+        self._contexts.clear()
+
+    def write_script(self, ctx: ScratchContext, content: str, name: str = "script") -> Path:
+        """Write a script file into a scratch directory.
+
+        Args:
+            ctx: Scratch context to write into.
+            content: Script text content.
+            name: Basename (without extension) for the script file.
+
+        Returns:
+            Path to the written script file.
+
+        Raises:
+            CacheError: If the file cannot be written.
+        """
+        path = ctx.path / f"{name}.R"
+        try:
+            path.write_text(content)
+            logger.debug("Wrote script to %s", path)
+            return path
+        except OSError as e:
+            raise CacheError(
+                f"Failed to write script '{path}': {e}"
+            ) from e

scinterop/cli.py

@@ -0,0 +1,186 @@
+"""Command-line interface for scinterop.
+
+Usage::
+
+    scinterop detect <path>
+    scinterop convert <input> <output> [options]
+    scinterop run <script> --executor {r,python} [options]
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from . import __version__, read, convert, run_r, run_python, detect, errors
+
+logger = logging.getLogger("scinterop.cli")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser for the CLI.
+
+    Subcommands:
+
+    - ``detect`` — Detect the format of a single-cell data file.
+    - ``convert`` — Convert between single-cell formats.
+    - ``run`` — Execute an external R or Python script.
+
+    Returns:
+        A configured ``ArgumentParser``.
+    """
+    parser = argparse.ArgumentParser(
+        prog="scinterop",
+        description="Single-cell data interoperability tool",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"scinterop {__version__}"
+    )
+    parser.add_argument(
+        "--verbose", "-v", action="store_true", help="Enable debug logging"
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # detect
+    detect_parser = subparsers.add_parser(
+        "detect", help="Detect the format of a file or directory"
+    )
+    detect_parser.add_argument("path", type=str, help="Path to file or directory")
+
+    # convert
+    convert_parser = subparsers.add_parser(
+        "convert", help="Convert between single-cell formats"
+    )
+    convert_parser.add_argument("input", type=str, help="Input file or directory")
+    convert_parser.add_argument("output", type=str, help="Output file or directory")
+    convert_parser.add_argument(
+        "--r-exe", type=str, default=None,
+        help="Path to Rscript executable (default: SCINTEROP_R_EXE env or 'Rscript')",
+    )
+    convert_parser.add_argument(
+        "--python-exe", type=str, default=None,
+        help="Path to Python executable (default: SCINTEROP_PYTHON_EXE env or 'python')",
+    )
+    convert_parser.add_argument(
+        "--seurat", action="store_true",
+        help="When converting to RDS, create a Seurat object instead of a plain R list",
+    )
+    convert_parser.add_argument(
+        "--debug", action="store_true",
+        help="Keep temporary files for debugging",
+    )
+
+    # run
+    run_parser = subparsers.add_parser(
+        "run", help="Run an external R or Python script"
+    )
+    run_parser.add_argument("script", type=str, help="Path to script file")
+    run_parser.add_argument(
+        "--executor", "-e", type=str, required=True,
+        choices=["r", "python"],
+        help="Script language/executor",
+    )
+    run_parser.add_argument(
+        "--exe", type=str, default=None,
+        help="Path to Rscript or Python executable",
+    )
+    run_parser.add_argument(
+        "--conda-env", type=str, default=None,
+        help="Conda environment name (Python only)",
+    )
+    run_parser.add_argument(
+        "--args", type=str, nargs=argparse.REMAINDER,
+        help="Additional arguments passed to the script",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point.
+
+    Args:
+        argv: Command-line arguments (defaults to ``sys.argv[1:]``).
+
+    Returns:
+        Exit code (0 for success, 1 for errors).
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    log_level = logging.DEBUG if args.verbose else logging.INFO
+    logging.basicConfig(
+        level=log_level,
+        format="%(levelname)s | %(name)s | %(message)s",
+        stream=sys.stderr,
+    )
+
+    try:
+        if args.command == "detect":
+            _cmd_detect(args)
+        elif args.command == "convert":
+            _cmd_convert(args)
+        elif args.command == "run":
+            _cmd_run(args)
+        else:
+            parser.print_help()
+            return 1
+    except errors.ScinteropError as e:
+        logger.error(str(e))
+        return 1
+    except Exception as e:
+        logger.exception("Unexpected error: %s", e)
+        return 1
+
+    return 0
+
+
+def _cmd_detect(args) -> None:
+    result = detect(args.path)
+    print(f"Format:      {result.fmt}")
+    print(f"Path:        {result.path}")
+    if result.details:
+        print("Details:")
+        for key, val in result.details.items():
+            print(f"  {key}: {val}")
+
+
+def _cmd_convert(args) -> None:
+    if args.debug:
+        import os as _os
+        _os.environ["SCINTEROP_DEBUG"] = "1"
+
+    result_path = convert(
+        args.input,
+        args.output,
+        r_exe=args.r_exe,
+        python_exe=args.python_exe,
+        seurat=args.seurat,
+    )
+    print(f"Output: {result_path}", file=sys.stderr)
+
+
+def _cmd_run(args) -> None:
+    script = Path(args.script)
+    if not script.exists():
+        logger.error("Script not found: %s", script)
+        sys.exit(1)
+
+    if args.executor == "r":
+        result = run_r(script, r_exe=args.exe)
+    elif args.executor == "python":
+        result = run_python(
+            script, python_exe=args.exe, conda_env=args.conda_env,
+        )
+
+    if result.stdout:
+        sys.stdout.write(result.stdout)
+    if result.stderr:
+        sys.stderr.write(result.stderr)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scinterop/detect.py

@@ -0,0 +1,147 @@
+"""Auto-detect single-cell data formats from file paths.
+
+The :func:`detect` function identifies format by file extension or
+directory contents without reading the full data. Supports H5AD, RDS,
+and 10X MTX formats.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .errors import DetectionError
+
+logger = logging.getLogger(__name__)
+
+EXTENSION_MAP: dict[str, str] = {
+    ".h5ad": "h5ad",
+    ".rds": "rds",
+    ".mtx": "mtx",
+}
+
+COMPRESSED_EXTENSIONS: dict[str, str] = {
+    ".mtx.gz": "mtx",
+}
+
+MTX_TRIO = {"matrix.mtx", "matrix.mtx.gz", "barcodes.tsv", "barcodes.tsv.gz",
+            "features.tsv", "features.tsv.gz"}
+
+
+@dataclass
+class Detection:
+    """Result of a format detection call.
+
+    Attributes:
+        fmt: Short format string — ``"h5ad"``, ``"rds"``, or ``"mtx"``.
+        path: The resolved path that was detected.
+        details: Extra information (e.g. extension matched, trio files found).
+    """
+
+    fmt: str
+    path: Path
+    details: dict[str, Any]
+
+
+def detect(path: str | Path) -> Detection:
+    """Detect the format of a single-cell data file or directory.
+
+    Resolution order:
+    1. If path is a **directory**, look for 10X MTX trio files.
+    2. If path is an **existing file**, detect by extension.
+    3. If path **does not exist** but has a recognised extension,
+       infer from extension alone.
+    4. Otherwise raise :class:`DetectionError`.
+
+    Args:
+        path: File path or directory to inspect.
+
+    Returns:
+        A :class:`Detection` with the format, resolved path, and details.
+
+    Raises:
+        DetectionError: If the format cannot be determined.
+    """
+    p = Path(path)
+
+    details: dict[str, Any] = {}
+
+    if p.is_dir():
+        return _detect_directory(p, details)
+
+    if p.exists():
+        return _detect_file(p, details)
+
+    if p.suffix:
+        result = _detect_by_extension(p, details)
+        if result is not None:
+            return result
+
+    raise DetectionError(
+        f"Cannot determine format from path: {p}. "
+        f"Supported extensions: {', '.join(EXTENSION_MAP)}"
+    )
+
+
+def _detect_directory(p: Path, details: dict) -> Detection:
+    files = {f.name for f in p.iterdir() if f.is_file()}
+    present = MTX_TRIO & files
+    n_present = len(present)
+    if n_present >= 2:
+        details["mtx_trio_found"] = sorted(present)
+        details["n_cells_file"] = "barcodes.tsv" in files or "barcodes.tsv.gz" in files
+        details["n_genes_file"] = "features.tsv" in files or "features.tsv.gz" in files
+        logger.info("Detected 10X MTX format in directory '%s'", p)
+        return Detection(fmt="mtx", path=p, details=details)
+
+    raise DetectionError(
+        f"Unrecognized directory format at '{p}'. "
+        f"Expected a 10X directory with matrix.mtx, barcodes.tsv, features.tsv. "
+        f"Found files: {sorted(files)[:20]}"
+    )
+
+
+def _detect_file(p: Path, details: dict) -> Detection:
+    result = _detect_by_extension(p, details)
+    if result is not None:
+        return result
+
+    raise DetectionError(
+        f"Unrecognized file format at '{p}'. "
+        f"Supported: {', '.join(EXTENSION_MAP)}, {', '.join(COMPRESSED_EXTENSIONS)}."
+    )
+
+
+def _detect_by_extension(p: Path, details: dict) -> Detection | None:
+    name_lower = p.name.lower()
+
+    for ext, fmt in COMPRESSED_EXTENSIONS.items():
+        if name_lower.endswith(ext):
+            details["extension"] = ext
+            logger.info("Detected format '%s' from extension '%s'", fmt, ext)
+            return Detection(fmt=fmt, path=p, details=details)
+
+    for ext, fmt in EXTENSION_MAP.items():
+        if name_lower.endswith(ext):
+            details["extension"] = ext
+            logger.info("Detected format '%s' from extension '%s'", fmt, ext)
+            return Detection(fmt=fmt, path=p, details=details)
+
+    return None
+
+
+def _peek_h5(p: Path) -> str | None:
+    try:
+        import h5py
+        with h5py.File(p, "r") as f:
+            keys = set(f.keys())
+            if "X" in keys:
+                if "obs" in keys and "var" in keys:
+                    return "anndata"
+            if "assays" in keys:
+                return "seurat_h5"
+            return f"keys: {sorted(keys)[:10]}"
+    except Exception:
+        return None