smoother.simulation.utils
=========================

.. py:module:: smoother.simulation.utils

.. autoapi-nested-parse::

   Generate ST count matrix based on the assigned pattern.
   Some functions adapted from the cell2location paper:
       Kleshchevnikov, Vitalii, et al. "Cell2location maps fine-grained cell types in spatial transcriptomics."
       Nature biotechnology 40.5 (2022): 661-671.
       https://www.nature.com/articles/s41587-021-01139-4#



Functions
---------

.. autoapisummary::

   smoother.simulation.utils.sample_cell_indices
   smoother.simulation.utils.diag_block_mat_boolindex
   smoother.simulation.utils.smooth_by_neighbors
   smoother.simulation.utils.create_spatial_adata
   smoother.simulation.utils.cal_counts_ct
   smoother.simulation.utils.add_gamma_noises
   smoother.simulation.utils.grouped_obs_mean


Module Contents
---------------

.. py:function:: sample_cell_indices(generation_snrna, annot_label, cell_count_df, cell_capture_eff_df)

   Sample cell indices function adapted from cell2location paper
   (https://github.com/vitkl/cell2location_paper/blob/master/notebooks/benchmarking/synthetic_data_construction_improved_real_mg.ipynb)

   :param generation_snrna: reference single-cell adata.
   :param cell_count_df: Array of n_spots x n_cell_types
   :param cell_capture_eff_df: Array of n_spots x n_cell_types

   :returns: cell index matrix (n_spots x n_cells).


.. py:function:: diag_block_mat_boolindex(L)

   Helper function to generate diagonal matrix across n_experiments


.. py:function:: smooth_by_neighbors(shared_prop, locations2cells_matrix, coords, n_experiments)

   Smoothing the spot x cell-index matrix by neighoring spots

   :param shared_prop: proportion of cells that come from neighboring spots.
   :param locations2cells_matrix: binary spot x cell-index matrix,
                                  ((n_spots * n_experiments) x n_cells).
   :param coords: n_spots x 2 (x and y coordinates) grids, the same for all experiments.
   :param n_experiments: number of experiments.

   :returns: smoothed cell index matrix (n_spots x n_cells).


.. py:function:: create_spatial_adata(adata, locations2cells_matrix, cell_counts, cell_abundances, capture_eff, locations, cell_types2zones_df)

   Construct count matrix using locations x cell_indice matrix and reference anndata

   :param adata: refrence adata where the raw counts are stored in adata.X
   :param locations2cells_matrix: cell index matrix (n_spots x n_cells)
   :param locations: (n_experiments * n_spots) x 2 (x and y coordinates) grids
   :param cell_abundances: Array of n_spots x n_cell_types
   :param cell_count_df: Array of n_spots x n_cell_types
   :param cell_capture_eff_df: Array of n_spots x n_cell_types
   :param cell_types2zones_df: n_cell_types x n_zones matrix

   :returns: synthetic anndata object


.. py:function:: cal_counts_ct(synth_adata, orig_adata, annot_label, locations2cells_matrix)

   Compute synthetic counts per cell type

   :param synth_adata: synthetic adata
   :param orig_adata: reference adata
   :param annot_label: key to access celltype information
   :param locations2cells_matrix: cell index matrix (n_spots x n_cells)

   :returns: updated synth_adata with UMI per cell_type stored in obs


.. py:function:: add_gamma_noises(synth_adata, shape=0.4586, scale=1 / 0.6992)

   Fuction for adding noises adapted from cell2location paper
   (https://github.com/vitkl/cell2location_paper/blob/master/notebooks/benchmarking/synthetic_data_construction_improved_real_mg.ipynb)

   :param synth_adata: synthetic adata
   :param shape: shape of gamma distribution
   :param scale: scale of gamma distribution

   :returns: synthetic adata


.. py:function:: grouped_obs_mean(adata, group_key, layer=None, gene_symbols=None)

   Group referenceobs by celltypes and output group mean for deconvolution

   :param adata: reference anndata
   :param group_key: key to access celltype information
   :param layer: anndata layer that stores the feature matrix to calculate group mean
   :param gene_symbols: genes to keep; keep all genes when "none"

   :returns: gene x cell_type count matrix