### Installing mLLMCelltype for Development

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/python/README.md

Provides instructions for installing the mLLMCelltype library from source for development purposes. It involves cloning the repository and installing in editable mode.

```Bash
git clone https://github.com/cafferychen777/mLLMCelltype.git
cd mLLMCelltype/python
pip install -e .
```

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

### Installing mLLMCelltype Python package from GitHub

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/README.md

This command installs the Python version of the mLLMCelltype package directly from the main branch of the GitHub repository using pip. This is useful for getting the latest development version or contributing.

```Bash
pip install git+https://github.com/cafferychen777/mLLMCelltype.git
```

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

### Installing mLLMCelltype R package from GitHub

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/README.md

This R command installs the mLLMCelltype package directly from the GitHub repository. It requires the 'devtools' package to be installed. The 'subdir = "R"' argument ensures that only the R-specific part of the repository is installed.

```R
devtools::install_github("cafferychen777/mLLMCelltype", subdir = "R")
```

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

### Installing mLLMCelltype R Package from GitHub

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/README_JP.md

This snippet demonstrates how to install the R version of the mLLMCelltype package directly from its GitHub repository. This method is useful for getting the latest development version. It requires the 'devtools' package to be installed.

```R
# GitHubからインストール
devtools::install_github("cafferychen777/mLLMCelltype", subdir = "R")
```

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

### Accessing Example Data File Path in mLLMCelltype (R)

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/README.md

This R command shows how to find the file path to the example CSV marker gene data included within the installed mLLMCelltype package using the `system.file` function. This is useful for testing or understanding the required input format.

```R
system.file("extdata", "Cat_Heart_markers.csv", package = "mLLMCelltype")
```

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

### Installing mLLMCelltype via PyPI

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/python/README.md

Installs the mLLMCelltype library using pip from the Python Package Index (PyPI). This is the recommended method for typical users.

```Bash
pip install mllmcelltype
```

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

### Installing mLLMCelltype Python package from PyPI

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/README.md

This command installs the stable Python version of the mLLMCelltype package using pip, the standard package installer for Python. It fetches the package from the Python Package Index (PyPI).

```Bash
pip install mllmcelltype
```

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

### Installing mLLMCelltype in Python

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/README_KR.md

Installs the Python version of the mLLMCelltype package using pip, the standard Python package installer. This command downloads and installs the necessary files to make the 'mllmcelltype' library available for use in Python scripts.

```bash
pip install mllmcelltype
```

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

### Install and Load mLLMCelltype R Package

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/R/index.md

Installs the mLLMCelltype R package from GitHub using devtools and then loads it into the current R session. Requires the devtools package to be installed.

```R
# Install the package
devtools::install_github("cafferychen777/mLLMCelltype", subdir = "R")

# Load the package
library(mLLMCelltype)
```

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

### Installing mLLMCelltype in R

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/README_KR.md

Installs the R version of the mLLMCelltype package directly from the GitHub repository, specifically targeting the code within the 'R' subdirectory. This requires the 'devtools' package to be installed and loaded.

```R
# GitHub에서 설치
devtools::install_github("cafferychen777/mLLMCelltype", subdir = "R")
```

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

### Running Consensus Annotation Using Only OpenRouter Models

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/python/README.md

Illustrates how to initiate the `interactive_consensus_annotation` process using a list of models that are all accessed through the OpenRouter provider, demonstrating a multi-model consensus setup via OpenRouter.

```Python
from mllmcelltype import interactive_consensus_annotation, print_consensus_summary

# Run consensus annotation with only OpenRouter models
result = interactive_consensus_annotation(
    marker_genes=marker_genes,
    species='human',
    tissue='peripheral blood',
    models=[
        {"provider": "openrouter", "model": "openai/gpt-4o"},             # OpenRouter OpenAI (paid)
        {"provider": "openrouter", "model": "anthropic/claude-3-opus"},   # OpenRouter Anthropic (paid)
        {"provider": "openrouter", "model": "meta-llama/llama-3-70b-instruct"}  # OpenRouter Meta (paid)
    ],
    consensus_threshold=0.7,
    max_discussion_rounds=3,
    verbose=True
)

# Print consensus summary
print_consensus_summary(result)
```

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

### Accessing Example CSV Path - R

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/README_ES.md

This short snippet provides the R code necessary to retrieve the file path for the example CSV data ('Cat_Heart_markers.csv') included within the installed mLLMCelltype package. This is useful for testing the CSV parsing functionality.

```R
system.file("extdata", "Cat_Heart_markers.csv", package = "mLLMCelltype")
```

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

### Installing mLLMCelltype Python Package via pip

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/README_JP.md

This snippet shows the standard way to install the Python version of the mLLMCelltype package using the pip package manager. This is the recommended method for users to get the stable release.

```bash
pip install mllmcelltype
```

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

### Annotating Cell Types using CSV File Input - R

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/README_ES.md

This example demonstrates how to use mLLMCelltype in R by providing marker genes from a CSV file. It includes steps for package installation, loading, setting up cache/log directories, reading and parsing the CSV into the required list format, configuring API keys, and running the `interactive_consensus_annotation` function, finally saving and printing the results.

```R
# Instalar la versión más reciente de mLLMCelltype
devtools::install_github("cafferychen777/mLLMCelltype", subdir = "R", force = TRUE)

# Cargar paquetes necesarios
library(mLLMCelltype)

# Crear directorios de caché y registros
cache_dir <- "path/to/your/cache"
log_dir <- "path/to/your/logs"
dir.create(cache_dir, showWarnings = FALSE, recursive = TRUE)
dir.create(log_dir, showWarnings = FALSE, recursive = TRUE)

# Leer el contenido del archivo CSV
markers_file <- "path/to/your/markers.csv"
file_content <- readLines(markers_file)

# Omitir la línea de encabezado
data_lines <- file_content[-1]

# Convertir datos a formato de lista, usando índices numéricos como claves
marker_genes_list <- list()
cluster_names <- c()

# Primero recopilar todos los nombres de clústeres
for(line in data_lines) {
  parts <- strsplit(line, ",", fixed = TRUE)[[1]]
  cluster_names <- c(cluster_names, parts[1])
}

# Luego crear marker_genes_list con índices numéricos
for(i in seq_along(data_lines)) {
  line <- data_lines[i]
  parts <- strsplit(line, ",", fixed = TRUE)[[1]]

  # La primera parte es el nombre del clúster
  cluster_name <- parts[1]

  # Usar índice como clave (base 0, compatible con Seurat)
  cluster_id <- as.character(i - 1)

  # El resto son genes
  genes <- parts[-1]

  # Filtrar NA y cadenas vacías
  genes <- genes[!is.na(genes) & genes != ""]

  # Agregar a marker_genes_list
  marker_genes_list[[cluster_id]] <- list(genes = genes)
}

# Configurar claves API
api_keys <- list(
  gemini = "YOUR_GEMINI_API_KEY",
  qwen = "YOUR_QWEN_API_KEY",
  grok = "YOUR_GROK_API_KEY",
  openai = "YOUR_OPENAI_API_KEY",
  anthropic = "YOUR_ANTHROPIC_API_KEY"
)

# Ejecutar anotación de consenso
consensus_results <-
  interactive_consensus_annotation(
    input = marker_genes_list,
    tissue_name = "your tissue type", # Ejemplo: "human heart"
    models = c("gemini-2.0-flash",
              "gemini-1.5-pro",
              "qwen-max-2025-01-25",
              "grok-3-latest",
              "anthropic/claude-3-7-sonnet-20250219",
              "openai/gpt-4o"),
    api_keys = api_keys,
    controversy_threshold = 0.6,
    entropy_threshold = 1.0,
    max_discussion_rounds = 3,
    cache_dir = cache_dir,
    log_dir = log_dir
  )

# Guardar resultados
saveRDS(consensus_results, "your_results.rds")

# Imprimir resumen de resultados
cat("\nResumen de resultados:\n")
cat("Campos disponibles:", paste(names(consensus_results), collapse=", "), "\n\n")

# Imprimir anotaciones finales
cat("Anotaciones finales de tipos celulares:\n")
for(cluster in names(consensus_results$final_annotations)) {
  cat(sprintf("%s: %s\n", cluster, consensus_results$final_annotations[[cluster]]))
}
```

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

### Annotating Clusters with a Single LLM (Quick Start)

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/python/README.md

Demonstrates the basic usage of the `annotate_clusters` function. It shows how to import the library, load marker genes, set the API key via environment variables, and perform annotation using a single specified LLM provider and model.

```Python
import pandas as pd
from mllmcelltype import annotate_clusters, setup_logging

# Setup logging (optional but recommended)
setup_logging()

# Load marker genes (from Scanpy, Seurat, or other sources)
marker_genes_df = pd.read_csv('marker_genes.csv')

# Configure API keys (alternatively use environment variables)
import os
os.environ["OPENAI_API_KEY"] = "your-openai-api-key"

# Annotate clusters with a single model
annotations = annotate_clusters(
    marker_genes=marker_genes_df,  # DataFrame or dictionary of marker genes
    species='human',               # Organism species
    provider='openai',            # LLM provider
    model='gpt-4o',               # Specific model
    tissue='brain'                # Tissue context (optional but recommended)
)

# Print annotations
for cluster, annotation in annotations.items():
    print(f"Cluster {cluster}: {annotation}")
```

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

### Comparing Cell Type Annotations from Multiple LLM Models (R)

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/README.md

This R code provides an example loop to run the `annotate_cell_types` function with a list of different LLM models and their corresponding API keys. It demonstrates how to programmatically obtain annotations from various providers, store the results in a list, and add each model's annotations as a separate column to a Seurat object for subsequent comparison or visualization.

```R
# Define models to test
models_to_test <- c(
  "claude-3-7-sonnet-20250219",  # Anthropic
  "gpt-4o",                      # OpenAI
  "gemini-1.5-pro",              # Google
  "qwen-max-2025-01-25"          # Alibaba
)

# API keys for different providers
api_keys <- list(
  anthropic = "your-anthropic-key",
  openai = "your-openai-key",
  gemini = "your-gemini-key",
  qwen = "your-qwen-key"
)

# Test each model and store results
results <- list()
for (model in models_to_test) {
  provider <- get_provider(model)
  api_key <- api_keys[[provider]]

  # Run annotation
  results[[model]] <- annotate_cell_types(
    input = pbmc_markers,
    tissue_name = "human PBMC",
    model = model,
    api_key = api_key,
    top_gene_count = 10
  )

  # Add to Seurat object
  column_name <- paste0("cell_type_", gsub("[^a-zA-Z0-9]", "_", model))
  pbmc[[column_name]] <- plyr::mapvalues(
    x = as.character(Idents(pbmc)),
    from = as.character(0:(length(results[[model]])-1)),
    to = results[[model]]
  )
}
```

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

### Integrating mLLMCelltype with Scanpy Workflow (Python)

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/python/README.md

Provides a complete example of integrating `mllmcelltype` into a typical Scanpy workflow. It covers loading example data, performing standard preprocessing (filtering, normalization, scaling, PCA, neighbors, clustering), identifying marker genes for each cluster, calling `mct.annotate_clusters` for annotation, adding the annotations back to the AnnData object's `.obs` attribute, and visualizing the results using UMAP.

```python
import scanpy as sc
import mllmcelltype as mct

# Load data
adata = sc.datasets.pbmc3k()

# Preprocessing
sc.pp.filter_cells(adata, min_genes=200)
sc.pp.filter_genes(adata, min_cells=3)
sc.pp.normalize_total(adata, target_sum=1e4)
sc.pp.log1p(adata)
sc.pp.highly_variable_genes(adata, n_top_genes=2000)
sc.pp.pca(adata)
sc.pp.neighbors(adata)
sc.tl.leiden(adata)
sc.tl.umap(adata)

# Extract marker genes for each cluster
sc.tl.rank_genes_groups(adata, 'leiden', method='wilcoxon')
marker_genes = {}
for cluster in adata.obs['leiden'].unique():
    genes = sc.get.rank_genes_groups_df(adata, group=cluster)['names'].tolist()[:20]
    marker_genes[cluster] = genes

# Use mLLMCelltype for cell type annotation
annotations = mct.annotate_clusters(
    marker_genes=marker_genes,
    species='human',
    provider='openai',
    model='gpt-4o'
)

# Add annotations back to AnnData object
adata.obs['cell_type'] = adata.obs['leiden'].astype(str).map(annotations)

# Visualize results
sc.pl.umap(adata, color='cell_type', legend_loc='on data')
```

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

### Running Consensus Cell Type Annotation with mLLMCelltype (R)

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/README.md

This R code block demonstrates how to perform consensus-based cell type annotation using the `interactive_consensus_annotation` function with the mLLMCelltype package. It shows examples for using both paid and free LLM models via API keys, followed by saving the results to an RDS file and printing a summary and the final annotations to the console.

```R
# Run consensus annotation with paid models
consensus_results <-
  interactive_consensus_annotation(
    input = marker_genes_list,
    tissue_name = "your tissue type", # e.g., "human heart"
    models = c("gemini-2.0-flash",
              "gemini-1.5-pro",
              "qwen-max-2025-01-25",
              "grok-3-latest",
              "anthropic/claude-3-7-sonnet-20250219",
              "openai/gpt-4o"),
    api_keys = api_keys,
    controversy_threshold = 0.6,
    entropy_threshold = 1.0,
    max_discussion_rounds = 3,
    cache_dir = cache_dir,
    log_dir = log_dir
  )

# Alternatively, use free OpenRouter models (no credits required)
# Add OpenRouter API key to the api_keys list
api_keys$openrouter <- "your-openrouter-api-key"

# Run consensus annotation with free models
free_consensus_results <-
  interactive_consensus_annotation(
    input = marker_genes_list,
    tissue_name = "your tissue type", # e.g., "human heart"
    models = c(
      "meta-llama/llama-4-maverick:free",      # Meta Llama 4 Maverick (free)
      "nvidia/llama-3.1-nemotron-ultra-253b-v1:free",  # NVIDIA Nemotron Ultra 253B (free)
      "deepseek/deepseek-chat-v3-0324:free",   # DeepSeek Chat v3 (free)
      "microsoft/mai-ds-r1:free"               # Microsoft MAI-DS-R1 (free)
    ),
    api_keys = api_keys,
    controversy_threshold = 0.6,
    entropy_threshold = 1.0,
    max_discussion_rounds = 2,
    cache_dir = cache_dir,
    log_dir = log_dir
  )

# Save results
saveRDS(consensus_results, "your_results.rds")

# Print results summary
cat("\nResults summary:\n")
cat("Available fields:", paste(names(consensus_results), collapse=", "), "\n\n")

# Print final annotations
cat("Final cell type annotations:\n")
for(cluster in names(consensus_results$final_annotations)) {
  cat(sprintf("%s: %s\n", cluster, consensus_results$final_annotations[[cluster]]))
}
```

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

### Analyze and Visualize Model Performance - Python

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/python/README.md

Provides code to analyze and visualize the performance and agreement among different LLM models used for cell type annotation. It uses `compare_model_predictions` to get metrics and an agreement matrix, and `matplotlib`/`seaborn` to create a heatmap visualization.

```python
from mllmcelltype import compare_model_predictions, create_comparison_table
import matplotlib.pyplot as plt
import seaborn as sns

# Compare results from different LLM providers
model_predictions = {
    "OpenAI (GPT-4o)": results_openai,
    "Anthropic (Claude 3.7)": results_claude,
    "Google (Gemini 2.5 Pro)": results_gemini,
    "Alibaba (Qwen-Max-2025-01-25)": results_qwen
}

# Perform comprehensive model comparison analysis
agreement_df, metrics = compare_model_predictions(
    model_predictions=model_predictions,
    display_plot=False                # We'll customize the visualization
)

# Generate detailed performance metrics
print(f"Average inter-model agreement: {metrics['agreement_avg']:.2f}")
print(f"Agreement variance: {metrics['agreement_var']:.2f}")
if 'accuracy' in metrics:
    print(f"Average accuracy: {metrics['accuracy_avg']:.2f}")

# Create custom visualization of model agreement patterns
plt.figure(figsize=(10, 8))
sns.heatmap(agreement_df, annot=True, cmap='viridis', vmin=0, vmax=1)
plt.title('Inter-model Agreement Matrix', fontsize=14)
plt.tight_layout()
plt.savefig('model_agreement.png', dpi=300)
plt.show()

# Create and display a comparison table
comparison_table = create_comparison_table(model_predictions)
print(comparison_table)
```

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

### Annotating Clusters with Custom Prompt Template (Python)

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/python/README.md

Demonstrates how to call the `annotate_clusters` function using a dictionary of marker genes, species, LLM provider, specific model, and a pre-defined custom prompt string. The custom prompt allows for specialized instructions to guide the LLM's annotation process. The function returns a dictionary of cluster annotations.

```python
custom_template = """You are an expert computational biologist specializing in single-cell RNA-seq analysis.
Please annotate the following cell clusters based on their marker gene expression profiles.

Organism: {context}

Differentially expressed genes by cluster:
{clusters}

For each cluster, provide a precise cell type annotation based on canonical markers.
Consider developmental stage, activation state, and lineage information when applicable.
Provide only the cell type name for each cluster, one per line.
"""

# Annotate with specialized custom prompt
annotations = annotate_clusters(
    marker_genes=marker_genes_df,
    species='human',                # Organism species
    provider='openai',              # LLM provider
    model='gpt-4o',                # Specific model
    prompt_template=custom_template # Custom instruction template
)
```

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

### Consensus Annotation for Complex Types or Free Models Only - Python

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/python/README.md

Provides examples of configuring `interactive_consensus_annotation` for specific use cases: handling complex or ambiguous cell types by increasing the consensus threshold to trigger discussion rounds, and performing annotation using exclusively free models available through OpenRouter.

```python
# For ambiguous or specialized cell types (e.g., regulatory T cells vs. CD4+ T cells)
result = interactive_consensus_annotation(
    marker_genes=specialized_marker_genes,  # Markers for specialized cell types
    species='human',
    tissue='lymphoid tissue',
    models=[
        'gpt-4o',                                                      # Direct API (paid)
        {"provider": "openrouter", "model": "openai/gpt-4o"},          # OpenRouter (paid)
        {"provider": "openrouter", "model": "deepseek/deepseek-chat:free"},  # OpenRouter (free)
    ],
    consensus_threshold=0.8,                # Higher threshold to force discussion
    max_discussion_rounds=3,                # Allow multiple rounds of discussion
    verbose=True
)

# Using only free models for budget-conscious users
result_free = interactive_consensus_annotation(
    marker_genes=marker_genes,
    species='human',
    tissue='peripheral blood',
    models=[
        {"provider": "openrouter", "model": "deepseek/deepseek-chat:free"},      # DeepSeek (free)
        {"provider": "openrouter", "model": "microsoft/mai-ds-r1:free"},         # Microsoft (free)
        {"provider": "openrouter", "model": "qwen/qwen-2.5-7b-instruct:free"},   # Qwen (free)
        {"provider": "openrouter", "model": "thudm/glm-4-9b:free"}               # GLM (free)
    ],
    consensus_threshold=0.7,
    max_discussion_rounds=2,
    verbose=True
)
```

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

### Performing Cell Type Annotation with R

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/README_KR.md

Demonstrates a quick start using the mLLMCelltype R package for cell type annotation on a Seurat object. It involves identifying marker genes using FindAllMarkers, running the interactive consensus annotation with specified models and API keys, and adding the final annotations back to the Seurat object. Requires Seurat and mLLMCelltype libraries.

```R
library(mLLMCelltype)
library(Seurat)

# 마커 유전자 목록 준비
markers <- FindAllMarkers(seurat_obj, only.pos = TRUE, min.pct = 0.25, logfc.threshold = 0.25)

# 세포 유형 주석 수행
consensus_results <- interactive_consensus_annotation(
  input = markers,
  tissue_name = "human PBMC",
  models = c("gpt-4o", "claude-3-7-sonnet-20250219", "gemini-2.0-pro"),
  api_keys = list(
    openai = "your_openai_api_key",
    anthropic = "your_anthropic_api_key",
    gemini = "your_gemini_api_key"
  ),
  top_gene_count = 10
)

# 결과 확인
print(consensus_results$final_annotations)

# Seurat 객체에 주석 추가
current_clusters <- as.character(Idents(seurat_obj))
cell_types <- as.character(current_clusters)
for (cluster_id in names(consensus_results$final_annotations)) {
  cell_types[cell_types == cluster_id] <- consensus_results$final_annotations[[cluster_id]]
}
seurat_obj$cell_type <- cell_types
```

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

### Performing Cell Type Annotation with Python

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/README_KR.md

Provides a Python example using Scanpy and mLLMCelltype to annotate cell types from scRNA-seq data stored in an AnnData object. It covers standard preprocessing (neighbors, clustering), differential expression analysis for markers, converting markers for mLLMCelltype's input format, running the LLM-based annotation, and storing the results in the AnnData object's .obs attribute. Requires scanpy and mllmcelltype libraries.

```python
# 단일세포 RNA-seq 데이터에서 mLLMCelltype를 사용한 세포 유형 주석 예제
import scanpy as sc
import mllmcelltype as mct

# 단일세포 RNA-seq 데이터를 AnnData 형식으로 로드
adata = sc.read_h5ad("your_data.h5ad")  # 자신의 scRNA-seq 데이터로 교체

# 세포 집단 식별을 위한 네트워크 구축 및 Leiden 클러스터링 수행
sc.pp.neighbors(adata)  # 유사한 세포를 연결하는 KNN 그래프 구축
sc.tl.leiden(adata)     # 커뮤니티 검출 알고리즘을 사용하여 세포 집단 식별

# 각 클러스터의 마커 유전자 식별을 위한 차별 발현 분석 수행
sc.tl.rank_genes_groups(adata, groupby="leiden", method="wilcoxon")  # Wilcoxon 랭크합 검정을 사용한 마커 검출

# Scanpy의 마커 유전자 결과를 mLLMCelltype에서 사용할 수 있는 형식으로 변환
markers_dict = mct.utils.convert_scanpy_markers(adata)  # 마커 유전자 사전 형태로 변환

# 다중 대형 언어 모델을 사용한 세포 유형 주석 수행
consensus_results = mct.annotate.interactive_consensus_annotation(
    input=markers_dict,                                             # 마커 유전자 사전
    tissue_name="human PBMC",                                      # 조직 정보 지정(주석 정확도 향상)
    models=["gpt-4o", "claude-3-7-sonnet-20250219", "gemini-1.5-pro"],  # 다양한 대형 언어 모델 사용
    api_keys={                                                     # 각 LLM 제공업체의 API 키 설정
        "openai": "your_openai_api_key",                             # OpenAI GPT-4o API 키
        "anthropic": "your_anthropic_api_key",                       # Anthropic Claude API 키
        "gemini": "your_gemini_api_key"                              # Google Gemini API 키
    },
    top_gene_count=10                                              # 각 클러스터마다 사용할 상위 마커 유전자 수
)

# 주석 결과를 AnnData 객체에 추가하여 후속 분석 및 시각화 준비
adata.obs["cell_type"] = adata.obs["leiden"].map(
    lambda x: consensus_results["final_annotations"].get(x, "Unknown")
)
```

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

### Listing Free OpenRouter Models via API Python

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/openrouter_free_models_guide.md

Provides a Python script to fetch the list of available models from the OpenRouter API and filter for models that are currently free (prompt and completion pricing is zero). It requires the `requests` library and an OpenRouter API key.

```python
import requests
import os

# Get your OpenRouter API key
api_key = "your-openrouter-api-key"

# Get available models
response = requests.get(
    "https://openrouter.ai/api/v1/models",
    headers={"Authorization": f"Bearer {api_key}"}
)

# Print all free models
models = response.json()["data"]
print("Available free OpenRouter models:")
for model in models:
    model_id = model["id"]
    is_free = model.get("pricing", {}).get("prompt") == 0 and model.get("pricing", {}).get("completion") == 0
    if is_free:
        print(f"  - {model_id}")
```

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

### Loading LLM API Key from a Configuration File

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/python/README.md

Demonstrates using the `load_api_key` function to read API keys from a specified file path, such as a `.env` file, for a given provider.

```Python
from mllmcelltype import load_api_key

# Load from .env file or custom config
load_api_key(provider='openai', path='.env')
```

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

### Setting LLM API Keys via Environment Variables

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/python/README.md

Illustrates the recommended method for configuring API keys for various supported LLM providers by setting corresponding environment variables in your shell session.

```Bash
export OPENAI_API_KEY="your-openai-api-key"  # For GPT models
export ANTHROPIC_API_KEY="your-anthropic-api-key"  # For Claude models
export GOOGLE_API_KEY="your-google-api-key"  # For Gemini models
export QWEN_API_KEY="your-qwen-api-key"  # For Qwen-Max-2025-01-25, Qwen-Plus
export DEEPSEEK_API_KEY="your-deepseek-api-key"  # For DeepSeek-Chat
export ZHIPU_API_KEY="your-zhipu-api-key"  # For GLM-4, GLM-3-Turbo
export STEPFUN_API_KEY="your-stepfun-api-key"  # For Step-2-16k, Step-2-Mini, etc.
export MINIMAX_API_KEY="your-minimax-api-key"  # For MiniMax-Text-01
export GROK_API_KEY="your-grok-api-key"  # For Grok-3-latest
export OPENROUTER_API_KEY="your-openrouter-api-key"  # For accessing multiple models via OpenRouter
# Additional providers as needed
```

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

### Performing Batch Annotation Across Multiple Datasets

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/python/README.md

Provides an example of using the `batch_annotate_clusters` function to efficiently process a list of marker gene dataframes, representing multiple datasets or samples, using a single LLM configuration.

```Python
from mllmcelltype import batch_annotate_clusters

# Prepare multiple sets of marker genes (e.g., from different samples)
marker_genes_list = [marker_genes_df1, marker_genes_df2, marker_genes_df3]

# Batch annotate multiple datasets efficiently
batch_annotations = batch_annotate_clusters(
    marker_genes_list=marker_genes_list,
    species='mouse',                      # Organism species
    provider='anthropic',                 # LLM provider
    model='claude-3-7-sonnet-20250219',    # Specific model
    tissue='brain'                       # Optional tissue context
)

# Process and utilize results
for i, annotations in enumerate(batch_annotations):
    print(f"Dataset {i+1} annotations:")
    for cluster, annotation in annotations.items():
        print(f"  Cluster {cluster}: {annotation}")
```

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

### Manual Comparison of OpenRouter Models and Accessing Results - Python

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/python/README.md

Shows how to obtain individual annotation results from different OpenRouter models using `annotate_clusters` and then manually compare them using `compare_model_predictions`. It also demonstrates accessing the final consensus and uncertainty metrics from a previous `interactive_consensus_annotation` run.

```python
# Get annotations from different models via OpenRouter
openai_via_openrouter = annotate_clusters(
    marker_genes=marker_genes,
    species='human',
    tissue='peripheral blood',
    provider_config={"provider": "openrouter", "model": "openai/gpt-4o"}
)

anthropic_via_openrouter = annotate_clusters(
    marker_genes=marker_genes,
    species='human',
    tissue='peripheral blood',
    provider_config={"provider": "openrouter", "model": "anthropic/claude-3-opus"}
)

# Create a dictionary of model predictions for comparison
model_predictions = {
    "OpenAI via OpenRouter": openai_via_openrouter,
    "Anthropic via OpenRouter": anthropic_via_openrouter,
    "Direct OpenAI": results_openai,  # From previous direct API calls
}

# Compare the results
from mllmcelltype import compare_model_predictions
agreement_df, metrics = compare_model_predictions(model_predictions)

# Access results programmatically
final_annotations = result["consensus"]
uncertainty_metrics = {
    "consensus_proportion": result["consensus_proportion"],  # Agreement level
    "entropy": result["entropy"]                            # Annotation uncertainty
}
```

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

### Prepare LLM API Keys List for Consensus in R

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/R/index.md

Creates a named list containing the API keys for different LLM providers by retrieving them from environment variables. This list is required as an input parameter for the `interactive_consensus_annotation` function.

```R
# Create consensus using interactive consensus annotation
api_keys <- list(
  anthropic = Sys.getenv("ANTHROPIC_API_KEY"),
  openai = Sys.getenv("OPENAI_API_KEY"),
  gemini = Sys.getenv("GEMINI_API_KEY")
)
```

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

### List Available OpenRouter Models via API - Python

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/python/README.md

Shows how to programmatically query the OpenRouter API to retrieve a list of all available models, including identifying which ones are designated as free. Requires the OpenRouter API key.

```python
import requests
import os

# Get your OpenRouter API key
api_key = os.environ.get("OPENROUTER_API_KEY", "your-openrouter-api-key")

# Get available models
response = requests.get(
    "https://openrouter.ai/api/v1/models",
    headers={"Authorization": f"Bearer {api_key}"}
)

# Print all available models
models = response.json()["data"]
print("Available OpenRouter models:")
for model in models:
    model_id = model["id"]
    is_free = model.get("pricing", {}).get("prompt") == 0 and model.get("pricing", {}).get("completion") == 0
    print(f"  - {model_id}{' (free)' if is_free else ''}")
```

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

### Integrating Free OpenRouter Models in mLLMCelltype Python

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/openrouter_free_models_guide.md

Demonstrates how to call the `interactive_consensus_annotation` function from mLLMCelltype using free OpenRouter models. It shows the correct format for model IDs, including the required `:free` suffix, and how to provide the OpenRouter API key.

```python
consensus_results = interactive_consensus_annotation(
    marker_genes=marker_genes,
    species="human",
    models=[
        {"provider": "openrouter", "model": "meta-llama/llama-4-maverick:free"},
        {"provider": "openrouter", "model": "nvidia/llama-3.1-nemotron-ultra-253b-v1:free"}
    ],
    api_keys={
        "openrouter": "your-openrouter-api-key"
    },
    max_discussion_rounds=3
)
```

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

### Integrating mLLMCelltype with Seurat - R

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/README_ES.md

This R snippet demonstrates how to use mLLMCelltype with a Seurat object. It involves loading the Seurat object, setting API keys, extracting marker genes from the clustered Seurat object using `get_seurat_markers`, and then running the `annotate_cell_types` function with the extracted markers to get the consensus cell type annotations.

```R
library(Seurat)
library(mLLMCelltype)

# Cargar datos
pbmc <- readRDS("pbmc3k.rds")

# Configurar claves API
set_api_keys(
  openai = "sk-...",  # Clave API de OpenAI
  anthropic = "sk-ant-..."  # Clave API de Anthropic
)

# Extraer genes marcadores de Seurat
markers <- get_seurat_markers(pbmc, group.by = "seurat_clusters")

# Anotar tipos celulares
results <- annotate_cell_types(
  marker_list = markers,
  num_llms = 2,
  consensus_method = "discussion",
  rounds = 2
)
```

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

### Annotating Clusters Using Various Models via OpenRouter

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/python/README.md

Demonstrates how to utilize the OpenRouter provider within the `annotate_clusters` function to access and perform annotation using different LLMs (like OpenAI, Anthropic, Meta, DeepSeek) by specifying the provider and model within a dictionary.

```Python
from mllmcelltype import annotate_clusters

# Set your OpenRouter API key
import os
os.environ["OPENROUTER_API_KEY"] = "your-openrouter-api-key"

# Define marker genes for each cluster
marker_genes = {
    "1": ["CD3D", "CD3E", "CD3G", "CD2", "IL7R", "TCF7"],           # T cells
    "2": ["CD19", "MS4A1", "CD79A", "CD79B", "HLA-DRA", "CD74"],   # B cells
    "3": ["CD14", "LYZ", "CSF1R", "ITGAM", "CD68", "FCGR3A"]      # Monocytes
}

# Annotate using OpenAI's GPT-4o via OpenRouter
openai_annotations = annotate_clusters(
    marker_genes=marker_genes,
    species='human',
    tissue='peripheral blood',
    provider_config={"provider": "openrouter", "model": "openai/gpt-4o"}
)

# Annotate using Anthropic's Claude model via OpenRouter
anthropic_annotations = annotate_clusters(
    marker_genes=marker_genes,
    species='human',
    tissue='peripheral blood',
    provider_config={"provider": "openrouter", "model": "anthropic/claude-3-opus"}
)

# Annotate using Meta's Llama model via OpenRouter
meta_annotations = annotate_clusters(
    marker_genes=marker_genes,
    species='human',
    tissue='peripheral blood',
    provider_config={"provider": "openrouter", "model": "meta-llama/llama-3-70b-instruct"}
)

# Annotate using a free model via OpenRouter
free_model_annotations = annotate_clusters(
    marker_genes=marker_genes,
    species='human',
    tissue='peripheral blood',
    provider_config={"provider": "openrouter", "model": "deepseek/deepseek-chat:free"}  # Free model with :free suffix
)

# Print annotations from different models
for cluster in marker_genes.keys():
    print(f"Cluster {cluster}:")
    print(f"  OpenAI GPT-4o: {openai_annotations[cluster]}")
    print(f"  Anthropic Claude: {anthropic_annotations[cluster]}")
    print(f"  Meta Llama: {meta_annotations[cluster]}")
    print(f"  DeepSeek (free): {free_model_annotations[cluster]}")
```

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

### Set LLM Provider API Keys in R

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/R/index.md

Sets environment variables for the API keys required by different LLM providers (Anthropic, OpenAI, Google Gemini). Users must replace the placeholder strings with their actual keys.

```R
# Set API keys
Sys.setenv(ANTHROPIC_API_KEY = "your-anthropic-api-key")
Sys.setenv(OPENAI_API_KEY = "your-openai-api-key")
Sys.setenv(GEMINI_API_KEY = "your-gemini-api-key")
```

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

### Preparing scRNA-seq Data with Scanpy for mLLMCelltype (Python)

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/README.md

This Python code snippet demonstrates the initial steps of preparing single-cell RNA-seq data using the Scanpy library for subsequent annotation with mLLMCelltype. It covers loading data, basic preprocessing (normalization, log-transformation), dimensionality reduction (PCA), clustering (Leiden), and identifying cluster-specific marker genes using the Wilcoxon rank-sum test.

```Python
# Example of using mLLMCelltype for single-cell RNA-seq cell type annotation with Scanpy
import scanpy as sc
import pandas as pd
from mllmcelltype import annotate_clusters, setup_logging, interactive_consensus_annotation
import os

# Initialize logging for mLLMCelltype framework
setup_logging()

# Load your single-cell RNA-seq dataset in AnnData format
adata = sc.read_h5ad('your_data.h5ad')  # Replace with your scRNA-seq dataset path

# Perform Leiden clustering for cell population identification if not already done
if 'leiden' not in adata.obs.columns:
    print("Computing leiden clustering for cell population identification...")
    # Preprocess single-cell data: normalize counts and log-transform for gene expression analysis
    if 'log1p' not in adata.uns:
        sc.pp.normalize_total(adata, target_sum=1e4)  # Normalize to 10,000 counts per cell
        sc.pp.log1p(adata)  # Log-transform normalized counts

    # Dimensionality reduction: calculate PCA for scRNA-seq data
    if 'X_pca' not in adata.obsm:
        sc.pp.highly_variable_genes(adata, min_mean=0.0125, max_mean=3, min_disp=0.5)  # Select informative genes
        sc.pp.pca(adata, use_highly_variable=True)  # Compute principal components

    # Cell clustering: compute neighborhood graph and perform Leiden community detection
    sc.pp.neighbors(adata, n_neighbors=10, n_pcs=30)  # Build KNN graph for clustering
    sc.tl.leiden(adata, resolution=0.8)  # Identify cell populations using Leiden algorithm
    print(f"Leiden clustering completed, identified {len(adata.obs['leiden'].cat.categories)} distinct cell populations")

# Identify marker genes for each cell cluster using differential expression analysis
sc.tl.rank_genes_groups(adata, 'leiden', method='wilcoxon')  # Wilcoxon rank-sum test for marker detection
```

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

### Direct Annotation with Single Free OpenRouter Model - Python

Source: https://github.com/cafferychen777/mllmcelltype/blob/main/python/README.md

Illustrates how to use a specific free OpenRouter model (Microsoft MAI-DS-R1) for direct cell type annotation of predefined clusters based on their marker genes. It includes setting the OpenRouter API key and structuring the marker gene input.

```python
from mllmcelltype import annotate_clusters, setup_logging

# Setup logging (optional)
setup_logging()

# Set your OpenRouter API key
import os
os.environ["OPENROUTER_API_KEY"] = "your-openrouter-api-key"

# Define marker genes for each cluster
marker_genes = {
    "0": ["CD3D", "CD3E", "CD3G", "CD2", "IL7R", "TCF7"],           # T cells
    "1": ["CD19", "MS4A1", "CD79A", "CD79B", "HLA-DRA", "CD74"],   # B cells
    "2": ["CD14", "LYZ", "CSF1R", "ITGAM", "CD68", "FCGR3A"]      # Monocytes
}

# Annotate using only the Microsoft MAI-DS-R1 free model
mai_annotations = annotate_clusters(
    marker_genes=marker_genes,
    species='human',
    tissue='peripheral blood',
    provider='openrouter',
    model='microsoft/mai-ds-r1:free'  # Free model
)

# Print annotations
for cluster, annotation in mai_annotations.items():
    print(f"Cluster {cluster}: {annotation}")
```