milopy 0.3.0__py3-none-any.whl

milopy/__init__.py

@@ -0,0 +1,21 @@
+from .core import (
+    build_graph,
+    make_nhoods,
+    count_cells,
+    calc_nhood_distance,
+    test_nhoods,
+)
+from .meta import (
+    test_nhoods_meta,
+    test_nhoods_mixed,
+)
+
+__all__ = [
+    "build_graph",
+    "make_nhoods",
+    "count_cells",
+    "calc_nhood_distance",
+    "test_nhoods",
+    "test_nhoods_meta",
+    "test_nhoods_mixed",
+]

milopy/core.py

@@ -0,0 +1,190 @@
+import numpy as np
+import pandas as pd
+import scipy.sparse as sp
+import scanpy as sc
+import anndata
+
+def build_graph(adata, k=30, d=30, **kwargs):
+    """
+    Builds a kNN graph. Wraps scanpy.pp.neighbors.
+    """
+    if 'X_pca' not in adata.obsm:
+        raise ValueError("PCA must be computed first. Run sc.pp.pca(adata)")
+        
+    sc.pp.neighbors(adata, n_neighbors=k, n_pcs=d, **kwargs)
+    return adata
+
+def make_nhoods(adata, prop=0.1, k=30, d=30, refined=True, random_state=None):
+    """
+    Defines neighbourhoods on the kNN graph.
+    """
+    if 'distances' not in adata.obsp:
+        raise ValueError("kNN graph not found. Run build_graph(adata)")
+        
+    n_cells = adata.n_obs
+    n_nhoods = int(np.round(n_cells * prop))
+    
+    if random_state is not None:
+        np.random.seed(random_state)
+        
+    # Initial random sampling
+    vertex_indices = np.random.choice(n_cells, size=n_nhoods, replace=False)
+    
+    knn_graph = adata.obsp['connectivities']
+    
+    if refined:
+        # Refinement step: for each random vertex, find its neighbourhood,
+        # compute the median profile in PCA space, and pick the closest vertex.
+        pca_coords = adata.obsm['X_pca'][:, :d]
+        refined_vertices = []
+        for v in vertex_indices:
+            # Find neighbors of v
+            neighbors = knn_graph[v].nonzero()[1]
+            # include self
+            neighborhood = np.append(neighbors, v)
+            
+            # Compute median profile
+            median_profile = np.median(pca_coords[neighborhood], axis=0)
+            
+            # Find vertex in neighborhood closest to median
+            distances = np.linalg.norm(pca_coords[neighborhood] - median_profile, axis=1)
+            closest_idx = neighborhood[np.argmin(distances)]
+            refined_vertices.append(closest_idx)
+            
+        # Remove duplicates
+        vertex_indices = np.unique(refined_vertices)
+        
+    # Store neighborhoods as a sparse matrix: cells x nhoods
+    rows = []
+    cols = []
+    
+    for i, v in enumerate(vertex_indices):
+        neighbors = knn_graph[v].nonzero()[1]
+        neighborhood = np.append(neighbors, v)
+        rows.extend(neighborhood)
+        cols.extend([i] * len(neighborhood))
+        
+    nhoods_mat = sp.coo_matrix((np.ones(len(rows)), (rows, cols)), shape=(n_cells, len(vertex_indices))).tocsc()
+    
+    adata.obsm['nhoods'] = nhoods_mat
+    adata.uns['nhood_indices'] = vertex_indices
+    return adata
+
+def count_cells(adata, sample_col):
+    """
+    Counts cells in each neighbourhood across samples.
+    """
+    if 'nhoods' not in adata.obsm:
+        raise ValueError("Neighborhoods not found. Run make_nhoods(adata)")
+        
+    if sample_col not in adata.obs.columns:
+        raise ValueError(f"Sample column '{sample_col}' not found in adata.obs")
+        
+    samples = adata.obs[sample_col].astype('category')
+    sample_categories = samples.cat.categories
+    sample_codes = samples.cat.codes.values
+    
+    n_nhoods = adata.obsm['nhoods'].shape[1]
+    n_samples = len(sample_categories)
+    
+    # Initialize count matrix
+    counts = np.zeros((n_nhoods, n_samples))
+    
+    nhoods_mat = adata.obsm['nhoods'].tocsc()
+    
+    for i in range(n_nhoods):
+        cells_in_nhood = nhoods_mat[:, i].nonzero()[0]
+        # Count cells per sample in this neighborhood
+        nhood_sample_codes = sample_codes[cells_in_nhood]
+        counts[i, :] = np.bincount(nhood_sample_codes, minlength=n_samples)
+        
+    count_df = pd.DataFrame(counts, columns=sample_categories)
+    
+    # store in uns
+    adata.uns['nhood_counts'] = count_df
+    return adata
+
+def calc_nhood_distance(adata, d=30):
+    """
+    Calculates distances between neighbourhoods based on overlap or PCA distance.
+    """
+    if 'nhoods' not in adata.obsm:
+        raise ValueError("Neighborhoods not found. Run make_nhoods(adata)")
+        
+    nhoods_mat = adata.obsm['nhoods'].tocsc()
+    pca_coords = adata.obsm['X_pca'][:, :d]
+    
+    n_nhoods = nhoods_mat.shape[1]
+    
+    # compute median of each neighborhood
+    nhood_medians = np.zeros((n_nhoods, d))
+    for i in range(n_nhoods):
+        cells = nhoods_mat[:, i].nonzero()[0]
+        nhood_medians[i, :] = np.median(pca_coords[cells, :], axis=0)
+        
+    # compute euclidean distance between medians
+    from scipy.spatial.distance import pdist, squareform
+    dists = pdist(nhood_medians, metric='euclidean')
+    dist_mat = squareform(dists)
+    
+    adata.uns['nhood_distances'] = dist_mat
+    return adata
+
+def test_nhoods(adata, design, design_df, model_contrasts=None):
+    """
+    Tests for differential abundance using edgepython (pure Python edgeR port).
+    `design` is a formula string like '~ condition'
+    `design_df` is a pandas DataFrame with row names matching sample columns in `nhood_counts`
+    """
+    if 'nhood_counts' not in adata.uns:
+        raise ValueError("Neighborhood counts not found. Run count_cells(adata, sample_col)")
+        
+    import edgepython as ep
+    import patsy
+    
+    # Counts are nhoods x samples
+    counts_df = adata.uns['nhood_counts']
+    
+    # Ensure design_df is aligned with counts_df columns
+    design_df = design_df.loc[counts_df.columns]
+    
+    # edgepython expects genes x samples (rows=features, cols=samples)
+    # Our counts_df is nhoods x samples, which is already the right orientation
+    counts_matrix = counts_df.values.astype(float)
+    
+    # Create DGEList
+    y = ep.make_dgelist(counts=counts_matrix)
+    y = ep.calc_norm_factors(y, method="TMM")
+    
+    # Create design matrix using patsy
+    design_mat = patsy.dmatrix(design, design_df, return_type='dataframe')
+    design_array = np.asarray(design_mat, dtype=float)
+    
+    # Estimate dispersion
+    y = ep.estimate_disp(y, design=design_array)
+    
+    # Fit QL GLM
+    fit = ep.glm_ql_fit(y, design=design_array, robust=True)
+    
+    # Test
+    if model_contrasts is not None:
+        # Build contrast vector from string like "conditionB - conditionA"
+        # For now, support simple column index contrasts
+        res = ep.glm_ql_ftest(fit, contrast=model_contrasts)
+    else:
+        # Default to testing the last coefficient
+        n_coefs = design_array.shape[1]
+        res = ep.glm_ql_ftest(fit, coef=n_coefs - 1)
+        
+    # Get results table
+    top = ep.top_tags(res, n=counts_matrix.shape[0], sort_by="none")
+    res_df = top['table']
+    
+    # Ensure it's a DataFrame with the right index
+    if not isinstance(res_df, pd.DataFrame):
+        res_df = pd.DataFrame(res_df)
+    
+    res_df.index = counts_df.index
+    adata.uns['nhood_test_results'] = res_df
+    return adata
+

milopy/meta.py

@@ -0,0 +1,147 @@
+import numpy as np
+import pandas as pd
+import scipy.stats
+from statsmodels.stats.multitest import multipletests
+
+def test_nhoods_meta(adata, design, design_df, dataset_col, model_contrasts=None):
+    """
+    Random-Effects Meta-Analysis for multi-dataset Differential Abundance.
+    Runs edgepython GLM independently for each dataset and combines effects using
+    Inverse-Variance DerSimonian-Laird meta-analysis.
+    """
+    if 'nhood_counts' not in adata.uns:
+        raise ValueError("Neighborhood counts not found. Run count_cells(adata, sample_col)")
+        
+    import edgepython as ep
+    import patsy
+    
+    counts_df = adata.uns['nhood_counts']
+    design_df = design_df.loc[counts_df.columns]
+    
+    if dataset_col not in design_df.columns:
+        raise ValueError(f"Dataset column '{dataset_col}' not found in design_df")
+        
+    datasets = design_df[dataset_col].unique()
+    
+    n_nhoods = counts_df.shape[0]
+    
+    # Store effects and standard errors
+    all_logfc = np.zeros((n_nhoods, len(datasets)))
+    all_se = np.zeros((n_nhoods, len(datasets)))
+    all_logcpm = np.zeros((n_nhoods, len(datasets)))
+    
+    for k, ds in enumerate(datasets):
+        ds_samples = design_df[design_df[dataset_col] == ds].index
+        ds_counts = counts_df[ds_samples].values.astype(float)
+        ds_design = design_df.loc[ds_samples]
+        
+        y = ep.make_dgelist(counts=ds_counts)
+        y = ep.calc_norm_factors(y, method="TMM")
+        
+        design_mat = patsy.dmatrix(design, ds_design, return_type='dataframe')
+        design_array = np.asarray(design_mat, dtype=float)
+        
+        y = ep.estimate_disp(y, design=design_array)
+        fit = ep.glm_ql_fit(y, design=design_array, robust=True)
+        
+        if model_contrasts is not None:
+            res = ep.glm_ql_ftest(fit, contrast=model_contrasts)
+        else:
+            n_coefs = design_array.shape[1]
+            res = ep.glm_ql_ftest(fit, coef=n_coefs - 1)
+            
+        top = ep.top_tags(res, n=n_nhoods, sort_by="none")
+        res_df = pd.DataFrame(top['table'])
+        
+        # logFC and F-statistic from edgeR/edgepython
+        logfc = res_df['logFC'].values
+        f_stat = res_df['F'].values
+        # standard error from F-stat (assuming 1 DF: F = (beta/se)^2 => se = |beta| / sqrt(F))
+        se = np.abs(logfc) / np.sqrt(f_stat + 1e-12) # add small epsilon to avoid div by zero
+        
+        all_logfc[:, k] = logfc
+        all_se[:, k] = se
+        all_logcpm[:, k] = res_df['logCPM'].values
+
+    # DerSimonian-Laird Random Effects Meta-Analysis
+    variances = all_se**2
+    w_fixed = 1.0 / variances
+    w_sum = w_fixed.sum(axis=1)
+    beta_fixed = (w_fixed * all_logfc).sum(axis=1) / w_sum
+    
+    K = len(datasets)
+    Q = (w_fixed * (all_logfc - beta_fixed[:, None])**2).sum(axis=1)
+    c = w_sum - (w_fixed**2).sum(axis=1) / w_sum
+    tau2 = np.maximum(0, (Q - (K - 1)) / (c + 1e-12))
+    
+    w_random = 1.0 / (variances + tau2[:, None])
+    w_random_sum = w_random.sum(axis=1)
+    
+    meta_logfc = (w_random * all_logfc).sum(axis=1) / w_random_sum
+    meta_se = np.sqrt(1.0 / w_random_sum)
+    
+    z_stat = meta_logfc / meta_se
+    pvals = 2 * scipy.stats.norm.sf(np.abs(z_stat))
+    _, fdr, _, _ = multipletests(pvals, method='fdr_bh')
+    
+    meta_res = pd.DataFrame({
+        'logFC': meta_logfc,
+        'SE': meta_se,
+        'logCPM': np.mean(all_logcpm, axis=1),
+        'PValue': pvals,
+        'FDR': fdr,
+        'Tau2': tau2
+    }, index=counts_df.index)
+    
+    adata.uns['nhood_test_results'] = meta_res
+    return adata
+
+def test_nhoods_mixed(adata, design, design_df, dataset_col, model_contrasts=None):
+    """
+    Negative Binomial Mixed-Effects model for multi-dataset DA.
+    Uses edgepython's NEBULA-LN extension (ep.glm_sc_fit) modeling
+    'dataset_col' as the random effect grouping variable.
+    """
+    if 'nhood_counts' not in adata.uns:
+        raise ValueError("Neighborhood counts not found. Run count_cells(adata, sample_col)")
+        
+    import edgepython as ep
+    import patsy
+    
+    counts_df = adata.uns['nhood_counts']
+    design_df = design_df.loc[counts_df.columns]
+    
+    if dataset_col not in design_df.columns:
+        raise ValueError(f"Dataset column '{dataset_col}' not found in design_df")
+        
+    counts_matrix = counts_df.values.astype(float)
+    
+    design_mat = patsy.dmatrix(design, design_df, return_type='dataframe')
+    design_array = np.asarray(design_mat, dtype=float)
+    
+    try:
+        # Fit the NEBULA-LN model with the random effect (dataset_col)
+        fit = ep.glm_sc_fit(
+            y=counts_matrix,
+            cell_meta=design_df,
+            design=design_array,
+            sample=dataset_col,
+            norm_method='TMM'
+        )
+    except AttributeError:
+        raise NotImplementedError("ep.glm_sc_fit (NEBULA-LN) is missing or not compiled in this edgepython version.")
+    
+    n_nhoods = counts_matrix.shape[0]
+    
+    if model_contrasts is not None:
+        res = ep.glm_ql_ftest(fit, contrast=model_contrasts)
+    else:
+        n_coefs = design_array.shape[1]
+        res = ep.glm_ql_ftest(fit, coef=n_coefs - 1)
+        
+    top = ep.top_tags(res, n=n_nhoods, sort_by="none")
+    res_df = pd.DataFrame(top['table'])
+    res_df.index = counts_df.index
+    
+    adata.uns['nhood_test_results'] = res_df
+    return adata

milopy-0.3.0.dist-info/METADATA

@@ -0,0 +1,32 @@
+Metadata-Version: 2.5
+Name: milopy
+Version: 0.3.0
+Summary: A native Python implementation of miloR for differential abundance testing
+Project-URL: Homepage, https://github.com/LuJoHae/milopy
+Project-URL: Repository, https://github.com/LuJoHae/milopy.git
+Author-email: LuJoHae <lukas.j.haeuser@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: anndata
+Requires-Dist: edgepython
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: patsy
+Requires-Dist: scanpy
+Requires-Dist: scipy
+Provides-Extra: test
+Requires-Dist: anndata2ri; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: rpy2; extra == 'test'
+Description-Content-Type: text/markdown
+
+# milopy
+
+A native Python implementation of miloR for differential abundance testing of single-cell datasets.
+
+## Installation
+
+```bash
+pip install -e .
+```

milopy-0.3.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+milopy/__init__.py,sha256=BILZtDYnfYxayIqwS0v0qGphuQsDbH6pA2jcpB8u-BU,349
+milopy/core.py,sha256=wcog_bwowOOY_13Y95mpVvjgfXk0SPtVLCYKWExL9dk,6641
+milopy/meta.py,sha256=QWvwNMUAGL_Mauk_5mbaMvqcnWBjmex6Tzv0PIZzavI,5359
+milopy-0.3.0.dist-info/METADATA,sha256=ujuOrRdnuVdtayjLtg9PcE8XZXgRNNJ3t6LYPH8LCzE,856
+milopy-0.3.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+milopy-0.3.0.dist-info/licenses/LICENSE,sha256=_EeNUEP026NojJHSowCSC-yS5ZnUuGyN8Ym175Sbj_g,1073
+milopy-0.3.0.dist-info/RECORD,,

milopy-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

milopy-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Lukas J. Haeuser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.