Refactoring with MuData

README.md

@@ -63,18 +63,18 @@ sc.pp.neighbors(adata, n_neighbors=10)
 milo.make_nhoods(adata)
 
 ## Count cells from each sample in each nhood
-milo.count_nhoods(adata, sample_col="sample")
+milo_mdata = milo.count_nhoods(adata, sample_col="sample")
 
 ## Test for differential abundance between conditions
-milo.DA_nhoods(adata, design="~ condition")
+milo.DA_nhoods(milo_mdata, design="~ condition")
 
 ## Check results
-milo_results = adata.uns["nhood_adata"].obs
+milo_results = milo_mdata['samples'].obs
 milo_results
 ```
 
 Visualize results on UMAP embedding
 ```python
-milopy.utils.build_nhood_graph(adata)
-milopy.plot.plot_nhood_graph(adata, alpha=0.2, min_size=5)
+milopy.utils.build_nhood_graph(milo_mdata)
+milopy.plot.plot_nhood_graph(milo_mdata, alpha=0.2, min_size=5)
 ```

docs/_build/_sources/autoapi/milopy/core/index.rst.txt

@@ -29,6 +29,8 @@ Functions
    position. Thus, multiple neighbourhoods may be collapsed down together to
    prevent over-sampling the graph space.
 
+   Params:
+   -------
    - adata: AnnData object. Should contain a knn graph in `adata.obsp`
    - neighbors_key: string indicating the key in `adata.obsp` to use as KNN graph. If not specified, 
    `make_nhoods` looks .obsp[‘connectivities’] for connectivities (default storage places for
@@ -37,33 +39,61 @@ Functions
    - prop: fraction of cells to sample for neighbourhood index search (default: 0.1)
    - seed: random seed for cell sampling (default: 42)
 
+   Returns:
+   --------
+   None, adds in place:
+   - `adata.obsm['nhoods']`: a binary matrix of cell to neighbourhood assignments
+   - `adata.obs['nhood_ixs_refined']`: a boolean indicating whether a cell is an index for a neighbourhood
+   - `adata.obs['kth_distance']`: the distance to the kth nearest neighbour for each index cell (used for SpatialFDR correction)
+   - `adata.uns["nhood_neighbors_key"]`: stores the KNN graph key in `adata.obsp` used for neighbourhood construction
+
 
 .. py:function:: count_nhoods(adata: anndata.AnnData, sample_col: str)
 
-   - adata
-   - sample_col: string, column in adata.obs that contains sample information 
-   (what should be in the columns of the nhoodCount matrix)
+   Builds a sample-level AnnData object storing the matrix of cell counts per sample per neighbourhood.
 
-   Returns: None
-   Updated adata.uns slot to contain adata.uns["nhood_adata"], where:
-   - adata.uns["nhood_adata"].obs_names are neighbourhoods
-   - adata.uns["nhood_adata"].var_names are samples
-   - adata.uns["nhood_adata"].X is the matrix counting the number of cells from each
+   Params:
+   -------
+   - adata: AnnData object with neighbourhoods defined in `adata.obsm['nhoods']`
+   - sample_col: string, column in adata.obs that contains sample information 
+   (what should be in the columns of the cell count matrix)
+
+   Returns: 
+   --------
+   MuData object storing the original (i.e. cell-level) AnnData in `mudata['cells']`
+   and the sample-level anndata storing the neighbourhood cell counts in `mudata['samples']`.
+   Here:
+   - `mudata['samples'].obs_names` are samples (defined from `adata.obs['sample_col']`)
+   - `mudata['samples'].var_names` are neighbourhoods 
+   - `mudata['samples'].X` is the matrix counting the number of cells from each
    sample in each neighbourhood
 
 
-.. py:function:: DA_nhoods(adata, design, model_contrasts=None, subset_samples=None, add_intercept=True)
+.. py:function:: DA_nhoods(milo_mdata: mudata.MuData, design: str, model_contrasts: str = None, subset_samples: List[str] = None, add_intercept: bool = True)
 
-   This will perform differential neighbourhood abundance testing (using edgeR under the hood)
-   - adata
-   - design: formula (terms should be columns in adata.uns["nhood_adata"].var)
-   - model_contrasts: A string vector that defines the contrasts used to perform DA testing
-   - subset_samples: subset of samples (columns in `adata.uns["nhood_adata"].X`) to use for the test
-   - add_intercept: whether to include an intercept in the model. If False, this is equivalent to adding + 0 in the design formula.
+   Performs differential abundance testing on neighbourhoods using QLF test implementation from edgeR
+   (using R code under the hood)
+
+   Params:
+   -------
+   - milo_mdata: MuData object, output of `count_nhoods`
+   - design: formula for the test, following glm syntax from R (e.g. '~ condition'). Terms should be columns in `milo_mdata['cells'].obs`.
+   - model_contrasts: A string vector that defines the contrasts used to perform DA testing, following glm syntax from R (e.g. "conditionDisease - conditionControl").
+       If no contrast is specified (default), then the last categorical level in condition of interest is used as the test group.
+   - subset_samples: subset of samples (obs in `milo_mdata['samples']`) to use for the test
+   - add_intercept: whether to include an intercept in the model. If False, this is equivalent to adding + 0 in the design formula. 
    When model_contrasts is specified, this is set to False by default. 
 
+   Returns:
+   --------
+   None, modifies `milo_mdata['samples']` in place, adding the results of the DA test to `.var`:
+   - `logFC` stores the log fold change in cell abundance (coefficient from the GLM)
+   - `PValue` stores the p-value for the QLF test before multiple testing correction
+   - `SpatialFDR` stores the the p-value adjusted for multiple testing to limit the false discovery rate, 
+       calculated with weighted Benjamini-Hochberg procedure
+
 
-.. py:function:: _graph_spatialFDR(adata, neighbors_key=None)
+.. py:function:: _graph_spatialFDR(sample_adata, neighbors_key=None)
 
    FDR correction weighted on inverse of connectivity of neighbourhoods.
    The distance to the k-th nearest neighbor is used as a measure of connectivity.

docs/_build/_sources/autoapi/milopy/index.rst.txt

@@ -29,7 +29,7 @@ Package Contents
 ----------------
 
 .. py:data:: __version__
-   :annotation: = 0.0.999
+   :annotation: = 0.1.0
 
 
 

docs/_build/_sources/autoapi/milopy/plot/index.rst.txt

@@ -21,13 +21,13 @@ Functions
 
 
 
-.. py:function:: plot_nhood_graph(adata: anndata.AnnData, alpha: float = 0.1, min_logFC: float = 0, min_size: int = 10, plot_edges: bool = False, title: str = 'DA log-Fold Change', **kwargs)
+.. py:function:: plot_nhood_graph(milo_mdata: mudata.MuData, alpha: float = 0.1, min_logFC: float = 0, min_size: int = 10, plot_edges: bool = False, title: str = 'DA log-Fold Change', **kwargs)
 
    Visualize DA results on abstracted graph (wrapper around sc.pl.embedding)
 
    Params:
    -------
-   - adata: AnnData object
+   - milo_mdata: MuData object
    - alpha: significance threshold
    - min_logFC: minimum absolute log-Fold Change to show results (default: 0, show all significant neighbourhoods)
    - min_size: minimum size of nodes in visualization (default: 10)
@@ -40,14 +40,20 @@ Functions
 
    Visualize cells in a neighbourhood
 
+   Params:
+   ------
+   - adata: AnnData object, storing neighbourhood assignments in `adata.obsm['nhoods']`
+   - ix: index of neighbourhood to visualize
+   - basis: embedding to use for visualization (default: 'X_umap')
+
 
-.. py:function:: plot_DA_beeswarm(adata: anndata.AnnData, anno_col: str = 'nhood_annotation', alpha: float = 0.1, subset_nhoods: List = None)
+.. py:function:: plot_DA_beeswarm(milo_mdata: mudata.MuData, anno_col: str = 'nhood_annotation', alpha: float = 0.1, subset_nhoods: List = None)
 
    Plot beeswarm plot of logFC against nhood labels
 
    Params:
    -------
-   - adata: AnnData object
+   - milo_mdata: MuData object
    - anno_col: column in adata.uns['nhood_adata'].obs to use as annotation
    - alpha: significance threshold
    - subset_nhoods: list of nhoods to plot (default: None, plot all nhoods)
@@ -56,13 +62,13 @@ Functions
 .. py:function:: _get_palette_adata(adata, obs_col)
 
 
-.. py:function:: plot_nhood_counts_by_cond(adata: anndata.AnnData, test_var: str, subset_nhoods: List = None, log_counts: bool = False)
+.. py:function:: plot_nhood_counts_by_cond(milo_mdata: mudata.MuData, test_var: str, subset_nhoods: List = None, log_counts: bool = False)
 
    Plot boxplot of cell numbers vs condition of interest
 
    Params:
    ------
-   - adata: anndata object storing neighbourhood information in adata.uns
+   - milo_mdata: MuData object storing cell level and nhood level information
    - test_var: string, name of column in adata.obs storing condition of interest (y-axis for boxplot)
    - subset_nhoods: list of obs_names for neighbourhoods to include in plot (default: None, plot all nhoods)
    - log_counts: boolean, whether to plot log1p of cell counts (default: False)

docs/_build/_sources/autoapi/milopy/tests/index.rst.txt

@@ -11,9 +11,9 @@ Submodules
    :maxdepth: 1
 
    test_DA_nhoods/index.rst
+   test_add_nhood_expression/index.rst
    test_annotate_nhoods/index.rst
    test_count_nhoods/index.rst
-   test_io/index.rst
    test_make_nhoods/index.rst
    test_plot/index.rst
 

docs/_build/_sources/autoapi/milopy/tests/test_DA_nhoods/index.rst.txt

@@ -13,26 +13,30 @@ Functions
 
 .. autoapisummary::
 
-   milopy.tests.test_DA_nhoods.anndata
+   milopy.tests.test_DA_nhoods.milo_mdata
    milopy.tests.test_DA_nhoods.test_missing_covariate
    milopy.tests.test_DA_nhoods.test_non_unique_covariate
    milopy.tests.test_DA_nhoods.test_pvalues
    milopy.tests.test_DA_nhoods.test_fdr
+   milopy.tests.test_DA_nhoods.test_default_contrast
 
 
 
-.. py:function:: anndata(seed=42)
+.. py:function:: milo_mdata(seed=42)
 
 
-.. py:function:: test_missing_covariate(anndata)
+.. py:function:: test_missing_covariate(milo_mdata)
 
 
-.. py:function:: test_non_unique_covariate(anndata)
+.. py:function:: test_non_unique_covariate(milo_mdata)
 
 
-.. py:function:: test_pvalues(anndata)
+.. py:function:: test_pvalues(milo_mdata)
 
 
-.. py:function:: test_fdr(anndata)
+.. py:function:: test_fdr(milo_mdata)
+
+
+.. py:function:: test_default_contrast(milo_mdata)
 
 

docs/_build/_sources/autoapi/milopy/tests/test_add_nhood_expression/index.rst.txt

@@ -0,0 +1,30 @@
+:py:mod:`milopy.tests.test_add_nhood_expression`
+================================================
+
+.. py:module:: milopy.tests.test_add_nhood_expression
+
+
+Module Contents
+---------------
+
+
+Functions
+~~~~~~~~~
+
+.. autoapisummary::
+
+   milopy.tests.test_add_nhood_expression.mdata
+   milopy.tests.test_add_nhood_expression.test_nhood_mean_range
+   milopy.tests.test_add_nhood_expression.test_nhood_mean_range
+
+
+
+.. py:function:: mdata(seed=42)
+
+
+.. py:function:: test_nhood_mean_range(mdata)
+
+
+.. py:function:: test_nhood_mean_range(mdata)
+
+

docs/_build/_sources/autoapi/milopy/tests/test_annotate_nhoods/index.rst.txt

@@ -13,7 +13,7 @@ Functions
 
 .. autoapisummary::
 
-   milopy.tests.test_annotate_nhoods.adata
+   milopy.tests.test_annotate_nhoods.milo_mdata
    milopy.tests.test_annotate_nhoods.prep_nhood_matrix
    milopy.tests.test_annotate_nhoods.test_nhood_mean_range
    milopy.tests.test_annotate_nhoods.test_correct_mean
@@ -22,21 +22,21 @@ Functions
 
 
 
-.. py:function:: adata(seed=42)
+.. py:function:: milo_mdata(seed=42)
 
 
 .. py:function:: prep_nhood_matrix(seed)
 
 
-.. py:function:: test_nhood_mean_range(adata)
+.. py:function:: test_nhood_mean_range(milo_mdata)
 
 
-.. py:function:: test_correct_mean(adata)
+.. py:function:: test_correct_mean(milo_mdata)
 
 
-.. py:function:: test_nhood_annotation_frac_range(adata)
+.. py:function:: test_nhood_annotation_frac_range(milo_mdata)
 
 
-.. py:function:: test_nhood_annotation_cont_gives_error(adata)
+.. py:function:: test_nhood_annotation_cont_gives_error(milo_mdata)