> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omophub.com/llms.txt
> Use this file to discover all available pages before exploring further.

# R SDK - Mapping concepts across vocabularies

> Map concepts between OMOP vocabularies using the OMOPHub R SDK - crosswalk SNOMED, ICD-10, LOINC, and RxNorm codes directly from OHDSI R scripts.

## Get Mappings for a Concept

Find how a concept maps to other vocabularies:

```r theme={null}
result <- client$mappings$get(201826)  # Type 2 diabetes mellitus
for (mapping in result$data$mappings) {
  cat(sprintf("%s: %s\n", mapping$relationship_id, mapping$target_concept_name))
}
```

## Filter by Target Vocabulary

Get mappings to a specific vocabulary only:

```r theme={null}
result <- client$mappings$get(
  201826,
  target_vocabulary = "ICD10CM"
)
for (mapping in result$data$mappings) {
  cat(sprintf("%s: %s\n", mapping$target_concept_id, mapping$target_concept_name))
}
```

## Include Invalid Mappings

Include deprecated or invalid mappings in results:

```r theme={null}
result <- client$mappings$get(
  201826,
  target_vocabulary = "ICD10CM",
  include_invalid = TRUE
)
```

## Use Specific Vocabulary Version

Query mappings from a specific vocabulary release:

```r theme={null}
result <- client$mappings$get(
  201826,
  target_vocabulary = "ICD10CM",
  vocab_release = "2025.1"
)
```

## Map Multiple Concepts

Map a batch of concept IDs to a target vocabulary:

```r theme={null}
result <- client$mappings$map(
  target_vocabulary = "ICD10CM",
  source_concepts = c(201826, 4329847)  # Diabetes, MI
)
for (mapping in result$data$mappings) {
  source <- mapping$source_concept_id
  target <- mapping$target_concept_id
  cat(sprintf("%s -> %s\n", source, target))
}
```

## Map Using Vocabulary Codes

Map concepts directly using vocabulary codes instead of OMOP concept IDs:

```r theme={null}
result <- client$mappings$map(
  target_vocabulary = "RxNorm",
  source_codes = list(
    list(vocabulary_id = "SNOMED", concept_code = "387517004"),  # Acetaminophen
    list(vocabulary_id = "SNOMED", concept_code = "108774000")   # Anastrozole
  )
)
for (mapping in result$data$mappings) {
  cat(sprintf("%s -> %s\n", mapping$source_concept_name, mapping$target_concept_name))
}
```

<Note>
  Use `source_codes` when you have vocabulary-specific codes (e.g., SNOMED codes from your source system).
  Use `source_concepts` when you already have OMOP concept IDs.
  You cannot use both parameters in the same request.
</Note>

## Map with Specific Mapping Type

Filter mappings by type:

```r theme={null}
result <- client$mappings$map(
  target_vocabulary = "ICD10CM",
  source_concepts = c(201826, 192671),
  mapping_type = "direct"  # "direct", "equivalent", "broader", "narrower"
)
```

## Common Use Case: SNOMED to ICD-10

**Option 1: Direct mapping using vocabulary codes (recommended)**

```r theme={null}
result <- client$mappings$map(
  target_vocabulary = "ICD10CM",
  source_codes = list(
    list(vocabulary_id = "SNOMED", concept_code = "44054006")  # Type 2 diabetes
  )
)
for (m in result$data$mappings) {
  cat(sprintf("  -> %s (%s)\n", m$target_concept_name, m$target_concept_code))
}
```

**Option 2: Using OMOP concept IDs**

```r theme={null}
# First get the OMOP concept ID
concept <- client$concepts$get_by_code("SNOMED", "44054006")

# Then map using the concept ID
mappings <- client$mappings$get(
  concept$concept_id,
  target_vocabulary = "ICD10CM"
)

cat(sprintf("Mapping %s:\n", concept$concept_name))
for (m in mappings$data$mappings) {
  cat(sprintf("  -> %s (confidence: %s)\n", m$target_concept_name, m$confidence))
}
```

## Working with Mapping Results

Convert mappings to a data frame for analysis:

```r theme={null}
result <- client$mappings$get(201826)

# Create a data frame from mappings
mapping_df <- do.call(rbind, lapply(result$data$mappings, function(m) {
  data.frame(
    source_id = m$source_concept_id,
    source_name = m$source_concept_name,
    target_id = m$target_concept_id,
    target_name = m$target_concept_name,
    relationship = m$relationship_id,
    confidence = m$confidence,
    stringsAsFactors = FALSE
  )
}))

print(mapping_df)
```