microarray 0.1.0__tar.gz

microarray-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: microarray
+Version: 0.1.0
+Summary: Microarray analysis tools
+Author: harryhaller001
+Author-email: harryhaller001 <harryhaller001@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: adjusttext>=1.3
+Requires-Dist: anndata
+Requires-Dist: click
+Requires-Dist: matplotlib
+Requires-Dist: requests
+Requires-Dist: scikit-learn
+Requires-Dist: scipy
+Requires-Dist: statsmodels
+Requires-Dist: ipython ; extra == 'docs'
+Requires-Dist: myst-parser ; extra == 'docs'
+Requires-Dist: nbsphinx ; extra == 'docs'
+Requires-Dist: sphinx ; extra == 'docs'
+Requires-Dist: sphinx-autoapi ; extra == 'docs'
+Requires-Dist: sphinx-autodoc-typehints ; extra == 'docs'
+Requires-Dist: sphinx-book-theme ; extra == 'docs'
+Requires-Dist: decoupler>=2.1.4 ; extra == 'test'
+Requires-Dist: ipykernel ; extra == 'test'
+Requires-Dist: ipython ; extra == 'test'
+Requires-Dist: ipywidgets ; extra == 'test'
+Requires-Dist: pre-commit ; extra == 'test'
+Requires-Dist: pytest ; extra == 'test'
+Requires-Dist: pytest-cov ; extra == 'test'
+Requires-Dist: responses ; extra == 'test'
+Requires-Dist: ruff ; extra == 'test'
+Requires-Dist: scanpy>=1.11.5 ; extra == 'test'
+Requires-Dist: tqdm>=4.67.3 ; extra == 'test'
+Requires-Dist: twine ; extra == 'test'
+Requires-Dist: ty>=0.0.16 ; extra == 'test'
+Requires-Dist: types-requests ; extra == 'test'
+Maintainer: harryhaller001
+Maintainer-email: harryhaller001 <harryhaller001@gmail.com>
+Requires-Python: >=3.11
+Project-URL: Source, https://github.com/harryhaller001/microarray
+Provides-Extra: docs
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# microarray
+Processing microarray data in Python
+
+
+## Installation
+
+Use `pip` to install the microarray package:
+
+`pip install microarray`
+
+## Usage
+
+```python
+import microarray as ma
+```
+
+See tutorial notebook for detailed workflow examples.
+
+## License
+
+MIT

microarray-0.1.0/README.md

@@ -0,0 +1,21 @@
+# microarray
+Processing microarray data in Python
+
+
+## Installation
+
+Use `pip` to install the microarray package:
+
+`pip install microarray`
+
+## Usage
+
+```python
+import microarray as ma
+```
+
+See tutorial notebook for detailed workflow examples.
+
+## License
+
+MIT

microarray-0.1.0/pyproject.toml

@@ -0,0 +1,107 @@
+[build-system]
+build-backend = "uv_build"
+requires = [ "uv-build>=0.9.28,<0.10" ]
+
+[project]
+name = "microarray"
+version = "0.1.0"
+description = "Microarray analysis tools"
+readme = { file = "README.md", content-type = "text/markdown" }
+license = "MIT"
+maintainers = [ { name = "harryhaller001", email = "harryhaller001@gmail.com" } ]
+authors = [ { name = "harryhaller001", email = "harryhaller001@gmail.com" } ]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "adjusttext>=1.3",
+    "anndata",
+    "click",
+    "matplotlib",
+    "requests",
+    "scikit-learn",
+    "scipy",
+    "statsmodels",
+]
+optional-dependencies.docs = [
+    "ipython",                  # Required for syntax highlighing (https://github.com/spatialaudio/nbsphinx/issues/24)
+    "myst-parser",
+    "nbsphinx",
+    "sphinx",
+    "sphinx-autoapi",
+    "sphinx-autodoc-typehints",
+    "sphinx-book-theme",
+]
+optional-dependencies.test = [
+    "decoupler>=2.1.4",
+    "ipykernel",
+    "ipython",
+    "ipywidgets",
+    "pre-commit",
+    "pytest",
+    "pytest-cov",
+    "responses",
+    "ruff",
+    "scanpy>=1.11.5",
+    "tqdm>=4.67.3",
+    "twine",
+    "ty>=0.0.16",
+    "types-requests",
+]
+# urls.Documentation = "TODO"
+urls.Source = "https://github.com/harryhaller001/microarray"
+
+[tool.uv]
+package = true
+
+[tool.ruff]
+line-length = 120
+format.docstring-code-format = true
+lint.select = [ "B", "BLE", "C4", "D", "E", "F", "I", "RUF100", "TID", "UP", "W" ]
+lint.ignore = [ "B008", "C408", "D100", "D104", "D105", "D107", "D203", "D213", "D400", "D401", "E501", "E731", "E741" ]
+lint.per-file-ignores."*/__init__.py" = [ "F401" ]
+lint.per-file-ignores."docs/*" = [ "I" ]
+lint.per-file-ignores."test/*" = [ "D" ]
+lint.pydocstyle.convention = "google"
+
+[tool.pyproject-fmt]
+column_width = 120  # after how many column width split arrays/dicts into multiple lines, 1 will force always
+indent = 4
+keep_full_version = false  # if false will remove unnecessary trailing ``.0``'s from version specifiers
+max_supported_python = "3.14"  # maximum Python version to use when generating version specifiers
+
+[tool.pytest]
+ini_options.minversion = "7.0"
+ini_options.log_format = "%(asctime)s %(levelname)s %(message)s"
+ini_options.log_date_format = "%Y-%m-%d %H:%M:%S"
+ini_options.log_level = "INFO"
+ini_options.log_cli = true
+ini_options.python_files = "test_*.py"
+ini_options.testpaths = [ "tests" ]
+ini_options.xfail_strict = true
+ini_options.addopts = [
+    "--import-mode=importlib",           # allow using test files with same name
+    "--cov=src/microarray",
+    "--cov-report=html:coverage_report",
+    "--cov-report=term",
+]
+
+[tool.coverage]
+run.omit = [ "*/tests/*" ]
+run.source = [ "src/microarray" ]
+report.exclude_lines = [ "raise" ]
+report.ignore_errors = true
+html.directory = "coverage_report"
+
+[tool.ty]
+src.include = [ "src", "tests", "docs" ]

microarray-0.1.0/src/microarray/__init__.py

@@ -0,0 +1,15 @@
+import microarray.datasets as datasets
+import microarray.io as io
+import microarray.plotting as pl
+import microarray.preprocessing as pp
+import microarray.tools as tl
+from microarray._version import __version__
+
+__all__ = [
+    "__version__",
+    "io",
+    "pl",
+    "pp",
+    "tl",
+    "datasets",
+]

microarray-0.1.0/src/microarray/_version.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__: str = version("microarray")

microarray-0.1.0/src/microarray/datasets/__init__.py

@@ -0,0 +1,3 @@
+from microarray.datasets._cdf_files import hgu133a_cdf, hgu133plus2_cdf
+
+__all__ = ["hgu133a_cdf", "hgu133plus2_cdf"]

microarray-0.1.0/src/microarray/datasets/_arrayexpress.py

@@ -0,0 +1 @@
+# TODO: download dataset utils for arrayexpress datasets, e.g. from https://www.ebi.ac.uk/arrayexpress/experiments/E-GEOD-2109/files/

microarray-0.1.0/src/microarray/datasets/_cdf_files.py

@@ -0,0 +1,35 @@
+import os
+
+from microarray.io._cdf import CdfFile, parse_cdf
+
+
+def _get_cache_dir() -> str:
+    """Returns the path to the cache directory for CDF files."""
+    cache_dir = os.path.join(os.getcwd(), ".cache", "cdf")
+    # os.makedirs(cache_dir, exist_ok=True)
+    assert os.path.isdir(cache_dir), f"Cache directory not found: {cache_dir}"
+    return cache_dir
+
+
+def hgu133a_cdf() -> CdfFile:
+    """Returns the CDF file for the hgu133a microarray platform."""
+    cache_dir = _get_cache_dir()
+    cdf_path = os.path.join(cache_dir, "GPL24120_HGU133A_Hs_ENTREZG.cdf.gz")
+
+    if not os.path.isfile(cdf_path):
+        # TODO: download from GEO if not found
+        raise FileNotFoundError(f"CDF file not found: {cdf_path}")
+
+    return parse_cdf(cdf_path)
+
+
+def hgu133plus2_cdf() -> CdfFile:
+    """Returns the CDF file for the hgu133plus2 microarray platform."""
+    cache_dir = _get_cache_dir()
+    cdf_path = os.path.join(cache_dir, "GPL22945_HGU133Plus2_Hs_ENTREZG.cdf.gz")
+
+    if not os.path.isfile(cdf_path):
+        # TODO: download from GEO if not found
+        raise FileNotFoundError(f"CDF file not found: {cdf_path}")
+
+    return parse_cdf(cdf_path)

microarray-0.1.0/src/microarray/datasets/_geo.py

@@ -0,0 +1 @@
+# TODO: Download utils from GEO datasets, e.g. from https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE2109

microarray-0.1.0/src/microarray/datasets/_utils.py

@@ -0,0 +1,143 @@
+import os
+from typing import Any, BinaryIO, Literal
+from urllib.parse import urlencode, urlunparse
+
+import requests
+
+TIMEOUT = 1000
+
+
+def build_url(
+    hostname: str,
+    path: str,
+    scheme: Literal["http", "https", "ftp"] | str = "https",
+    query: dict[str, str | int | float] | None = None,
+    fragment: str | None = None,
+) -> str:
+    """Build url from parts.
+
+    Args:
+        hostname (str): Hostname of url (e.g. "example.com").
+        path (str): Path of url.
+        scheme (Literal["http", "https", "ftp"] | str, optional): Schema of url. Defaults to `https`.
+        query (dict[str, str | int | float] | None, optional): Query parameter. Defaults to `None`.
+        fragment (str | None, optional): Fragment of url. Defaults to `None`.
+
+    Returns:
+        str: Full url as string.
+    """
+    query_encoded: str = ""
+
+    if query is not None:
+        query_encoded = urlencode(query)
+
+    url = urlunparse(
+        [
+            scheme,
+            hostname,
+            path,
+            "",
+            query_encoded,
+            "" if fragment is None else fragment,
+        ]
+    )
+    return url
+
+
+def _file_or_buffer(
+    output_file: str | BinaryIO,
+    overwrite: bool = False,
+) -> BinaryIO:
+    """Harmonize file name and buffer.
+
+    Args:
+        output_file (str | BinaryIO): Filename to save object to or file object.
+        overwrite (bool, optional): Flag to overwrite, if output file already exist. Defaults to `False`.
+
+    Returns:
+        Memory buffer or opened File buffer.
+
+    Raises:
+        FileExistsError: If `overwrite=False` and output file already exists.
+    """
+    file_object: BinaryIO
+
+    if isinstance(output_file, str):
+        if overwrite is False and os.path.isfile(output_file):
+            raise FileExistsError(f"Output file '{output_file}' already exists.")
+
+        file_object = open(output_file, "wb")
+    else:
+        file_object = output_file
+
+    return file_object
+
+
+def download_file_stream(
+    url: str,
+    output_file: str | BinaryIO,
+    overwrite: bool = False,
+    chunk_size: int = 8192,
+    request_kwargs: dict[str, Any] | None = None,
+) -> None:
+    """Download file as stream. Source: https://stackoverflow.com/questions/16694907/download-large-file-in-python-with-requests.
+
+    Args:
+        url (str): URL to download.
+        output_file (str | BinaryIO): Filename to save object to or file object.
+        overwrite (bool, optional): Flag to overwrite, if output file already exist. Defaults to `False`.
+        chunk_size (int, optional): Size of downloaded chunk. Defaults to `8192`.
+        request_kwargs (dict[str, Any] | None, optional): Extra arguments passed to `requests.get` function. Defaults to `None`.
+
+    Raises:
+        FileExistsError: If `overwrite=False` and output file already exists.
+    """
+    file_object = _file_or_buffer(
+        output_file=output_file,
+        overwrite=overwrite,
+    )
+
+    if request_kwargs is None:
+        request_kwargs = {}
+
+    if "timeout" not in request_kwargs:
+        request_kwargs["timeout"] = TIMEOUT
+
+    with requests.get(url, stream=True, **request_kwargs) as requests_content:
+        requests_content.raise_for_status()
+        for chunk in requests_content.iter_content(chunk_size=chunk_size):
+            file_object.write(chunk)
+
+
+def download_file(
+    url: str,
+    output_file: str | BinaryIO,
+    overwrite: bool = False,
+    request_kwargs: dict[str, Any] | None = None,
+) -> None:
+    """Download file.
+
+    Args:
+        url (str): URL to download.
+        output_file (str | BinaryIO): Filename to save object to or file object.
+        overwrite (bool, optional): Flag to overwrite, if output file already exist. Defaults to `False`.
+        request_kwargs (dict[str, Any] | None, optional): Extra arguments passed to `requests.get` function. Defaults to `None`.
+
+    Raises:
+        FileExistsError: If `overwrite=False` and output file already exists.
+    """
+    file_object = _file_or_buffer(
+        output_file=output_file,
+        overwrite=overwrite,
+    )
+
+    if request_kwargs is None:
+        request_kwargs = {}
+
+    if "timeout" not in request_kwargs:
+        request_kwargs["timeout"] = TIMEOUT
+
+    response = requests.get(url, **request_kwargs)
+    response.raise_for_status()
+
+    file_object.write(response.content)

microarray-0.1.0/src/microarray/io/__init__.py

@@ -0,0 +1,17 @@
+from microarray.io._anndata_converter import (
+    cel_to_anndata,
+)
+from microarray.io._cdf import CdfFile, parse_cdf
+from microarray.io._cel import CelFile, apply_probe_annotation, parse_cel
+from microarray.io._read import read_cel, read_cel_batch
+
+__all__ = [
+    "apply_probe_annotation",
+    "parse_cel",
+    "parse_cdf",
+    "read_cel",
+    "read_cel_batch",
+    "CelFile",
+    "CdfFile",
+    "cel_to_anndata",
+]

microarray-0.1.0/src/microarray/io/_anndata_converter.py

@@ -0,0 +1,198 @@
+"""AnnData converter for microarray CEL/CDF data."""
+
+import os
+from collections import defaultdict
+
+import numpy as np
+import pandas as pd
+from anndata import AnnData
+
+from microarray.io._cdf import CdfFile, parse_cdf
+from microarray.io._cel import CelFile, parse_cel
+
+
+def cel_to_anndata(
+    cel_path: str | CelFile,
+    cdf_path: str | CdfFile,
+    sample_name: str | None = None,
+) -> AnnData:
+    """Convert a single CEL file to a probe-level AnnData object.
+
+    Creates an AnnData with shape (1, n_cells) where each variable represents
+    an individual CDF cell (probe):
+
+    - ``.X`` contains per-cell intensities.
+    - ``.var`` contains ``probeset_id``, ``probe_index`` (0-based rank within
+      probeset by ascending ``expos``, so 0 = 3' end), ``probe_type``
+      (``"pm"``, ``"mm"``, or ``"unknown"``), ``gene_id`` (gene identifier
+      extracted from probeset name), and ``suffix`` (Affymetrix probe type
+      suffix such as ``"_at"`` for antisense target).
+    - ``.obs`` contains sample metadata from the CEL header.
+    - ``.layers`` contains per-cell QC arrays: ``stdevs``, ``npixels``,
+      ``masks``, ``outliers``, ``modified``.
+    - ``.uns`` contains CDF chip info and CEL file metadata.
+
+
+    Parameters
+    ----------
+    cel_path : str | CelFile
+        Path to the CEL file or a parsed :class:`~microarray.io.CelFile`
+        instance.
+    cdf_path : str | CdfFile
+        Path to the CDF file or a parsed :class:`~microarray.io.CdfFile`
+        instance.
+    sample_name : str | None
+        Name used as the observation index.  Defaults to the CEL file's
+        basename, or ``"unknown"`` when a :class:`~microarray.io.CelFile`
+        instance is supplied without a path.
+
+    Returns:
+    -------
+    AnnData
+        Probe-level AnnData with shape ``(1, n_cells)``.
+    """
+    # Parse input files if they are paths
+    if isinstance(cel_path, str):
+        cel_file_path = cel_path
+        cel_file = parse_cel(cel_path)
+    else:
+        cel_file_path = None
+        cel_file = cel_path
+
+    if isinstance(cdf_path, str):
+        cdf_file = parse_cdf(cdf_path)
+    else:
+        cdf_file = cdf_path
+
+    if sample_name is None:
+        sample_name = os.path.basename(cel_file_path) if cel_file_path else "unknown"
+
+    obs = pd.DataFrame(
+        {
+            "sample_name": [sample_name],
+            "cel_version": [cel_file.version],
+            "nrows": [cel_file.nrows],
+            "ncols": [cel_file.ncols],
+            "algorithm": [cel_file.algorithm],
+        },
+        index=[sample_name],
+    )
+
+    uns = {
+        "cel_metadata": {
+            "total_x": cel_file.total_x,
+            "total_y": cel_file.total_y,
+            "offset_x": cel_file.offset_x,
+            "offset_y": cel_file.offset_y,
+            "grid_corner_ul": cel_file.grid_corner_ul,
+            "grid_corner_ur": cel_file.grid_corner_ur,
+            "grid_corner_ll": cel_file.grid_corner_ll,
+            "grid_corner_lr": cel_file.grid_corner_lr,
+            "axis_invert_x": cel_file.axis_invert_x,
+            "axis_invert_y": cel_file.axis_invert_y,
+            "swap_xy": cel_file.swap_xy,
+            "algorithm_parameters": cel_file.algorithm_parameters,
+            "dat_header": cel_file.dat_header,
+        },
+        "cdf_metadata": {
+            "chip_name": cdf_file.chip_info.name,
+            "chip_rows": cdf_file.chip_info.rows,
+            "chip_cols": cdf_file.chip_info.cols,
+            "number_of_units": cdf_file.chip_info.number_of_units,
+            "max_unit": cdf_file.chip_info.max_unit,
+            "num_qc_units": cdf_file.chip_info.num_qc_units,
+        },
+    }
+
+    # Collect cells per probeset to compute ordinal ranks.
+    # Structure: {probeset_id: [(expos, x, y, is_pm), ...]}
+    ps_cells: dict[str, list[tuple]] = defaultdict(list)
+
+    for unit in cdf_file.units:
+        for block in unit.blocks:
+            probeset_id = block.name if block.name and block.name != "NONE" else unit.name
+            for cell in block.cells:
+                expos_val = cell.expos if cell.expos is not None else 0
+                ps_cells[probeset_id].append((expos_val, cell.x, cell.y, cell.is_pm))
+
+    # Sort by expos within each probeset and assign ordinal rank.
+    # Smallest expos = 3' end = rank 0.
+    probeset_ids: list[str] = []
+    probe_indices: list[int] = []
+    probe_types: list[str] = []
+    probe_var_ids: list[str] = []
+    intensities_list: list[float] = []
+    stdevs_list: list[float] = []
+    npixels_list: list[float] = []
+    masks_list: list[float] = []
+    outliers_list: list[float] = []
+    modified_list: list[float] = []
+
+    for probeset_id, cells in ps_cells.items():
+        cells_sorted = sorted(cells, key=lambda c: c[0])
+        for ordinal_rank, (_, cx, cy, cell_is_pm) in enumerate(cells_sorted):
+            intensity = float(cel_file.intensities[cy, cx]) if cel_file.intensities is not None else float("nan")
+            stdev = float(cel_file.stdevs[cy, cx]) if cel_file.stdevs is not None else float("nan")
+            npixels = float(cel_file.npixels[cy, cx]) if cel_file.npixels is not None else float("nan")
+            masks = float(cel_file.masks[cy, cx]) if cel_file.masks is not None else float("nan")
+            outliers = float(cel_file.outliers[cy, cx]) if cel_file.outliers is not None else float("nan")
+            modified = float(cel_file.modified[cy, cx]) if cel_file.modified is not None else float("nan")
+
+            if cell_is_pm is True:
+                probe_type = "pm"
+            elif cell_is_pm is False:
+                probe_type = "mm"
+            else:
+                probe_type = "unknown"
+
+            var_id = f"{probeset_id}:{cx}:{cy}"
+            probeset_ids.append(probeset_id)
+            probe_indices.append(ordinal_rank)
+            probe_types.append(probe_type)
+            probe_var_ids.append(var_id)
+            intensities_list.append(intensity)
+            stdevs_list.append(stdev)
+            npixels_list.append(npixels)
+            masks_list.append(masks)
+            outliers_list.append(outliers)
+            modified_list.append(modified)
+
+    n_cells = len(probeset_ids)
+    X = np.array(intensities_list, dtype=np.float32).reshape(1, n_cells)
+
+    var = pd.DataFrame(
+        {
+            "probeset_id": probeset_ids,
+            "probe_index": probe_indices,
+            "probe_type": probe_types,
+        },
+        index=probe_var_ids,
+    )
+
+    # Merge probeset_info (gene_id and suffix) into var
+    if cdf_file.probeset_info is not None:
+        # Map probeset_id to gene_id and suffix by looking up in probeset_info
+        gene_ids = []
+        suffixes = []
+        for ps_id in probeset_ids:
+            if ps_id in cdf_file.probeset_info.index:
+                info = cdf_file.probeset_info.loc[ps_id]
+                gene_ids.append(info["gene_id"])
+                suffixes.append(info["suffix"])
+            else:
+                # Fallback if probeset not in probeset_info
+                gene_ids.append(ps_id)
+                suffixes.append("")
+
+        var["gene_id"] = gene_ids
+        var["suffix"] = suffixes
+
+    layers = {
+        "stdevs": np.array(stdevs_list, dtype=np.float32).reshape(1, n_cells),
+        "npixels": np.array(npixels_list, dtype=np.float32).reshape(1, n_cells),
+        "masks": np.array(masks_list, dtype=np.float32).reshape(1, n_cells),
+        "outliers": np.array(outliers_list, dtype=np.float32).reshape(1, n_cells),
+        "modified": np.array(modified_list, dtype=np.float32).reshape(1, n_cells),
+    }
+
+    return AnnData(X=X, obs=obs, var=var, layers=layers, uns=uns)