Update usage.rst

docs/source/usage.rst

@@ -6,28 +6,83 @@ Usage
 Installation
 ------------
 
-To use Lumache, first install it using pip:
+Symphonypy package might be installed via pip:
 
 .. code-block:: console
 
-   (.venv) $ pip install lumache
+   pip install symphonypy
 
-Creating recipes
-----------------
+Instructions
+------------
+
+Step 1: Reference building
+**************************
+
+.. code-block:: python
+
+   import scanpy as sc
+   import symphonypy as sp
+
+   # adata_ref is a filtered dataset that contains counts
+   sc.pp.normalize_total(adata_ref, target_sum=1e5)
+   sc.pp.log1p(adata_ref)
+   sc.pp.highly_variable_genes(
+       adata_ref,
+       batch_key=batch_key_ref,
+       n_top_genes=n_top_genes,
+   )
+   adata_ref.raw = adata_ref
+   adata_ref = adata_ref[:, adata_ref.var.highly_variable]
+   sc.pp.scale(adata_ref, max_value=10)
+   sc.pp.pca(adata_ref, n_comps=30, zero_center=False)
+   # zero_center=False for sc.pp.pca() is recommended, but even
+   # without it the results will be pretty same
+   
+   # You can skip Harmony if you have only one batch in reference
+   sp.pp.harmony_integrate(adata_ref, key=batch_key_ref)  
+   # -> adata_ref.obsm["X_pca_harmony"] <- Harmony adjusted "X_pca"
+   # -> adata_ref.uns["harmony"] <- Harmony object for Symphony
+
+Step 2: Query preprocessing and Symphony
+****************************************
+
+.. code-block:: python
+
+   # target_sum for normalize_total() should be the same as in reference
+   sc.pp.normalize_total(adata_query, target_sum=1e5)
+   sc.pp.log1p(adata_query)
+   
+   # Symphony
+   sp.tl.map_embedding(adata_query, adata_ref, key=batch_key_query)
+   # -> adata_query.obsm["X_pca_harmony"] <- Symphony adjusted query's PCA
+   sp.tl.per_cell_confidence(adata_query, adata_ref)
+   # -> adata_query.obs["symphony_per_cell_dist"] <- Symphony mapping score per cell
+   sp.tl.per_cluster_confidence(adata_query, adata_ref, query_clusters)
+   # -> adata_query.uns["symphony_per_cluster_dist"] <- Symphony mapping score per cluster
+
+Step 3: Label transfer
+**********************
+.. code-block:: python
+
+   sp.tl.transfer_labels_kNN(adata_query, adata_ref, labels)
+   # -> adata_query.obs[labels] <- transferred labels (via sklearn kNN)
+
+Step 4 (optional): Dimensionality reduction
+*******************************************
 
-To retrieve a list of random ingredients,
-you can use the ``lumache.get_random_ingredients()`` function:
+With UMAP:
 
-.. autofunction:: lumache.get_random_ingredients
+.. code-block:: python
 
-The ``kind`` parameter should be either ``"meat"``, ``"fish"``,
-or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
-will raise an exception.
+   sc.pp.neighbors(adata_ref, use_rep="X_pca_harmony")
+   sc.tl.umap(adata_ref)
+   sp.tl.ingest(adata_query, adata_ref)
+   # -> adata_query.obsm["X_umap"] <- mapped to the reference's UMAP coords
 
-.. autoexception:: lumache.InvalidKindError
+With t-SNE (``openTSNE`` should be installed, ``pip install openTSNE``):
 
-For example:
+.. code-block:: python
 
->>> import lumache
->>> lumache.get_random_ingredients()
-['shells', 'gorgonzola', 'parsley']
+   tSNE_model = sp.tl.tsne(adata_ref, use_rep="X_pca_harmony", return_model=True)
+   sp.tl.tsne(adata_query, use_rep="X_pca_harmony", use_model=tSNE_model)
+   # -> adata_query.obsm["X_tsne"] <- mapped to the reference's tSNE coords