microarray 0.1.0__py3-none-any.whl

microarray/preprocessing/_log2.py

@@ -0,0 +1,77 @@
+import warnings
+
+import numpy as np
+from anndata import AnnData
+
+
+def log2(
+    adata: AnnData,
+    copy: bool = False,
+    layer: str | None = None,
+    key_added: str | None = None,
+) -> AnnData | None:
+    """Apply log2 transformation to the data.
+
+    Parameters
+    ----------
+    adata : AnnData
+        Input AnnData object containing microarray data.
+    copy : bool, optional
+        Whether to return a new AnnData object or modify in place.
+    layer : str, optional
+        If specified, apply log2 transformation to the data in this layer instead of `adata.X`.
+    key_added : str, optional
+        Key to store the log2-transformed data in `adata.layers`.
+        If None, the transformation is applied directly to `adata.X`.
+
+    Returns:
+    -------
+    AnnData | None
+        Log2-transformed AnnData if `copy=True`, otherwise None.
+
+    Notes:
+    -----
+    This function checks if the data appears to be already log-transformed (e.g., if max value < 100) and issues a warning if so.
+    """
+    if _is_log_transformed(adata):
+        warnings.warn(
+            "Data appears to be already log-transformed. Skipping log2 transformation.",
+            UserWarning,
+            stacklevel=2,
+        )
+        return adata.copy() if copy else None
+
+    if copy:
+        adata = adata.copy()
+
+    X_to_transform = adata.layers[layer] if layer is not None else adata.X
+
+    if key_added is not None:
+        if key_added in adata.layers:
+            warnings.warn(
+                f"Layer '{key_added}' already exists and will be overwritten with log2-transformed data.",
+                UserWarning,
+                stacklevel=2,
+            )
+        adata.layers[key_added] = np.log2(X_to_transform + 1)
+    else:
+        adata.X = np.log2(X_to_transform + 1)
+
+    return adata if copy else None
+
+
+def _is_log_transformed(adata: AnnData) -> bool:
+    """Heuristic check if data is already log-transformed.
+
+    Log-transformed microarray data typically has values mostly in the range [0, 20].
+    Raw intensities are typically in the range [1, 100000].
+    """
+    X = adata.X
+    max_val = np.max(X)
+    mean_val = np.mean(X)
+
+    # If max is relatively small and mean is in expected log range, likely log-transformed
+    if max_val < 30 and 3 < mean_val < 15:
+        return True
+
+    return False