---
title: "Mappings Tab"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Mappings Tab}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Introduction

The **Mappings** tab is used to combine concepts and audit mapping decisions. Merge actions are available in **patient mode**.

The example below creates a small hierarchy-based mapping table from the bundled `lc500` study. These are the kinds of candidate merges that can later be reviewed in the Mappings tab.

```{r}
if (requireNamespace("nanoparquet", quietly = TRUE)) {
  studyDir <- system.file("example", "st", package = "CohortContrast")
  study <- CohortContrast::loadCohortContrastStudy("lc500", pathToResults = studyDir)

  maxMinDataFrame <- data.frame(
    descendant_concept_id = c(4008211, 4176729, 2107967, 2107968, 2108158, 32280, 32815),
    maximum_minimal_separation = c(0, 1, 0, 1, 1, 0, 1)
  )

  mappingTable <- CohortContrast::generateMappingTable(
    abstractionLevel = 0,
    data = study,
    maxMinDataFrame = maxMinDataFrame
  )
  utils::head(mappingTable, 4)
}
```

Each row links a more specific concept to a broader replacement concept, together with the mapping type and abstraction level used to generate the suggestion.

## Manual Merge

Workflow:

1. In **Manual Merge**, select concepts using the `Map` column (main concepts only).
2. Click **Merge Selected Concepts**.
3. Confirm `New Concept ID`, `New Concept Name`, and `Heritage`.
4. Click **Apply Merge**.

Defaults in the merge form are prefilled from the most prevalent selected concept.

![Manual merge workflow](../man/figures/a02_mappings_manual.png)

## Hierarchy Suggestions

Use hierarchy-based candidate merges:

- Set `Minimum hierarchy depth`.
- Optionally keep `Allow only minors` enabled.
- Click **Update Hierarchy Suggestions**.
- Review rows and click **Merge Selected Hierarchy Suggestions**.

![Hierarchy suggestions](../man/figures/a02_mappings_suggestions.png)

## Correlation Suggestions

Use correlation-based candidate merges:

- Set `Minimum correlation`.
- Set `Max median days in between`.
- Optionally allow `heritage drift`.
- Click **Update Correlation Suggestions**.
- Review rows and click **Merge Selected Correlation Suggestions**.

![Correlation suggestions](../man/figures/a06_mappings_correlation.png)

## Mapping History

The history table records applied mappings, including source concept IDs/names, mapped concept IDs/names, mapping type, and heritage. Use it as an audit trail for post-processing decisions.