### Install MetaTiME and Dependencies

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Installs necessary libraries including scanpy, metatime, anndata, adjustText, leidenalg, and harmonypy. It also downloads and displays a logo for testing.

```python
##Calling matplotlib first help avoid error in colab when plotting
import matplotlib
import matplotlib.pyplot as plt
!wget -q https://www.dropbox.com/s/gnmgfxa85basvwq/logo.png
img = matplotlib.image.imread('./logo.png', 0)

logo = plt.imshow( img ) # for test the colab matplotlib. a logo shall be plotted:)
_=plt.axis('off')

## install
!pip install scanpy 
!pip install metatime
!pip install anndata
!pip install adjustText
!pip install leidenalg
!pip install harmonypy
```

--------------------------------

### Complete Workflow Example

Source: https://context7.com/yi-zhang/metatime/llms.txt

An end-to-end analysis workflow from raw data to annotated cell states and differential analysis using MetaTiME and scanpy.

```python
from metatime import loaddata, mecs, mecmapper, annotator, plmapper, dmec, config
import scanpy as sc

# 1. Load and preprocess data
ada = loaddata.load('tumor_scRNA.h5ad')
ada = loaddata.adatapp(adata, mode='pp')
ada = loaddata.batchharmonize(adata, batchcols=['patient'])

# 2. Remove malignant cells (keep TME cells)
ada = adata[adata.obs['isTME']]

# 3. Load MetaTiME model
mecmodel = mecs.MetatimeMecs.load_mec_precomputed()
mectable = mecs.load_mecname(mode='table')
mecnamedict = mecs.getmecnamedict_ct(mectable)

# 4. Project and annotate
ada = annotator.overcluster(adata)
pdata = mecmapper.projectMecAnn(adata, mecmodel.mec_score)
projmat, mecscores = annotator.pdataToTable(pdata, mectable)
projmat, gpred, gpreddict = annotator.annotator(projmat, mecnamedict)
ada = annotator.saveToAdata(adata, projmat)
pdata = annotator.saveToPdata(pdata, adata, projmat)

# 5. Visualize
ada.obs['MetaTiME'] = adata.obs['MetaTiME_overcluster'].str.split(': ').str.get(1)
fig, ax = plmapper.plot_annotation_on_data(adata, COL='MetaTiME')

# 6. Differential analysis
cells_pre = adata[adata.obs['treatment'] == 'pre'].obs.index
cells_post = adata[adata.obs['treatment'] == 'post'].obs.index
mec_enriched = dmec.enrich_mec(pdata, 'MetaTiME', mecnamedict)
diffmec, diffmecsig, _ = dmec.dmec(
    adata, pdata, cells_pre, cells_post,
    'MetaTiME', mec_enriched, mecnamedict
)
fig, ax = dmec.plot_topdiff(diffmec)
```

--------------------------------

### Import Libraries and Load Data

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Imports essential libraries for data analysis and MetaTiME functionalities. Includes setup for local development paths and loading an AnnData object from a specified file.

```python
import sys
import os
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
plt.rcParams['figure.dpi'] = 200
import seaborn as sns
import scanpy as sc


import importlib as imp
import metatime
import matplotlib
import matplotlib.pyplot as plt
"""
## For local testing in dev
METATIME_DIR = '../../metatime/'
if METATIME_DIR not in sys.path:
    sys.path.append(METATIME_DIR)
file = '../notebooks_dev/BCC_GSE123813_aPD1_with_metainfo.h5ad'
"""

from metatime import config
from metatime import loaddata
from metatime import mecmapper
from metatime import mecs
from metatime import annotator
from metatime import plmapper
from metatime import dmec
import matplotlib
```

```python
file = 'testdata.h5ad' 
```

```python
# file = '../notebooks_dev/BCC_GSE123813_aPD1_with_metainfo.h5ad' # Yost et al. 2019 Nat Med.
```

```python
adata = loaddata.load(file = file)
```

--------------------------------

### Get DataFrame of Significant Differential Signatures

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Extracts a DataFrame containing significant differential signatures and their associated statistics from the differential analysis results.

```python
diff, diff_sig = dmec.topdiff_df(diffmec)

```

--------------------------------

### metatime.plmapper.MidpointNormalize

Source: https://github.com/yi-zhang/metatime/blob/main/docs/source/metatime.md

Normalizes the colorbar separately for above-midpoint and below-midpoint values. This is useful for visualizing signature continua with a diverging colorbar. It is borrowed from Chris Wills' matplotlib examples.

```APIDOC
## POST /api/metatime/plmapper/MidpointNormalize

### Description
Normalise the colorbar separately for above-midpoint and below-midpoint. Useful for visualizing the signature continuum with diverging colorbar.

### Method
POST

### Endpoint
/api/metatime/plmapper/MidpointNormalize

### Parameters
#### Request Body
- **vmin** (float) - Optional - Minimum value for normalization.
- **vmax** (float) - Optional - Maximum value for normalization.
- **midpoint** (float) - Optional - The midpoint value for normalization. Defaults to 0.
- **clip** (bool) - Optional - Whether to clip values outside the vmin/vmax range.

### Response
#### Success Response (200)
- **matplotlib.colors.Normalize** - A normalization object suitable for use with matplotlib color mapping.

### Request Example
```json
{
  "vmin": null,
  "vmax": null,
  "midpoint": 0,
  "clip": false
}
```

### Response Example
```json
{
  "norm": "<matplotlib.colors.Normalize object>"
}
```
```

--------------------------------

### Download Sample Data

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Downloads a sample dataset (BCC_GSE123813_aPD1_with_metainfo.h5ad) for analysis.

```python
#!wget -O testdata.h5ad https://www.dropbox.com/s/0sj6gtppsfr2ouo/NSCLC_GSE117570_res.pp.h5ad?dl=0

!wget -O testdata.h5ad https://www.dropbox.com/s/f791mv3tnhs9fii/BCC_GSE123813_aPD1_with_metainfo.h5ad
```

--------------------------------

### Configure differential signature testing

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Sets up the column and condition variables required for cluster-wise differential signature testing.

```python
condcol = 'treatment' # the column in adata.obs to mark the condition
cond1 = ['pre'] # Condition 1 in adata.obs[ condcol ], 
cond2 = ['post'] # Condition 2 in adata.obs[ condcol ], 
clustercol = 'MetaTiME' # MetaTiME annotated cluster labels 
```

--------------------------------

### Load Pre-trained MetaTiME Model and Annotations

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Loads the pre-trained MetaTiME MetaComponents (MeCs) and their functional annotations. This involves loading the MeC model and creating a dictionary for MeC names.

```python
# Load the pre-trained MeCs
mecmodel = mecs.MetatimeMecs.load_mec_precomputed()

# Load functional annotation for MetaTiME-TME
mectable = mecs.load_mecname( mecDIR = config.SCMECDIR, mode ='table' )
mecnamedict = mecs.getmecnamedict_ct(mectable) 

```

--------------------------------

### Preprocess Raw Data

Source: https://context7.com/yi-zhang/metatime/llms.txt

Execute a full preprocessing pipeline including filtering, normalization, and dimensionality reduction.

```python
from metatime import loaddata

# Full preprocessing pipeline for raw count data
adata = loaddata.adatapp(
    adata,
    mode='pp',              # Full preprocessing
    MAX_MITO_PERCENT=5,     # Filter cells with >5% mitochondrial genes
    MINGENES=500,           # Minimum genes per cell
    MINCOUNTS=1000,         # Minimum counts per cell
    MINCELLS=5,             # Minimum cells per gene
    random_state=42
)

# Output:
# [Log] adata.X is count. Copy to .layers["counts"]. Pre-processing...
# [Log] filtering
# [Log] Human MT-percentage
```

--------------------------------

### Load Pretrained MeC Model

Source: https://context7.com/yi-zhang/metatime/llms.txt

Load pretrained meta-components and functional annotations for tumor microenvironment analysis.

```python
from metatime import mecs
from metatime import config

# Load pretrained MeC model (gene weights)
mecmodel = mecs.MetatimeMecs.load_mec_precomputed()

# Access model properties
print(f"Number of MeCs: {mecmodel.nmecs}")
print(f"Number of genes: {len(mecmodel.feature)}")

# Load functional annotations
mectable = mecs.load_mecname(mecDIR=config.SCMECDIR, mode='table')
mecnamedict = mecs.getmecnamedict_ct(mectable)

# Example mecnamedict entries:
# {'MeC_3': 'DC: pDC',
#  'MeC_4': 'B: Plasma',
#  'MeC_8': 'T: NK-cytotoxic',
#  'MeC_17': 'M: Monocyte-CD14',
#  ...}
```

--------------------------------

### Plot signature continuum with MetaTiME

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Generates a UMAP projection plot for functional MeCs.

```python
fig=plmapper.plot_umap_proj_pdata( pdata, mecnamedict , figfile =None)
```

--------------------------------

### metatime.testdata module

Source: https://github.com/yi-zhang/metatime/blob/main/docs/source/metatime.md

Information about the metatime.testdata module.

```APIDOC
## metatime.testdata module

### Description
Module contents for testdata.
```

--------------------------------

### metatime.loaddata Functions

Source: https://github.com/yi-zhang/metatime/blob/main/docs/source/metatime.md

Functions for loading, preprocessing, and batch harmonizing scRNA data.

```APIDOC
## metatime.loaddata.adatapp

### Description
Performs pre-processing on a scanpy scRNA object.

### Parameters
- **adata_input** (AnnData) - Required - Scanpy scRNA object.
- **mode** (str) - Optional - Choose from ['pp', 'umap'].
- **random_state** (int) - Optional - UMAP random state.
- **MAX_MITO_PERCENT** (int) - Optional - Max mitochondrial percentage.
- **MINGENES** (int) - Optional - Minimum genes per cell.
- **MINCOUNTS** (int) - Optional - Minimum counts per cell.
- **MINCELLS** (int) - Optional - Minimum cells per gene.

### Response
- **adata** (AnnData) - Processed scanpy object.

---

## metatime.loaddata.load

### Description
Reads an expression matrix table file as a scanpy object.

### Parameters
- **file** (str) - Required - File path for the expression file.
- **preprocessing** (bool) - Optional - Whether to do preprocessing.
- **delimiter** (str) - Optional - Delimiter of the expression matrix table.

### Response
- **adata** (AnnData) - Loaded scRNA data in scanpy object.
```

--------------------------------

### Plot All MeC Signatures

Source: https://context7.com/yi-zhang/metatime/llms.txt

Generate a comprehensive panel showing all functional MeC signatures on UMAP.

```python
from metatime import plmapper

# Plot all MeC signatures in a grid
fig = plmapper.plot_umap_proj_pdata(
    pdata,
    mecnamedict,
    use_MeC_name=True,
    N_col=4,                  # Number of columns in grid
    figfile='all_mec_signatures.png'
)
```

--------------------------------

### Display Simplified MeC Naming Dictionary

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Prints the simplified dictionary mapping MeC identifiers to their descriptive names. This is useful for understanding the meaning of each annotated cell state.

```python
mecnamedict_simp
```

--------------------------------

### Load scRNA data

Source: https://github.com/yi-zhang/metatime/blob/main/docs/source/metatime.md

Read an expression matrix file into a scanpy object.

```pycon
>>> adata = load( file, preprocessing=False )
```

--------------------------------

### metatime.plmapper.plot_umap_mecproj_2condition

Source: https://github.com/yi-zhang/metatime/blob/main/docs/source/metatime.md

Plots a comparison panel for projected MeC signatures across two conditions. This is a beta version function.

```APIDOC
## POST /api/metatime/plmapper/plot_umap_mecproj_2condition

### Description
Plotting comparison panel for pdata format, beta version.

### Method
POST

### Endpoint
/api/metatime/plmapper/plot_umap_mecproj_2condition

### Parameters
#### Request Body
- **pdata** (anndata.AnnData) - Required - Scanpy object with projection score matrix in pdata.X.
- **meccol** (str) - Required - MeC id (column name in pdata.X).
- **mecnamedict** (dict) - Required - Dictionary mapping MeC ids to their names.
- **cellscond1** (list) - Required - List of cell indices for condition 1.
- **cellscond2** (list) - Required - List of cell indices for condition 2.
- **use_MeC_name** (bool) - Optional - Whether to use MeC names in the plot. Default is True.
- **figfile** (str) - Optional - File path to save the figure. Default is '../tmp.png'.

### Response
#### Success Response (200)
- **matplotlib.figure.Figure** - A matplotlib figure object with the comparison panel plotted.

### Request Example
```json
{
  "pdata": "<anndata.AnnData object>",
  "meccol": "score_1",
  "mecnamedict": {"score_1": "MeC Name 1"},
  "cellscond1": ["cell_1", "cell_2"],
  "cellscond2": ["cell_3", "cell_4"],
  "use_MeC_name": true,
  "figfile": "../tmp.png"
}
```

### Response Example
```json
{
  "figure": "<matplotlib.figure.Figure object>"
}
```
```

--------------------------------

### Annotate Cell States and Save to Scanpy Objects

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Computes per-cell projection scores, annotates cell states, and saves the results to both the main adata object and a smaller pdata object. Overlapping columns in projmat and adata.obs will be overwritten.

```python
projmat, gpred, gpreddict = annotator.annotator( projmat,  mecnamedict, gcol = 'overcluster')

adata = annotator.saveToAdata( adata, projmat )
pdata = annotator.saveToPdata( pdata, adata, projmat )
```

--------------------------------

### Plot Differential Signatures

Source: https://context7.com/yi-zhang/metatime/llms.txt

Create volcano-style plots showing differential signatures between conditions.

```python
from metatime import dmec
import seaborn as sns

# Set plot style
sns.set_theme(style='white')

# Plot differential signatures
fig, ax = dmec.plot_topdiff(
    diffmec,
    fontsize=6,
    cut_logppos=1.3,      # -log10(p) cutoff (p=0.05)
    cut_effectpos=1,      # Effect size cutoff (1 std)
    cut_effectneg=-1,
    figsize=(9, 6)
)

fig.savefig('differential_signatures.png', dpi=300)
```

--------------------------------

### Plot Single MeC Signature

Source: https://context7.com/yi-zhang/metatime/llms.txt

Visualize the signature continuum for a specific meta-component on UMAP.

```python
from metatime import plmapper

# Plot signature continuum for a single MeC
fig = plmapper.plot_umap_mec(
    pdata,
    meccol='MeC_3',           # MeC ID to plot
    mecnamedict=mecnamedict,
    use_MeC_name=True,        # Show functional name in title
    figsize=(3, 3),
    figfile='pDC_signature.png'
)
```

--------------------------------

### Export cell counts to file

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Saves the generated cell count table to a tab-separated text file.

```python
cellcts.to_csv('./cell_counts.txt',sep='	')
```

--------------------------------

### Annotate Projection Data

Source: https://context7.com/yi-zhang/metatime/llms.txt

Convert projection data to table format, run the automatic annotator, and save results back to AnnData objects.

```python
projmat, mecscores = annotator.pdataToTable(
    pdata,
    mectable,
    gcol='overcluster'
)

# Run automatic annotator
projmat, gpred, gpreddict = annotator.annotator(
    projmat,
    mecnamedict,
    gcol='overcluster'
)

# Save annotations back to AnnData objects
adata = annotator.saveToAdata(adata, projmat)
pdata = annotator.saveToPdata(pdata, adata, projmat)

# New column 'MetaTiME_overcluster' added with annotations like:
# 'T: CD8T-GZMK-CCL5', 'M: Macrophage-C1Q', 'B: B', etc.

# Simplify cell state names for visualization
adata.obs['MetaTiME'] = adata.obs['MetaTiME_overcluster'].str.split(': ').str.get(1)
```

--------------------------------

### metatime.mecmapper.scale

Source: https://github.com/yi-zhang/metatime/blob/main/docs/source/metatime.md

Standardizes and scales features in a DataFrame.

```APIDOC
## POST /api/metatime/mecmapper/scale

### Description
Standardize scaling feature.

### Method
POST

### Endpoint
/api/metatime/mecmapper/scale

### Parameters
#### Request Body
- **df** (pd.DataFrame) - Required - DataFrame to be scaled.

### Response
#### Success Response (200)
- **pd.DataFrame** - Scaled DataFrame.

### Request Example
```json
{
  "df": "<pd.DataFrame object>"
}
```

### Response Example
```json
{
  "scaled_df": "<pd.DataFrame object>"
}
```
```

--------------------------------

### metatime.mecmapper Functions

Source: https://github.com/yi-zhang/metatime/blob/main/docs/source/metatime.md

Functions for extracting expression matrices and projecting them onto gene signatures.

```APIDOC
## metatime.mecmapper.annToDataFrame

### Description
Extracts an expression matrix from a scanpy object.

### Parameters
- **adata_input** (AnnData) - Required - Input scanpy object.
- **genescaling** (bool) - Optional - Whether to z-scale extracted feature matrix.
- **layer** (str) - Optional - Layer of expression to extract.

### Response
- **pd.DataFrame** - Extracted expression matrix.

---

## metatime.mecmapper.projectMec

### Description
Projects expression data onto MEC signatures.

### Parameters
- **expr** (pd.DataFrame) - Required - Expression matrix, cell by gene.
- **mec** (pd.DataFrame) - Required - MEC table.
- **glstcol** (str) - Optional - Column name for gene list in format 1.
```

--------------------------------

### Pre-process scRNA data

Source: https://github.com/yi-zhang/metatime/blob/main/docs/source/metatime.md

Perform standard preprocessing on an AnnData object.

```pycon
>>> adata = adatapp(adata )
```

--------------------------------

### Count cells by condition and cluster

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Calculates cell counts grouped by treatment, cluster, and patient columns.

```python
condcol = 'treatment' 
clustercol = 'MetaTiME' 
samplecol = 'patient'

cellcts = dmec.count_cell_condition( adata.obs, countbycols = [condcol, clustercol, samplecol] )
#cellcts.to_csv('./cell_counts.txt',sep='	')
cellcts
```

--------------------------------

### Prepare projection data for plotting

Source: https://github.com/yi-zhang/metatime/blob/main/docs/source/metatime.md

Extracts projection data from an AnnData object for custom plotting workflows.

```python
Xproj = pdata.to_df()
use_MeC_name = True
mec_col =’score_1’
mec_name = mecnamedict[ mec_col ]
condcol = ‘response’
```

--------------------------------

### Print Cell Counts for Conditions

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Prints the number of cells belonging to specified conditions. Ensure 'condcol', 'cond1', and 'cond2' are defined prior to execution.

```python
print(f'Compare cells based on {condcol} with conditions {cond1} and {cond2}')
print(f'Cells in Condition {cond1} : {len(allcellscond1)}')
print(f'Cells in Condition {cond2} : {len(allcellscond2)}')
```

--------------------------------

### Plot Cell State Annotations

Source: https://context7.com/yi-zhang/metatime/llms.txt

Visualize annotated cell states on UMAP with non-overlapping labels.

```python
from metatime import plmapper

# Plot annotated cell states on UMAP
fig, ax = plmapper.plot_annotation_on_data(
    adata,
    COL='MetaTiME',       # Column with cell state labels
    title='MetaTiME Cell States',
    fontsize=7,
    MIN_CELL=5            # Minimum cells to show label
)

# Save figure
fig.savefig('cell_states_umap.png', dpi=300)
```

--------------------------------

### metatime.plmapper.plot_umap_proj_pdata

Source: https://github.com/yi-zhang/metatime/blob/main/docs/source/metatime.md

Saves all projection images in one large figure. Input is pdata format. Deprecated.

```APIDOC
## metatime.plmapper.plot_umap_proj_pdata

### Description
Save all projection images in one large figure. input is pdata format. Deprecated

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **pdata** (object) - Input data in pdata format.
- **mecnamedict** (dict) - Dictionary mapping MeC names.
- **use_MeC_name** (bool) - Whether to use MeC names. Defaults to True.
- **figfile** (str, optional) - File path to save the figure.
- **N_col** (int) - Number of columns in the figure. Defaults to 4.

### Return type
None
```

--------------------------------

### Display Per-Cell Projection Scores

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Displays the resulting table of per-cell projection scores. This output shows scores for different cell types across various categories.

```text
Result:
                                       0: Pan_Interferon-response  \
bcc.su001.pre.tcell_AAACCTGCAGGGATTG                    -0.819890   
bcc.su001.pre.tcell_AAACGGGCATAGACTC                     0.497730   
bcc.su001.pre.tcell_AAACGGGTCATACGGT                    -0.853597   
bcc.su001.pre.tcell_AAAGATGAGACAGGCT                     1.643644   
bcc.su001.pre.tcell_AAAGATGTCTGAGTGT                    -0.904096   
...                                                           ...   
bcc.su012.post.tcell_TTTGCGCGTCTTTCAT                   -0.655006   
bcc.su012.post.tcell_TTTGGTTCAGCCAGAA                   -1.002944   
bcc.su012.post.tcell_TTTGTCAAGCACCGTC                   -0.705487   
bcc.su012.post.tcell_TTTGTCAAGTGAACGC                    0.205688   
bcc.su012.post.tcell_TTTGTCAGTCCCTTGT                   -0.059757   

                                       1: Pan_Proliferation-S  \
bcc.su001.pre.tcell_AAACCTGCAGGGATTG                -0.688164   
bcc.su001.pre.tcell_AAACGGGCATAGACTC                -0.781702   
bcc.su001.pre.tcell_AAACGGGTCATACGGT                 0.389129   
bcc.su001.pre.tcell_AAAGATGAGACAGGCT                -0.217423   
bcc.su001.pre.tcell_AAAGATGTCTGAGTGT                -0.855004   
...                                                       ...   
bcc.su012.post.tcell_TTTGCGCGTCTTTCAT               -0.323290   
bcc.su012.post.tcell_TTTGGTTCAGCCAGAA               -0.177266   
bcc.su012.post.tcell_TTTGTCAAGCACCGTC               -0.384236   
bcc.su012.post.tcell_TTTGTCAAGTGAACGC               -0.372909   
bcc.su012.post.tcell_TTTGTCAGTCCCTTGT                0.314007   

                                       2: Pan_Heat-stress  3: DC_pDC  \
bcc.su001.pre.tcell_AAACCTGCAGGGATTG            -1.293394  -0.623175   
bcc.su001.pre.tcell_AAACGGGCATAGACTC            -1.236870  -0.225077   
bcc.su001.pre.tcell_AAACGGGTCATACGGT             2.834898  -0.235956   
bcc.su001.pre.tcell_AAAGATGAGACAGGCT            -0.643116   0.088754   
bcc.su001.pre.tcell_AAAGATGTCTGAGTGT            -1.025405  -0.417323   
...                                                   ...        ...   
bcc.su012.post.tcell_TTTGCGCGTCTTTCAT            1.357172  -0.252120   
bcc.su012.post.tcell_TTTGGTTCAGCCAGAA            1.441417  -0.175024   
bcc.su012.post.tcell_TTTGTCAAGCACCGTC            1.495082  -0.411420   
bcc.su012.post.tcell_TTTGTCAAGTGAACGC            1.382011   0.256174   
bcc.su012.post.tcell_TTTGTCAGTCCCTTGT            1.000176  -0.132242   

                                       4: B_Plasma  5: Pan_Proliferation-G2-M  \
bcc.su001.pre.tcell_AAACCTGCAGGGATTG     -0.619621                  -0.014213   
bcc.su001.pre.tcell_AAACGGGCATAGACTC     -0.407063                  -0.196667   
bcc.su001.pre.tcell_AAACGGGTCATACGGT      0.469343                   0.946867   
bcc.su001.pre.tcell_AAAGATGAGACAGGCT     -0.523546                  -1.255705   
bcc.su001.pre.tcell_AAAGATGTCTGAGTGT     -0.265433                  -0.517993   
...                                            ...                        ...   
bcc.su012.post.tcell_TTTGCGCGTCTTTCAT    -0.477362                  -0.562883   
bcc.su012.post.tcell_TTTGGTTCAGCCAGAA    -0.643992                  -1.178595   
bcc.su012.post.tcell_TTTGTCAAGCACCGTC    -0.401349                  -0.957136   
bcc.su012.post.tcell_TTTGTCAAGTGAACGC    -0.391342                   0.236742   
bcc.su012.post.tcell_TTTGTCAGTCCCTTGT     0.371538                  -0.351378   

                                       6: DC_cDC2-MHCII  \
bcc.su001.pre.tcell_AAACCTGCAGGGATTG          -0.421470   
bcc.su001.pre.tcell_AAACGGGCATAGACTC          -0.708806   
bcc.su001.pre.tcell_AAACGGGTCATACGGT          -0.673814   
bcc.su001.pre.tcell_AAAGATGAGACAGGCT          -0.849190   
bcc.su001.pre.tcell_AAAGATGTCTGAGTGT          -0.371883   
...                                                 ...   
bcc.su012.post.tcell_TTTGCGCGTCTTTCAT         -0.469015   
bcc.su012.post.tcell_TTTGGTTCAGCCAGAA         -1.009185   
bcc.su012.post.tcell_TTTGTCAAGCACCGTC         -1.487738   
bcc.su012.post.tcell_TTTGTCAAGTGAACGC         -1.236226   
bcc.su012.post.tcell_TTTGTCAGTCCCTTGT         -0.189296   

                                       7: T_Treg-T-co-signaling  \
bcc.su001.pre.tcell_AAACCTGCAGGGATTG                  -0.575049   
bcc.su001.pre.tcell_AAACGGGCATAGACTC                   0.148677   
bcc.su001.pre.tcell_AAACGGGTCATACGGT                   0.078563   
bcc.su001.pre.tcell_AAAGATGAGACAGGCT                   0.658166   
bcc.su001.pre.tcell_AAAGATGTCTGAGTGT                  -0.238967   
...                                                         ...   
bcc.su012.post.tcell_TTTGCGCGTCTTTCAT                 -0.594926   
bcc.su012.post.tcell_TTTGGTTCAGCCAGAA                  0.391318   

```

--------------------------------

### Simplify Cell State Names

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Simplifies the cell state names by extracting the descriptive part after ': ' and updates both adata and pdata objects with the simplified names. A simplified naming dictionary is also created.

```python
adata.obs['MetaTiME'] = adata.obs['MetaTiME_overcluster'].str.split(': ').str.get(1)
pdata.obs['MetaTiME'] = pdata.obs['MetaTiME_overcluster'].str.split(': ').str.get(1)
mecnamedict_simp = mecnamedict.copy()
_=[mecnamedict_simp.update({t: mecnamedict[t].split(': ')[1]}) for t in mecnamedict.keys()]
```

--------------------------------

### Convert Per-Cell Scores to Table

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Use this function to convert per-cell projection data into a table format for easier analysis. Requires 'annotator' object, 'pdata', and 'mectable'.

```python
projmat, mecscores = annotator.pdataToTable(pdata, mectable, gcol = 'overcluster')
```

--------------------------------

### Plot UMAP for Two Conditions

Source: https://github.com/yi-zhang/metatime/blob/main/docs/source/metatime.md

Visualizes UMAP projections colored by a specific MeC score, differentiating between two defined cell conditions. Requires pre-defined cell lists for each condition.

```python
allcellscond1= adata[adata.obs[ condcol ].isin([‘Non-responder’]), ].obs.index
allcellscond2= adata[adata.obs[ condcol ].isin([‘Responder’]), ].obs.index

plmapper.plot_umap_mecproj_2condition( pdata, meccol = ‘score_0’, mecnamedict = mecnamedict,
: cellscond1 = allcellscond1, cellscond2 = allcellscond2,
  use_MeC_name = True, )
```

--------------------------------

### Save Significant Results

Source: https://context7.com/yi-zhang/metatime/llms.txt

Saves the differential signatures to a tab-separated text file. The output includes columns like -logp, effect, meanb, and meana.

```python
diff_sig.to_csv('differential_signatures_significant.txt', sep='\t')
```

--------------------------------

### metatime.mecmapper.projectMecAnn

Source: https://github.com/yi-zhang/metatime/blob/main/docs/source/metatime.md

Projects single-cell expression data onto MeCs (Metabolic Control Elements). This function can scale gene expression and projected scores, and offers options to either append results to the original AnnData object or return a new AnnData object with only the projected values.

```APIDOC
## POST /api/metatime/mecmapper/projectMecAnn

### Description
Projects single cell expression in AnnData to MeCs.

### Method
POST

### Endpoint
/api/metatime/mecmapper/projectMecAnn

### Parameters
#### Request Body
- **adata_input** (anndata.AnnData) - Required - Input scanpy object for gene expression
- **mec** (pd.DataFrame) - Required - mec table with one column, two types of format both accepted
  format 1, each row is a mec with genes , comma seperated.
  format 2, each row is a genes, each column is a mec, value is float.
- **genescaling** (bool) - Optional - Whether to scale expression on gene level. Recommended to be False.
- **sigscaling** (bool) - Optional - Whether to scale projected scores across cells. Recommended and default is True.
- **addon** (bool) - Optional - Whether to keep the original adata and append the signatures in obs, or return an independent anndata (pdata) with only projected values (which saves memory).
- **layer** (str) - Optional - Layer of expression to extract from adata_input. Default is 'norm_data'.
- **glstcol** (str) - Optional - Used only when mec is the list format format 1, and glstcol is the column name to record comma separated gene list for each mec. Default is 'TopGene20'.

### Response
#### Success Response (200)
- **anndata.AnnData** - If addon is False, return pdata where values are MeC-projected values. If addon is True, return adata where values are same as in adata_input, but with extra obs columns.

### Request Example
```json
{
  "adata_input": "<anndata.AnnData object>",
  "mec": "<pd.DataFrame object>",
  "genescaling": false,
  "sigscaling": true,
  "addon": false,
  "layer": "norm_data",
  "glstcol": "TopGene20"
}
```

### Response Example
```json
{
  "pdata": "<anndata.AnnData object>"
}
```
```

--------------------------------

### Differential Signature Analysis

Source: https://context7.com/yi-zhang/metatime/llms.txt

Compare MeC signature scores between two conditions cluster-wise using statistical tests.

```python
from metatime import dmec

# Define conditions
condcol = 'treatment'
cond1 = ['pre']
cond2 = ['post']
clustercol = 'MetaTiME'

# Get cell barcodes for each condition
allcellscond1 = adata[adata.obs[condcol].isin(cond1)].obs.index
allcellscond2 = adata[adata.obs[condcol].isin(cond2)].obs.index

# Identify enriched MeCs per cluster
mec_enriched = dmec.enrich_mec(
    adata=pdata,
    labelcol=clustercol,
    mecnamedict=mecnamedict
)

# Run differential analysis
diffmec, diffmecsig, diffmec_full = dmec.dmec(
    adata,
    pdata,
    allcellscond1,
    allcellscond2,
    clustercol,
    mec_enriched,
    mecnamedict,
    test_clusters='all',      # Test all clusters
    test_method='ttest'       # or 'wilcoxon'
)
```

--------------------------------

### Project Cells onto MeC Space

Source: https://context7.com/yi-zhang/metatime/llms.txt

Calculate per-cell signature scores by projecting expression data onto the meta-component space.

```python
from metatime import mecmapper

# Project cells onto MeC space (returns new AnnData with MeC scores)
pdata = mecmapper.projectMecAnn(
    adata,
    mecmodel.mec_score,
    sigscaling=True,       # Z-scale scores across cells
    genescaling=False,     # Don't scale genes (recommended)
    addon=False,           # Return separate pdata object
    layer='norm_data'      # Expression layer to use
)

# pdata now contains:
# - pdata.X: cell x MeC projection scores
# - pdata.obs: cell metadata from original adata

# Alternative: Add scores to existing adata.obs
adata_with_scores = mecmapper.projectMecAnn(
    adata,
    mecmodel.mec_score,
    addon=True  # Append to adata.obs instead
)
```

--------------------------------

### Enrich MeC Signatures in Clusters

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Enriches for Methylation Capture (MeC) signatures within cell clusters. Requires 'pdata', 'clustercol', and 'mecnamedict' to be defined.

```python
mec_enriched = dmec.enrich_mec( 
    adata=pdata, labelcol =clustercol, mecnamedict=mecnamedict_simp)

```

--------------------------------

### metatime.mecmapper.projectModuleAnn_aucell

Source: https://github.com/yi-zhang/metatime/blob/main/docs/source/metatime.md

Projects single-cell RNA data using top genes from MeCs and AUCell. This function is an alternative to `projectMecAnn` and requires the module to be in list format.

```APIDOC
## POST /api/metatime/mecmapper/projectModuleAnn_aucell

### Description
Projects scRNA data using top genes from MeCs and AUCell. Module has to be list mode.

### Method
POST

### Endpoint
/api/metatime/mecmapper/projectModuleAnn_aucell

### Parameters
#### Request Body
- **adata** (anndata.AnnData) - Required - Input scanpy object for gene expression
- **module** (pd.DataFrame) - Required - mec table with one column, two types of format accepted
  format 1, each row is a mec with genes , comma seperated.
- **glstcol** (str) - Optional - Used only when mec is the list format format 1, and glstcol is the column name to record comma separated gene list for each mec. Default is 'TopGene20'.

### Response
#### Success Response (200)
- **anndata.AnnData** - adata with AUCell score stored in extra columns starting with ‘score_sig_’ in adata.obs

### Request Example
```json
{
  "adata": "<anndata.AnnData object>",
  "module": "<pd.DataFrame object>",
  "glstcol": "TopGene20"
}
```

### Response Example
```json
{
  "adata": "<anndata.AnnData object>"
}
```
```

--------------------------------

### Differential MeC Analysis Between Conditions

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Performs differential analysis of MeC signatures between two cell conditions. Requires 'adata', 'pdata', cell lists, cluster column, enriched MeC data, and MeC name dictionary. Supports 'ttest' and other methods.

```python
diffmec, diffmecsig, diffmec_full = dmec.dmec(adata, pdata, allcellscond1, allcellscond2, clustercol, mec_enriched, mecnamedict_simp,
                                              test_clusters='all', test_method = 'ttest' )

```

--------------------------------

### Count Cells by Condition

Source: https://context7.com/yi-zhang/metatime/llms.txt

Count cells across conditions, clusters, and samples for downstream statistical analysis.

```python
from metatime import dmec

# Define grouping columns
condcol = 'treatment'      # e.g., 'pre', 'post'
clustercol = 'MetaTiME'    # Cell state annotations
samplecol = 'patient'      # Sample/patient IDs

# Get cell counts
cellcts = dmec.count_cell_condition(
    adata.obs,
    countbycols=[condcol, clustercol, samplecol]
)

# Save to file
cellcts.to_csv('cell_counts.txt', sep='\t')
```

--------------------------------

### metatime.plmapper.plot_umap_proj

Source: https://github.com/yi-zhang/metatime/blob/main/docs/source/metatime.md

Plots the signature continuum score for each functional MeC in one large figure.

```APIDOC
## metatime.plmapper.plot_umap_proj

### Description
Plotting function: plot the signature continuum score for each funcntional MeC in one large figure.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **adata** (anndata.AnnData) - scanpy object for scRNA data. Two formats are accepted. 1. scanpy object with gene by cell expression, with extra mec columns in adata.obs. When adata.var_names has less than 100 features, go with format1. 2. scanpy object with only gene by MeC scores in adata.X. projected style format.
- **Xproj** (pd.DataFrame) - Dataframe for projected scores
- **mecnamedict** (dict) - Dictionary mapping MeC names.
- **use_MeC_name** (bool) - Whether to use MeC names. Defaults to True.
- **figfile** (str, optional) - File path to save the figure.
- **N_col** (int) - Number of columns in the figure. Defaults to 4.
- **N_MECS** (int) - Number of MeCS to consider. Defaults to 100.

### Return type
matplotlib figure
```

--------------------------------

### Display Top 3 Significant Differential Signatures

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Shows the first 3 rows of the DataFrame containing significant differential signatures. This provides a preview of the most impactful signatures.

```python
diff_sig[:3]

```

--------------------------------

### Project Cells onto MeC Space

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Projects each cell in the AnnData object onto the functional MetaComponent (MeC) space using the loaded MeC model.

```python
pdata = mecmapper.projectMecAnn(adata, mecmodel.mec_score)
```

--------------------------------

### Save Significant Differential Signatures to CSV

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Saves the DataFrame of significant differential signatures to a tab-separated text file named 'diff_sig_allcluster.txt'.

```python
diff_sig.to_csv('diff_sig_allcluster.txt',sep='	')

```

--------------------------------

### metatime.plmapper.gen_mpl_labels

Source: https://github.com/yi-zhang/metatime/blob/main/docs/source/metatime.md

Calculates the locations of cluster medians for plotting purposes. This function is borrowed from the scanpy GitHub forum.

```APIDOC
## POST /api/metatime/plmapper/gen_mpl_labels

### Description
Get locations of cluster median.

### Method
POST

### Endpoint
/api/metatime/plmapper/gen_mpl_labels

### Parameters
#### Request Body
- **adata** (anndata.AnnData) - Required - AnnData object containing the data.
- **groupby** (str) - Required - The key in adata.obs to group cells by.
- **exclude** (tuple) - Optional - Tuple of categories to exclude from labeling.
- **ax** (matplotlib.axes.Axes) - Optional - Matplotlib axes object to draw labels on.
- **adjust_kwargs** (dict) - Optional - Additional keyword arguments for adjusting label positions.
- **text_kwargs** (dict) - Optional - Additional keyword arguments for text formatting.

### Response
#### Success Response (200)
- **dict** - A dictionary containing the positions and text for the labels.

### Request Example
```json
{
  "adata": "<anndata.AnnData object>",
  "groupby": "leiden",
  "exclude": [],
  "ax": null,
  "adjust_kwargs": {},
  "text_kwargs": {}
}
```

### Response Example
```json
{
  "labels": {
    "cluster_0": {"x": 0.1, "y": 0.2, "text": "Cluster 0"}
  }
}
```
```

--------------------------------

### Load scRNA-seq Data

Source: https://context7.com/yi-zhang/metatime/llms.txt

Load data from h5ad or CSV files into an AnnData object. CSV loading supports optional preprocessing.

```python
from metatime import loaddata

# Load from h5ad file (scanpy format)
adata = loaddata.load(file='tumor_sample.h5ad')

# Load from CSV file with preprocessing
adata = loaddata.load(
    file='expression_matrix.csv',
    preprocessing=True,  # Apply standard preprocessing
    delimiter=','
)

# Output: Loaded tumor_sample.h5ad
```

--------------------------------

### Project MEC signatures

Source: https://github.com/yi-zhang/metatime/blob/main/docs/source/metatime.md

Calculate scores for cells based on MEC gene signatures.

```pycon
>>> scorepd = mecmapper.projectMec( df, mec )
```

--------------------------------

### Project single cell expression to MeCs

Source: https://github.com/yi-zhang/metatime/blob/main/docs/source/metatime.md

Projects gene expression data from an AnnData object to MeC signatures.

```pycon
>>> pdata = mecmapper.projectMecAnn(adata, mec_score_topg, sigscaling=True, genescaling=False, addon=False)
```

--------------------------------

### Plot Top Differential Signatures

Source: https://github.com/yi-zhang/metatime/blob/main/docs/notebooks/metatime_annotator.ipynb

Generates a dot plot visualizing the top differential MeC signatures between conditions. Uses seaborn for styling. The plot displays effect size against -log(p-value), with dot size indicating mean signature score.

```python
sns.set_theme(style='white')
fig_topdiff = dmec.plot_topdiff(diffmec, fontsize=6)

```

--------------------------------

### Plot annotated cells

Source: https://github.com/yi-zhang/metatime/blob/main/docs/source/metatime.md

Visualizes annotated cells with non-overlapping labels.

```pycon
>>> plmapper.plot_annotation_on_data(pdata, title = 'MetaTiME')
```

--------------------------------

### metatime.plmapper.plot_annotation_on_data

Source: https://github.com/yi-zhang/metatime/blob/main/docs/source/metatime.md

Plots annotated cells with non-overlapping fonts. This function calls `gen_mpl_labels` and may require resetting color information if `sdata.uns['MetaTiME_overcluster_colors']` exists.

```APIDOC
## POST /api/metatime/plmapper/plot_annotation_on_data

### Description
Plot annotated cells with non-overlapping fonts.

### Method
POST

### Endpoint
/api/metatime/plmapper/plot_annotation_on_data

### Parameters
#### Request Body
- **sdata** (anndata.AnnData) - Required - Scanpy object for single cell, or scanpy object with projected signature.
- **COL** (str) - Optional - Column of cluster assignment in sdata.obs. Default is 'MetaTiME'.
- **title** (str) - Optional - Title for the plot.
- **fontsize** (int) - Optional - Font size for labels. Default is 8.
- **MIN_CELL** (int) - Optional - Minimum number of cells to plot and mark. Default is 5.

### Response
#### Success Response (200)
- **matplotlib.figure.Figure** - A matplotlib figure object with the annotated cells plotted.

### Request Example
```json
{
  "sdata": "<anndata.AnnData object>",
  "COL": "MetaTiME",
  "title": "MetaTiME",
  "fontsize": 8,
  "MIN_CELL": 5
}
```

### Response Example
```json
{
  "figure": "<matplotlib.figure.Figure object>"
}
```
```