# Types of Codelist

In this vignette we will introduce the three different types of codelist that CodelistGenerator uses: codelist, codelist with details, and concept set. First of all, we will upload the packages required for the demonstration.

    library(omopgenerics, warn.conflicts = FALSE)
    library(dplyr, warn.conflicts = FALSE)
    library(CodelistGenerator)

## Codelist

Codelist format is the simplest of the three formats. To create one, we just need a named list where each element contains a vector of concept IDs. You can see an example below on how to create one:

    codelist <- list("codes1" = c(1L, 2L, 3L),
                     "codes2" = c(4L, 5L, 10L))
    codelist <- newCodelist(codelist)

    codelist

Notice that the codelist has two specific attributes, the name of the codelists that contains and the class:

    attributes(codelist)

### Create an empty codelist

We can create an empty codelist using omopGenerics package:

    empty_codelist  <- emptyCodelist()

    empty_codelist

## Codelist with details

Codelist with details contains a tibble in each element. To create one, we need a named list where each element contains a tibble with at least the column concept_id.

    codelist_with_details <- list("codes1" = tibble("concept_id" = c(1L, 2L, 3L)),
                                  "codes2" = tibble("concept_id" = c(4L, 5L, 10L)))
    codelist_with_details <- newCodelistWithDetails(codelist_with_details)

    codelist_with_details

Notice that this allows us to add more information of each one of the codes:

    codelist_with_details <- list(
      "codes1" = tibble("concept_id" = c(1L, 2L, 3L),
                        "concept_name" = c("Musculoskeletal disorder", "Osteoarthrosis", "Arthritis"),
                        "domain_id" = c("Condition", "Condition", "Condition"),
                        "vocabulary_id" = c("SNOMED","SNOMED","SNOMED"),
                        "standard_concept" = c("S","S","S")),
      "codes2" = tibble("concept_id" = c(4L, 5L, 10L),
                        "concept_name" = c("Osteoarthritis of knee", "Osteoarthritis of hip", "Adalimumab"),
                        "domain_id" = c("Condition", "Condition", "Drug"),
                        "vocabulary_id" = c("SNOMED","SNOMED","RxNorm"),
                        "standard_concept" = c("S","S","S")))
    codelist_with_details <- newCodelistWithDetails(codelist_with_details)

    codelist_with_details

The codelist with details also has two specific attributes:

    attributes(codelist_with_details)

### Create an empty codelist with details

omopGenerics package also has a function to create an empty codelist with details.

    empty_codelist_with_details <- emptyCodelistWithDetails()

    empty_codelist_with_details

## Concept set expression

A concept set expression contains a tibble with the logic describing how this concepts will be included or excluded. It usually follows the JSON file structure. To create one, we need a named list with a tibble containing the columns: concept_id, excluded, descendants, and mapped:

    concept_set_expression <- list(
      "codes1" = tibble("concept_id" = c(1L, 2L, 3L),
                        "excluded" = c(FALSE, FALSE, FALSE),
                        "descendants" = c(TRUE, FALSE, FALSE),
                        "mapped" = c(TRUE, TRUE, TRUE)),
      "codes2" = tibble("concept_id" = c(4L, 5L, 10L),
                        "excluded" = c(FALSE, FALSE, FALSE),
                        "descendants" = c(FALSE, FALSE, FALSE),
                        "mapped" = c(TRUE, TRUE, TRUE))
    )

    concept_set_expression <- newConceptSetExpression(concept_set_expression)

    concept_set_expression

You can also see the attributes:

    attributes(concept_set_expression)

### Create an empty concept set expression

We can also use omopGenerics package to create an empty concept set expression:

    empty_concept_set_expression <- emptyConceptSetExpression()

    empty_concept_set_expression

### Concept set expression from a JSON file

CodelistGenerator contains a function that allows us to read a JSON file and transform it to a concept set expression (or other types of codelists). See the vignette Extract codelists from JSON files for further information.

## Change to different codelist types

There are several functions in CodelistGenerator that will allow us to go from a codelist to a codelist with details.

### Codelist/Concept set expression to codelist with details

Notice that to go from a codelist or concept_set_expression to a codelist_with_details, we will need to provide the cdm, as the details of the concepts will be extracted from the concept table.

    cdm <- mockVocabRef()
    codelist_to_codelist_with_details <- asCodelistWithDetails(codelist, cdm)
    codelist_to_codelist_with_details

    codelist_to_concept_set_expression <- asCodelistWithDetails(codelist, cdm)
    codelist_to_concept_set_expression

### Codelist/Codelist with details to concept set expression

    codelist_to_concept_set_expression <- asConceptSetExpression(codelist)
    codelist_to_concept_set_expression

    codelist_with_details_to_concept_set_expression <- asConceptSetExpression(codelist_with_details)
    codelist_with_details_to_concept_set_expression

### Codelist with details/Concept set expression to codelist

    codelist_with_details_to_codelist <- asCodelist(codelist_with_details)
    codelist_with_details_to_codelist