<!--
# COPYRIGHT NOTICE
# This file is part of the "Universal Biomedical Skills" project.
# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
# All Rights Reserved.
#
# This code is proprietary and confidential.
# Unauthorized copying of this file, via any medium is strictly prohibited.
#
# Provenance: Authenticated by MD BABU MIA

-->

# How to Find Articles and cBioPortal Data

This guide walks you through searching biomedical literature with automatic cancer genomics integration from cBioPortal.

## Overview

When searching for articles about genes, BioMCP automatically enriches your results with:

- **cBioPortal Summary**: Mutation frequencies, hotspots, and cancer type distribution ([API Reference](../backend-services-reference/03-cbioportal.md))
- **PubMed Articles**: Peer-reviewed research with entity annotations ([PubTator3 Reference](../backend-services-reference/06-pubtator3.md))
- **Preprints**: Latest findings from bioRxiv and medRxiv

## Basic Article Search

### Search by Gene

Find articles about a specific gene:

```bash
# CLI
biomcp article search --gene BRAF --limit 5

# Python
articles = await client.articles.search(genes=["BRAF"], limit=5)

# MCP Tool
article_searcher(genes=["BRAF"], limit=5)
```

This automatically includes:

1. cBioPortal summary showing BRAF mutation frequency across cancers
2. Top mutation hotspots (e.g., V600E)
3. Recent articles mentioning BRAF

### Search by Disease

Find articles about a specific disease:

```bash
# CLI
biomcp article search --disease melanoma --limit 10

# Python
articles = await client.articles.search(diseases=["melanoma"])

# MCP Tool
article_searcher(diseases=["melanoma"])
```

## Advanced Search Techniques

### Combining Multiple Filters

Search for articles at the intersection of genes, diseases, and chemicals:

```bash
# CLI - EGFR mutations in lung cancer treated with erlotinib
biomcp article search \
  --gene EGFR \
  --disease "lung cancer" \
  --chemical erlotinib \
  --limit 20

# Python
articles = await client.articles.search(
    genes=["EGFR"],
    diseases=["lung cancer"],
    chemicals=["erlotinib"]
)
```

### Using OR Logic in Keywords

Find articles mentioning different notations of the same variant:

```bash
# CLI - Find any notation of BRAF V600E
biomcp article search \
  --gene BRAF \
  --keyword "V600E|p.V600E|c.1799T>A"

# Python - Different names for same concept
articles = await client.articles.search(
    diseases=["NSCLC|non-small cell lung cancer"],
    chemicals=["pembrolizumab|Keytruda|anti-PD-1"]
)
```

### Excluding Preprints

For peer-reviewed articles only:

```bash
# CLI
biomcp article search --gene TP53 --no-preprints

# Python
articles = await client.articles.search(
    genes=["TP53"],
    include_preprints=False
)
```

## Understanding cBioPortal Integration

### What cBioPortal Provides

When you search for a gene, the first result includes:

```markdown
### cBioPortal Summary for BRAF

- **Mutation Frequency**: 76.7% (368 mutations in 480 samples)
- **Studies**: 1 of 5 studies have mutations

**Top Hotspots:**

1. V600E: 310 mutations (84.2%)
2. V600K: 23 mutations (6.3%)
3. V600M: 12 mutations (3.3%)

**Cancer Type Distribution:**

- Skin Cancer, Non-Melanoma: 156 mutations
- Melanoma: 91 mutations
- Thyroid Cancer: 87 mutations
```

### Mutation-Specific Searches

Search for articles about specific mutations:

```python
# Search for BRAF V600E specifically
articles = await client.articles.search(
    genes=["BRAF"],
    keywords=["V600E"],
    include_cbioportal=True  # Default
)
```

The cBioPortal summary will highlight the specific mutation if found.

### Disabling cBioPortal

If you don't need cancer genomics data:

```bash
# CLI
biomcp article search --gene BRCA1 --no-cbioportal

# Python
articles = await client.articles.search(
    genes=["BRCA1"],
    include_cbioportal=False
)
```

## Practical Examples

### Example 1: Resistance Mechanism Research

Find articles about EGFR T790M resistance:

```python
# Using think tool first (for MCP)
think(
    thought="Researching EGFR T790M resistance mechanisms in lung cancer",
    thoughtNumber=1
)

# Search with multiple relevant terms
articles = await article_searcher(
    genes=["EGFR"],
    diseases=["lung cancer|NSCLC"],
    keywords=["T790M|p.T790M|resistance|resistant"],
    chemicals=["osimertinib|gefitinib|erlotinib"]
)
```

### Example 2: Combination Therapy Research

Research BRAF/MEK combination therapy:

```bash
# CLI approach
biomcp article search \
  --gene BRAF --gene MEK1 --gene MEK2 \
  --disease melanoma \
  --chemical dabrafenib --chemical trametinib \
  --keyword "combination therapy|combined treatment"
```

### Example 3: Biomarker Discovery

Find articles about potential biomarkers:

```python
# Search for PD-L1 as a biomarker
articles = await client.articles.search(
    genes=["CD274"],  # PD-L1 gene symbol
    keywords=["biomarker|predictive|prognostic"],
    diseases=["cancer"],
    limit=50
)

# Filter results programmatically
biomarker_articles = [
    a for a in articles
    if "biomarker" in a.title.lower() or "predictive" in a.abstract.lower()
]
```

## Working with Results

### Extracting Key Information

```python
# Process article results
for article in articles:
    print(f"Title: {article.title}")
    print(f"PMID: {article.pmid}")
    print(f"URL: {article.url}")

    # Extract annotated entities
    genes = article.metadata.get("genes", [])
    diseases = article.metadata.get("diseases", [])
    chemicals = article.metadata.get("chemicals", [])

    print(f"Genes mentioned: {', '.join(genes)}")
    print(f"Diseases: {', '.join(diseases)}")
    print(f"Chemicals: {', '.join(chemicals)}")
```

### Fetching Full Article Details

Get complete article information:

```python
# Get article by PMID
full_article = await client.articles.get("38768446")

# Access full abstract
print(full_article.abstract)

# Check for full text availability
if full_article.full_text_url:
    print(f"Full text: {full_article.full_text_url}")
```

## Tips for Effective Searches

### 1. Use Official Gene Symbols

```python
# ✅ Correct - Official HGNC symbol
articles = await search(genes=["ERBB2"])

# ❌ Avoid - Common name
articles = await search(genes=["HER2"])  # May miss results
```

### 2. Include Synonyms for Diseases

```python
# Cover all variations
articles = await search(
    diseases=["GIST|gastrointestinal stromal tumor|gastrointestinal stromal tumour"]
)
```

### 3. Leverage PubTator Annotations

PubTator automatically annotates articles with:

- Gene mentions (normalized to official symbols)
- Disease concepts (mapped to MeSH terms)
- Chemical/drug entities
- Genetic variants
- Species

### 4. Combine with Other Tools

```python
# 1. Find articles about a gene
articles = await article_searcher(genes=["ALK"])

# 2. Get gene details for context
gene_info = await gene_getter("ALK")

# 3. Find relevant trials
trials = await trial_searcher(
    other_terms=["ALK positive", "ALK rearrangement"]
)
```

## Troubleshooting

### No Results Found

1. **Check gene symbols**: Use [genenames.org](https://www.genenames.org)
2. **Broaden search**: Remove filters one by one
3. **Try synonyms**: Especially for diseases and drugs

### cBioPortal Data Missing

- Some genes may not have cancer genomics data
- Try searching for cancer-related genes
- Check if gene symbol is correct

### Preprint Issues

- Europe PMC may have delays in indexing
- Some preprints may not have DOIs
- Try searching by title keywords instead

## Next Steps

- Learn to [find trials with NCI and BioThings](02-find-trials-with-nci-and-biothings.md)
- Explore [variant annotations](03-get-comprehensive-variant-annotations.md)
- Set up [API keys](../getting-started/03-authentication-and-api-keys.md) for enhanced features


<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->