update API docu

AnneHartebrodt · AnneHartebrodt · commit cdfb003caa01 · 2026-01-07T17:33:13.000+01:00
diff --git a/docs/source/generated/netmap.downstream.clustering.rst b/docs/source/generated/netmap.downstream.clustering.rst
@@ -1,4 +1,4 @@
-netmap.downstream.clustering
+﻿netmap.downstream.clustering
 ============================
 
 .. currentmodule:: netmap.downstream.clustering
diff --git a/docs/source/generated/netmap.downstream.edge_selection.data_preprr.rst b/docs/source/generated/netmap.downstream.edge_selection.data_preprr.rst
diff --git a/docs/source/generated/netmap.downstream.edge_selection.rst b/docs/source/generated/netmap.downstream.edge_selection.rst
@@ -1,4 +1,4 @@
-netmap.downstream.edge\_selection
+﻿netmap.downstream.edge\_selection
 =================================
 
 .. currentmodule:: netmap.downstream.edge_selection
@@ -21,8 +21,6 @@ netmap.downstream.edge\_selection
 
    add_top_edge_annotation_global
 
-   data_preprr
-
 
 
 
diff --git a/docs/source/generated/netmap.downstream.final_downstream.rst b/docs/source/generated/netmap.downstream.final_downstream.rst
@@ -1,4 +1,4 @@
-netmap.downstream.final\_downstream
+﻿netmap.downstream.final\_downstream
 ===================================
 
 .. currentmodule:: netmap.downstream.final_downstream
diff --git a/docs/source/generated/netmap.downstream.gene_clustering.rst b/docs/source/generated/netmap.downstream.gene_clustering.rst
@@ -1,4 +1,4 @@
-netmap.downstream.gene\_clustering
+﻿netmap.downstream.gene\_clustering
 ==================================
 
 .. currentmodule:: netmap.downstream.gene_clustering
diff --git a/docs/source/generated/netmap.masking.external.rst b/docs/source/generated/netmap.masking.external.rst
@@ -1,4 +1,4 @@
-netmap.masking.external
+﻿netmap.masking.external
 =======================
 
 .. currentmodule:: netmap.masking.external
diff --git a/docs/source/generated/netmap.masking.internal.rst b/docs/source/generated/netmap.masking.internal.rst
@@ -1,4 +1,4 @@
-netmap.masking.internal
+﻿netmap.masking.internal
 =======================
 
 .. currentmodule:: netmap.masking.internal
diff --git a/docs/source/generated/netmap.model.nbautoencoder.rst b/docs/source/generated/netmap.model.nbautoencoder.rst
@@ -1,4 +1,4 @@
-netmap.model.nbautoencoder
+﻿netmap.model.nbautoencoder
 ==========================
 
 .. currentmodule:: netmap.model.nbautoencoder
diff --git a/docs/source/generated/netmap.model.standardautoencoder.rst b/docs/source/generated/netmap.model.standardautoencoder.rst
@@ -1,4 +1,4 @@
-netmap.model.standardautoencoder
+﻿netmap.model.standardautoencoder
 ================================
 
 .. currentmodule:: netmap.model.standardautoencoder
diff --git a/docs/source/generated/netmap.model.train_model.rst b/docs/source/generated/netmap.model.train_model.rst
@@ -1,4 +1,4 @@
-netmap.model.train\_model
+﻿netmap.model.train\_model
 =========================
 
 .. currentmodule:: netmap.model.train_model
diff --git a/docs/source/generated/netmap.model.zinbautoencoder.rst b/docs/source/generated/netmap.model.zinbautoencoder.rst
@@ -1,4 +1,4 @@
-netmap.model.zinbautoencoder
+﻿netmap.model.zinbautoencoder
 ============================
 
 .. currentmodule:: netmap.model.zinbautoencoder
diff --git a/docs/source/generated/netmap.utils.data_utils.rst b/docs/source/generated/netmap.utils.data_utils.rst
@@ -1,4 +1,4 @@
-netmap.utils.data\_utils
+﻿netmap.utils.data\_utils
 ========================
 
 .. currentmodule:: netmap.utils.data_utils
diff --git a/docs/source/generated/netmap.utils.misc.rst b/docs/source/generated/netmap.utils.misc.rst
@@ -1,4 +1,4 @@
-netmap.utils.misc
+﻿netmap.utils.misc
 =================
 
 .. currentmodule:: netmap.utils.misc
diff --git a/docs/source/generated/netmap.utils.netmap_config.rst b/docs/source/generated/netmap.utils.netmap_config.rst
@@ -1,4 +1,4 @@
-netmap.utils.netmap\_config
+﻿netmap.utils.netmap\_config
 ===========================
 
 .. currentmodule:: netmap.utils.netmap_config
diff --git a/docs/source/generated/netmap.utils.tf_utils.rst b/docs/source/generated/netmap.utils.tf_utils.rst
@@ -1,4 +1,4 @@
-netmap.utils.tf\_utils
+﻿netmap.utils.tf\_utils
 ======================
 
 .. currentmodule:: netmap.utils.tf_utils
diff --git a/src/netmap/downstream/clustering.py b/src/netmap/downstream/clustering.py
@@ -8,37 +8,60 @@
 from sklearn.cluster import KMeans, SpectralClustering
 from sklearn.metrics.cluster import contingency_matrix
 
-def downstream_recipe(adata)-> anndata.AnnData:
-    """
-    Downstream reciepe for an LRP anndata object:
-    TODO: replace the config dict, to pass values
+
+
+def downstream_recipe(grn_adata, config = {'min_cells':1, 'n_neighbors': 30, 'leiden_resolution': 0.1, 'n_components': 100, 'knn_neighbors': 50})-> anndata.AnnData:
     """
-    config = {'min_cells':1, 'n_neighbors': 30, 'leiden_resolution': 0.1, 'n_components': 100, 'knn_neighbors': 50}
-    #sc.pp.filter_genes(adata, min_cells=config['min_cells'])
-    #sc.pl.pca_variance_ratio(adata, n_pcs=50, log=True)
-    #sc.pp.normalize_total(adata)
-    #sc.pp.log1p(adata)
+    Minimal downstream processing for GRN object. Runs sc.pca (without scaling),
+    sc.neighbours, sc.leiden, sc. umap
 
-    sc.tl.pca(adata, svd_solver = 'randomized', zero_center = False)
+    Parameters
+    ----------
+    grn_adata : AnnData
+        A GRN anndata object to process
 
-    sc.pp.neighbors(adata, n_neighbors=config['knn_neighbors'])
-    sc.tl.leiden(adata, resolution=config['leiden_resolution'])
+    config: dict
+        Parameters for the processing
 
-    sc.tl.umap(adata, n_components = config['n_components'])
-    return adata
+    Returns
+    -------
+    grn_adata : AnnData
+        Processed Anndata object
+    """
+    
+    sc.tl.pca(grn_adata, svd_solver = 'randomized', zero_center = False)
+    sc.pp.neighbors(grn_adata, n_neighbors=config['knn_neighbors'])
+    sc.tl.leiden(grn_adata, resolution=config['leiden_resolution'])
+    sc.tl.umap(grn_adata, n_components = config['n_components'])
+
+    return grn_adata
 
 
 def spectral_clustering(adata, n_clu = 2, key_added = 'spectral'):
     """
     Run sklearn spectral clustering on the neighbour matrix in the anndata object.
 
-    Args:
-    adata: Anndata object
-    n_clu: Number of clusters to compute
-    key_added: The key to add the new labelling to [Default: spectral]
+
+    Parameters
+    ----------
+    grn_adata : AnnData
+        A GRN anndata object to process
+
+    n_clu: int
+        Number of clusters to compute
+    key_added: str
+        The key to add the new labelling to [Default: spectral]
+
+    Returns
+    -------
+    grn_adata : AnnData
+        Clustered Anndata object with an additional column in the .obs
+        slot of the object named `key_added`
     """
+
     sc.pp.neighbors(adata)
     ssc = SpectralClustering(n_clusters=n_clu,assign_labels='discretize',random_state=0, affinity= 'precomputed_nearest_neighbors').fit(adata.obsp['distances'])
+    
     counter = 0
     key_added_t = key_added
     while key_added_t in adata.obs.columns:
@@ -50,24 +73,68 @@ def spectral_clustering(adata, n_clu = 2, key_added = 'spectral'):
 
 
 
-def process(grn_adata, n_clu=2, cluster_var = 'spectral'):
+def process(grn_adata, n_clu=2, key_added = 'spectral'):
+    """
+    Wrapper function for convenience processing and clustering
+
+    Parameters
+    ----------
+    grn_adata : AnnData
+        A GRN anndata object to process
+
+    n_clu: int
+        Number of clusters to compute
+    key_added: str
+        The key to add the new labelling to [Default: spectral]
+
+    Returns
+    -------
+    grn_adata : AnnData
+        Processed Anndata object with an additional column in the .obs
+        slot of the object named `key_added`
+    """
+
     if not scs.issparse(grn_adata.X):
         grn_adata.X[np.isnan(grn_adata.X) ] = 0
     grn_adata = downstream_recipe(grn_adata)
-    print(f'clustering: {n_clu} clusters')
-    grn_adata = spectral_clustering(grn_adata, n_clu=n_clu, key_added = 'spectral')
+    grn_adata = spectral_clustering(grn_adata, n_clu=n_clu, key_added = key_added)
     return grn_adata
 
 
 
-def unify_group_labelling(adata, grn_adata, col_adata, col_grn_adata, return_mapping=False):
-    
+def unify_group_labelling(adata, grn_adata, col_adata, col_grn_adata) -> float:
+
+
     """
     Adjust group labelling such that grn_adata has the same group label than the 
     corresponding column in adata based on the grn column.
 
-    Returns the data objects and a score of the matching as the cost of the matching
-    divided by the number of cells.
+    Tee prrocessed GRN  Anndata object wwill contian ith an additional column in the
+    .obs slot containing a '_remap' column which contains a relabelled column
+    matching the clustering in adata
+
+    Returns a score of the matching as the cost of the matching divided by the number
+    of cells. The score ranges between 1/n_clusters and 1, with 1 indicating an identical
+    clustering and 1/n_clu a random matching.
+    
+    Parameters
+    ----------
+    adata : AnnData
+        original Anndata object containing a clustering column in the
+        obs object specified as `col_adata`
+    grn_adata : AnnData
+        original Anndata object containing a clustering column in the
+        obs object specified as `col_grn_adata`
+
+    col_adata_clu: str
+        Name of the reference column in expression object
+    col_grn_adata: str
+        Name of the novel clustering column in GRN object
+
+    Returns
+    -------
+    score: int 
+        The score of the linear sum assignment divided by the number of cells.
     """
 
     cm = contingency_matrix(adata.obs[col_adata], grn_adata.obs[col_grn_adata])
@@ -89,9 +156,7 @@ def unify_group_labelling(adata, grn_adata, col_adata, col_grn_adata, return_map
     grn_adata.obs[col_grn_adata_remapped] = pd.Categorical(grn_adata.obs[col_grn_adata_remapped])
 
     score = cm[row_ind, col_ind].sum()/adata.obs.shape[0]
-    if return_mapping:
-        return score
-    else:
-        return score
+    
+    return score
 
 
diff --git a/src/netmap/downstream/edge_selection.py b/src/netmap/downstream/edge_selection.py
@@ -3,7 +3,24 @@
 import numpy as np
 from collections import Counter
 
-def _get_top_edges_global(grn_adata, top_edges: int, layer = 'X'):
+def _get_top_edges_global(grn_adata, top_edges: float):
+    """
+    Subroutine to get the top edges from an Anndata GRN object
+
+    Parameters
+    ----------
+    grn_adata : AnnData
+        A GRN anndata object to process containing a layer 'sorted'
+        with the result of an argsort
+
+    top_edges: float
+        Percentage of interest
+
+    Returns
+    -------
+    final_df : pd.DataFrame
+        Processed Anndata object with the counted edges
+    """
 
     b = grn_adata.layers['sorted']
     # Calculate partition indices for all top_edges values
@@ -29,17 +46,38 @@ def _get_top_edges_global(grn_adata, top_edges: int, layer = 'X'):
 
 
     global_counter = top[0]
-    final_df = [data_preprr(global_counter, edge_metadata_np, top_edges[0])]
+    final_df = [_data_preprr(global_counter, edge_metadata_np, top_edges[0])]
     for i in range(1, len(top)):
         global_counter = global_counter + top[i]
         t_val = top_edges[i]
-        final_df.append(data_preprr(global_counter, edge_metadata_np, t_val))
+        final_df.append(_data_preprr(global_counter, edge_metadata_np, t_val))
     
     final_df = np.concatenate(final_df)
     final_df = pd.DataFrame(final_df)
     return final_df
 
-def data_preprr(global_counter, edge_metadata_np, top_edges_val):
+def _data_preprr(global_counter, edge_metadata_np, top_edges_val) -> pd.DataFrame:
+    
+    """
+    Subroutine of to identify the top scoring edges and count how many times an edge
+    is among the top edges.
+
+    Parameters
+    ----------
+    global_counter : Counter
+        A counter dictionary containing the keys of the edges
+
+    edge_metadata_np: np.ndarray
+        The names of the edges
+
+    top_edges_valu: float 
+        Top percentage to be returned with the data
+
+    Returns
+    -------
+    final_summary_result : pd.DataFrame
+        DataFrame with the edge counts per percentage
+    """
     
     edge_keys_list = []
     cell_counts_list = []
@@ -79,6 +117,31 @@ def data_preprr(global_counter, edge_metadata_np, top_edges_val):
 
 
 def add_top_edge_annotation_cluster(grn_adata, top_edges = [0.1], nan_fill = 0, cluster_var = 'spectral'):
+    """
+    Add annotation  colum(s) to the the var slot of the anndata object indicating whether the edge in
+    in the top n% edges (by value) by cluster. A list of possible values can be passed, and should be, if multiple
+    values are required, because the function requires sorting the object.
+
+    Parameters
+    ----------
+    grn_adata : AnnData
+        A GRN anndata object to process
+
+    top_edges: list
+        Percentages of interest
+
+    nan_fill: int [Default: 0]
+        Value to add when no edge is found
+    
+    key_name: str [Default: global]
+        Prefix name of column(s) created
+
+    Returns
+    -------
+    grn_adata : AnnData
+        Processed Anndata object with the column(s) added
+    """
+        
     var = grn_adata.var
     if var.index.name is None or var.index.name == 'index':
         var = var.reset_index()
@@ -103,6 +166,30 @@ def add_top_edge_annotation_cluster(grn_adata, top_edges = [0.1], nan_fill = 0,
 
 
 def add_top_edge_annotation_global(grn_adata, top_edges = [0.1], nan_fill = 0, key_name = 'global'):
+    """
+    Add annotation  colum(s) to the the var slot of the anndata object indicating whether the edge in
+    in the top n% edges (by value). A list of possible values can be passed, and should be, if multiple
+    values are required, because the function requires sorting the object.
+
+    Parameters
+    ----------
+    grn_adata : AnnData
+        A GRN anndata object to process
+
+    top_edges: list
+        Percentages of interest
+
+    nan_fill: int [Default: 0]
+        Value to add when no edge is found
+    
+    key_name: str [Default: global]
+        Prefix name of column(s) created
+
+    Returns
+    -------
+    grn_adata : AnnData
+        Processed Anndata object with the column(s) added
+    """
 
     var = grn_adata.var
     if var.index.name is None or var.index.name == 'index':
diff --git a/src/netmap/downstream/gene_clustering.py b/src/netmap/downstream/gene_clustering.py
diff --git a/src/netmap/grn/inferrence.py b/src/netmap/grn/inferrence.py
diff --git a/src/netmap/model_concept.py b/src/netmap/model_concept.py
diff --git a/src/netmap/netmap.py b/src/netmap/netmap.py

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-netmap.downstream.clustering`
	`1`	`+netmap.downstream.clustering`
`2`	`2`	`============================`
`3`	`3`
`4`	`4`	`.. currentmodule:: netmap.downstream.clustering`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-netmap.downstream.final\_downstream`
	`1`	`+netmap.downstream.final\_downstream`
`2`	`2`	`===================================`
`3`	`3`
`4`	`4`	`.. currentmodule:: netmap.downstream.final_downstream`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-netmap.downstream.gene\_clustering`
	`1`	`+netmap.downstream.gene\_clustering`
`2`	`2`	`==================================`
`3`	`3`
`4`	`4`	`.. currentmodule:: netmap.downstream.gene_clustering`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-netmap.masking.external`
	`1`	`+netmap.masking.external`
`2`	`2`	`=======================`
`3`	`3`
`4`	`4`	`.. currentmodule:: netmap.masking.external`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-netmap.masking.internal`
	`1`	`+netmap.masking.internal`
`2`	`2`	`=======================`
`3`	`3`
`4`	`4`	`.. currentmodule:: netmap.masking.internal`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-netmap.model.nbautoencoder`
	`1`	`+netmap.model.nbautoencoder`
`2`	`2`	`==========================`
`3`	`3`
`4`	`4`	`.. currentmodule:: netmap.model.nbautoencoder`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-netmap.model.standardautoencoder`
	`1`	`+netmap.model.standardautoencoder`
`2`	`2`	`================================`
`3`	`3`
`4`	`4`	`.. currentmodule:: netmap.model.standardautoencoder`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-netmap.model.train\_model`
	`1`	`+netmap.model.train\_model`
`2`	`2`	`=========================`
`3`	`3`
`4`	`4`	`.. currentmodule:: netmap.model.train_model`