epyraw 0.1.0__py3-none-any.whl

epyraw/__init__.py

@@ -0,0 +1,113 @@
+"""Epyraw - Python wrapper for Thermo Fisher RawFileReader library.
+
+This package provides a Pythonic interface to read Thermo Scientific .raw
+mass spectrometry files using the official RawFileReader .NET library.
+
+Example:
+    >>> from epyraw import RawFile, Device
+    >>> with RawFile("data.raw") as rf:
+    ...     rf.select_instrument(Device.MS, 1)
+    ...     print(f"Scans: {rf.run_header.spectra_count}")
+    ...     spectrum = rf.get_spectrum(100)
+    ...     print(f"Peaks: {spectrum.num_peaks}")
+"""
+
+from .download import check_runtimes_present, download_runtimes, get_default_runtime_path
+from .enums import (
+    BarcodeStatusType,
+    DetectorType,
+    Device,
+    IonizationMode,
+    MassAnalyzerType,
+    MSOrderType,
+    PolarityType,
+    SampleType,
+    ScanTypeEnum,
+    SpectrumPacketType,
+    ToleranceUnits,
+    TraceType,
+    TrayShape,
+)
+from .exceptions import (
+    AssemblyLoadError,
+    InitializationError,
+    InstrumentNotSelectedError,
+    InvalidScanNumberError,
+    RawFileCorruptedError,
+    RawFileNotFoundError,
+    RawFileOpenError,
+    ThermoRawFileError,
+)
+from .models import (
+    AutoSamplerInformation,
+    Chromatogram,
+    FileHeader,
+    InclusionListItem,
+    InstrumentData,
+    MassOptions,
+    Reaction,
+    RunHeader,
+    SampleInformation,
+    ScanDependentDetail,
+    ScanDependents,
+    ScanEvent,
+    ScanFilter,
+    ScanHeader,
+    ScanStats,
+    Spectrum,
+    StatusLogField,
+)
+from .raw_file import RawFile, set_runtime
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Main class
+    "RawFile",
+    "set_runtime",
+    # Download functions
+    "download_runtimes",
+    "check_runtimes_present",
+    "get_default_runtime_path",
+    # Enums
+    "Device",
+    "DetectorType",
+    "IonizationMode",
+    "MSOrderType",
+    "MassAnalyzerType",
+    "PolarityType",
+    "SampleType",
+    "ToleranceUnits",
+    "TraceType",
+    "SpectrumPacketType",
+    "ScanTypeEnum",
+    "TrayShape",
+    "BarcodeStatusType",
+    # Data models
+    "Chromatogram",
+    "FileHeader",
+    "InclusionListItem",
+    "InstrumentData",
+    "RunHeader",
+    "SampleInformation",
+    "ScanFilter",
+    "Spectrum",
+    "StatusLogField",
+    "ScanHeader",
+    "ScanEvent",
+    "Reaction",
+    "MassOptions",
+    "ScanStats",
+    "ScanDependents",
+    "ScanDependentDetail",
+    "AutoSamplerInformation",
+    # Exceptions
+    "AssemblyLoadError",
+    "InitializationError",
+    "InstrumentNotSelectedError",
+    "InvalidScanNumberError",
+    "RawFileCorruptedError",
+    "RawFileNotFoundError",
+    "RawFileOpenError",
+    "ThermoRawFileError",
+]

epyraw/cli.py

@@ -0,0 +1,71 @@
+"""CLI for epyraw package."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from .download import check_runtimes_present, download_runtimes, get_default_runtime_path
+
+
+def main() -> None:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="epyraw",
+        description="Thermo RawFileReader Python wrapper - manage runtime DLLs",
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Download command
+    download_parser = subparsers.add_parser(
+        "download", help="Download Thermo RawFileReader runtime DLLs"
+    )
+    download_parser.add_argument(
+        "--path",
+        "-p",
+        type=str,
+        help="Custom path for DLLs (default: ~/.epyraw/runtimes/net8old)",
+    )
+    download_parser.add_argument(
+        "--force",
+        "-f",
+        action="store_true",
+        help="Re-download even if files exist",
+    )
+
+    # Check command
+    check_parser = subparsers.add_parser("check", help="Check if runtime DLLs are installed")
+    check_parser.add_argument(
+        "--path",
+        "-p",
+        type=str,
+        help="Custom path to check (default: ~/.epyraw/runtimes/net8old)",
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "download":
+        target_path = Path(args.path) if args.path else None
+        print("Downloading Thermo RawFileReader runtime DLLs...")
+        try:
+            path = download_runtimes(target_path, force=args.force)
+            print(f"Successfully downloaded to: {path}")
+        except Exception as e:
+            print(f"Error: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    elif args.command == "check":
+        path = Path(args.path) if args.path else get_default_runtime_path()
+        if check_runtimes_present(path):
+            print(f"Runtime DLLs found at: {path}")
+            sys.exit(0)
+        else:
+            print(f"Runtime DLLs NOT found at: {path}")
+            print("Run 'epyraw download' to install them.")
+            sys.exit(1)
+    else:
+        parser.print_help()
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

epyraw/download.py

@@ -0,0 +1,158 @@
+"""Download Thermo RawFileReader runtime DLLs.
+
+This module provides functionality to download the required .NET assemblies
+from the Thermo Fisher RawFileReader GitHub repository.
+"""
+
+from pathlib import Path
+
+try:
+    import requests
+except ImportError:
+    requests = None  # type: ignore
+
+
+# GitHub raw content URLs for the DLLs
+RAW_FILE_READER_URLS = {
+    "base_url": "https://raw.githubusercontent.com/thermofisherlsms/RawFileReader/main/Libs/NetCore/Net8Old/Assemblies/",
+    "files": [
+        "OpenMcdf.dll",
+        "OpenMcdf.Extensions.dll",
+        "ThermoFisher.CommonCore.BackgroundSubtraction.dll",
+        "ThermoFisher.CommonCore.BackgroundSubtraction.xml",
+        "ThermoFisher.CommonCore.Data.dll",
+        "ThermoFisher.CommonCore.Data.xml",
+        "ThermoFisher.CommonCore.MassPrecisionEstimator.dll",
+        "ThermoFisher.CommonCore.MassPrecisionEstimator.xml",
+        "ThermoFisher.CommonCore.RawFileReader.dll",
+        "ThermoFisher.CommonCore.RawFileReader.xml",
+    ],
+}
+
+
+def get_default_runtime_path() -> Path:
+    """Get the default path for runtime DLLs.
+
+    Returns:
+        Path to ~/.epyraw/runtimes/net8old/
+    """
+    return Path.home() / ".epyraw" / "runtimes" / "net8old"
+
+
+def download_runtimes(
+    target_path: Path | None = None, force: bool = False, progress: bool = True
+) -> Path:
+    """Download the Thermo RawFileReader runtime DLLs.
+
+    Args:
+        target_path: Optional custom path for DLLs. Defaults to ~/.epyraw/runtimes/net8old/
+        force: If True, re-download even if files exist
+        progress: If True, print progress messages
+
+    Returns:
+        Path to the directory containing the downloaded DLLs
+
+    Raises:
+        RuntimeError: If download fails
+        ImportError: If requests library is not installed
+    """
+    if requests is None:
+        raise ImportError(
+            "requests library is required for downloading runtimes. "
+            "Install it with: pip install requests"
+        )
+
+    if target_path is None:
+        target_path = get_default_runtime_path()
+
+    # Create target directory
+    target_path.mkdir(parents=True, exist_ok=True)
+
+    base_url = RAW_FILE_READER_URLS["base_url"]
+    files = RAW_FILE_READER_URLS["files"]
+
+    downloaded = []
+    failed = []
+
+    for filename in files:
+        file_path = target_path / filename
+        if file_path.exists() and not force:
+            if progress:
+                print(f"  Skipping {filename} (already exists)")
+            downloaded.append(file_path)
+            continue
+
+        url = base_url + filename
+        try:
+            if progress:
+                print(f"  Downloading {filename}...")
+            response = requests.get(url, timeout=30)
+            response.raise_for_status()
+
+            with open(file_path, "wb") as f:
+                f.write(response.content)
+            downloaded.append(file_path)
+        except Exception as e:
+            # Clean up partial download
+            if file_path.exists():
+                file_path.unlink()
+            failed.append((filename, str(e)))
+
+    if failed:
+        error_msg = "\n".join(f"  {name}: {err}" for name, err in failed)
+        raise RuntimeError(f"Failed to download some files:\n{error_msg}")
+
+    if progress:
+        print(f"Successfully downloaded {len(downloaded)} files to: {target_path}")
+
+    return target_path
+
+
+def check_runtimes_present(path: Path | None = None) -> bool:
+    """Check if runtime DLLs are present.
+
+    Args:
+        path: Optional custom path. Defaults to ~/.epyraw/runtimes/net8old/
+
+    Returns:
+        True if all required DLLs are present
+    """
+    if path is None:
+        path = get_default_runtime_path()
+
+    required_files = [
+        "ThermoFisher.CommonCore.RawFileReader.dll",
+        "ThermoFisher.CommonCore.Data.dll",
+        "ThermoFisher.CommonCore.BackgroundSubtraction.dll",
+        "ThermoFisher.CommonCore.MassPrecisionEstimator.dll",
+        "OpenMcdf.dll",
+    ]
+
+    return all((path / f).exists() for f in required_files)
+
+
+def ensure_runtimes_available(runtime_path: Path | None = None) -> Path:
+    """Ensure runtime DLLs are available, downloading if necessary.
+
+    Args:
+        runtime_path: Optional custom path. Checks default location if not provided.
+
+    Returns:
+        Path to the runtime directory
+
+    Raises:
+        RuntimeError: If runtimes cannot be downloaded
+    """
+    # Check provided path first
+    if runtime_path is not None and Path(runtime_path).exists():
+        return Path(runtime_path)
+
+    # Check default user path
+    default_path = get_default_runtime_path()
+    if default_path.exists() and check_runtimes_present(default_path):
+        return default_path
+
+    # Try to download
+    print("Thermo RawFileReader runtime DLLs not found.")
+    print("Downloading from GitHub...")
+    return download_runtimes()

epyraw/enums.py

@@ -0,0 +1,208 @@
+"""Enum types for Thermo RawFile Reader.
+
+These enums mirror the .NET enum types from the RawFileReader library,
+providing a Pythonic interface to filter and select data.
+"""
+
+from enum import IntEnum
+
+
+class Device(IntEnum):
+    """Instrument device types.
+
+    Values match the Thermo RawFileReader .NET Device enum:
+    https://github.com/thermofisherlsms/RawFileReader
+    """
+
+    MS = 0
+    MSAnalog = 1
+    Analog = 2
+    Other = 5
+    Pda = 4
+    UV = 3
+
+
+class MSOrderType(IntEnum):
+    """Mass spectrometry order."""
+
+    Unknown = 0
+    Ms = 1
+    Ms2 = 2
+    Ms3 = 3
+    MsN = 4
+
+
+class IonizationMode(IntEnum):
+    """Ionization mode."""
+
+    Unknown = 0
+    Positive = 1
+    Negative = 2
+
+
+class PolarityType(IntEnum):
+    """Polarity type."""
+
+    Unknown = 0
+    Positive = 1
+    Negative = 2
+
+
+class MassAnalyzerType(IntEnum):
+    """Mass analyzer types."""
+
+    Unknown = 0
+    Quadrupole = 1
+    IonTrap = 2
+    TOF = 3
+    Orbitrap = 4
+    FTICR = 5
+    Sector = 6
+
+
+class DetectorType(IntEnum):
+    """Detector types."""
+
+    Unknown = 0
+    ElectronMultiplier = 1
+    FaradayCup = 2
+    PhotodiodeArray = 3
+    CCD = 4
+
+
+class TraceType(IntEnum):
+    """Chromatogram trace types."""
+
+    BasePeak = 0
+    TIC = 1
+    A2DChannel1 = 2
+    A2DChannel2 = 3
+    A2DChannel3 = 4
+    A2DChannel4 = 5
+    Analog1 = 6
+    Analog2 = 7
+    Analog3 = 8
+    Analog4 = 9
+    UV1 = 10
+    UV2 = 11
+    UV3 = 12
+    PDA1 = 13
+    PDA2 = 14
+    PDA3 = 15
+
+
+class ToleranceUnits(IntEnum):
+    """Mass tolerance units."""
+
+    Daltons = 0
+    ppm = 1
+
+
+class SampleType(IntEnum):
+    """Sample types."""
+
+    Unknown = 0
+    Blank = 1
+    Standard = 2
+    QualityControl = 3
+    Sample = 4
+    CalibrationStandard = 5
+    SystemSuitability = 6
+
+
+class GenericDataTypes(IntEnum):
+    """Generic data types for status log and trailer extra fields."""
+
+    NULL = 0
+    Double = 1
+    String = 2
+    DateTime = 3
+    Int32 = 4
+    Int64 = 5
+
+
+class SpectrumPacketType(IntEnum):
+    """Type of spectrum data packet.
+
+    Values match the Thermo RawFileReader .NET SpectrumPacketType enum.
+    """
+
+    FtCentroid = 0
+    """Fourier transform centroid data."""
+
+    FtProfile = 1
+    """Fourier transform profile data."""
+
+    QuadrupoleCentroid = 2
+    """Quadrupole centroid data."""
+
+    QuadrupoleProfile = 3
+    """Quadrupole profile data."""
+
+
+class ScanTypeEnum(IntEnum):
+    """Type of scan performed.
+
+    Values match common Thermo instrument scan types.
+    """
+
+    Full = 0
+    """Full scan."""
+
+    SIM = 1
+    """Selected ion monitoring (SIM) scan."""
+
+    ProductIon = 2
+    """Product ion scan."""
+
+    DataDependent = 3
+    """Data-dependent scan."""
+
+    TopN = 4
+    """Top N scan."""
+
+
+class TrayShape(IntEnum):
+    """Autosampler tray shape.
+
+    Values match the Thermo RawFileReader .NET TrayShape enum.
+    """
+
+    Rectangular = 0
+    """Rectangular tray layout."""
+
+    Circular = 1
+    """Circular tray layout."""
+
+    StaggeredOdd = 2
+    """Staggered layout for odd rows."""
+
+    StaggeredEven = 3
+    """Staggered layout for even rows."""
+
+    Unknown = 4
+    """Unknown tray shape."""
+
+    Invalid = 5
+    """Invalid tray shape."""
+
+
+class BarcodeStatusType(IntEnum):
+    """Barcode read status.
+
+    Values match the Thermo RawFileReader .NET BarcodeStatusType enum.
+    """
+
+    NotRead = 0
+    """Barcode was not read."""
+
+    Read = 1
+    """Barcode was successfully read."""
+
+    ReadFailed = 2
+    """Barcode read failed."""
+
+
+# Type aliases for clarity
+TraceTypeName = str
+"""Type alias for trace type names."""

epyraw/exceptions.py

@@ -0,0 +1,49 @@
+"""Custom exceptions for Thermo RawFile Reader."""
+
+
+class ThermoRawFileError(Exception):
+    """Base exception for Thermo RawFile Reader errors."""
+
+    pass
+
+
+class RawFileNotFoundError(ThermoRawFileError):
+    """Raised when the RAW file cannot be found."""
+
+    pass
+
+
+class RawFileOpenError(ThermoRawFileError):
+    """Raised when the RAW file cannot be opened."""
+
+    pass
+
+
+class RawFileCorruptedError(ThermoRawFileError):
+    """Raised when the RAW file is corrupted or has read errors."""
+
+    pass
+
+
+class InvalidScanNumberError(ThermoRawFileError):
+    """Raised when an invalid scan number is requested."""
+
+    pass
+
+
+class InstrumentNotSelectedError(ThermoRawFileError):
+    """Raised when an operation requires instrument selection."""
+
+    pass
+
+
+class AssemblyLoadError(ThermoRawFileError):
+    """Raised when a .NET assembly fails to load."""
+
+    pass
+
+
+class InitializationError(ThermoRawFileError):
+    """Raised when the .NET runtime fails to initialize."""
+
+    pass