Feature Request: assign_ct mapping algorithm

[rammprasad]

Feature Idea

The assign_ct algorithm will be implemented as a function.

Algorithm Description - One-to-one mapping between the raw source and a
target SDTM variable that is subject to controlled terminology
restrictions. A simple assign statement and applying controlled
terminology. This will be used only if the SDTM variable has an
associated controlled terminology.

Example mappings -
VS.VSPOS
VS.VSLAT
CM.CMDOSU

function call

assign_ct(raw_dataset,
raw_variable,
study_ct,
target_sdtm_variable, 
target_sdtm_variable_codelist_code,
target_dataset,
merge_to_topic_by )

Input: raw_dataset - R dataframe. Usually, the raw dataset.

raw_variable - A Character string. Name of the variable in the raw
dataset

study_ct - A dataframe that has all the controlled terminology of the
study.

target_sdtm_variable - A Character string. Name of the SDTM variable
that has to be derived

target_sdtm_variable_codelist_code - A Character string. The codelist
code of the SDTM variable that is being derived.

target_dataset - Optional parameter. This is the target_dataset that was
created in the previous step.

merge_to_topic_by - Optional parameter. A vector with the string that
will be used to merge to the target_dataset

Output: A dataframe with oak_id_vars and target_sdtm_variable if
target_dataset & merge_to_topic_by are not provided target_dataset with
one additional variable target_sdtm_variable

Relevant Input

sdtm spec

study_number	raw_source_model	raw_dataset	raw_dataset_ordinal	raw_dataset_label	raw_variable	raw_variable_label	raw_variable_ordinal	raw_variable_type	raw_data_format	raw_codelist	study_specific	annotation_ordinal	mapping_is_dataset	annotation_text	target_sdtm_domain	target_sdtm_variable	target_sdtm_variable_role	target_sdtm_variable_codelist_code	target_sdtm_variable_controlled_terms_or_format	target_sdtm_variable_ordinal	origin	mapping_algorithm	entity_sub_algorithm	target_hardcoded_value	target_term_value	target_term_code	condition_ordinal	condition_group_ordinal	condition_left_raw_dataset	condition_left_raw_variable	condition_left_sdtm_domain	condition_left_sdtm_variable	condition_operator	condition_right_text_value	condition_right_sdtm_domain	condition_right_sdtm_variable	condition_right_raw_dataset	condition_right_raw_variable	condition_next_logical_operator	merge_type	merge_left	merge_right	merge_condition	unduplicate_keys	groupby_keys	target_resource_raw_dataset	target_resource_raw_variable
lp_study	e-CRF	MD1	27	Concomitant Medications	MDRTE	Route	17	DropDownList	$25	ROUTE_CV1	FALSE	1	FALSE	CM.CMROUTE	CM	CMROUTE	Variable Qualifier	C66729	(ROUTE)	29	CRF	ASSIGN_CT	NA_character_	NA	NA	NA	NA	NA	NA	NA	NA	NA	NA	NA	NA	NA	NA	NA	NA	NA	NA	NA	NA	NA	NA	NA	NA

raw_datasaet

oak_id	raw_source	PATIENT_NUM	MDRTE
1	MD1	PATNUM	PO (Oral)
2	MD1	PATNUM	PO (Oral)
3	MD1	PATNUM	NA_character_
4	MD1	PATNUM	PO
5	MD1	PATNUM	Intraoral Route of Administration
6	MD1	PATNUM	PO (Oral)
7	MD1	PATNUM	IM (Intramuscular)
8	MD1	PATNUM	IA (Intra-arterial)
9	MD1	PATNUM
10	MD1	PATNUM	Non-standard
11	MD1	PATNUM	random_value
12	MD1	PATNUM	IJ (Intra-articular)
13	MD1	PATNUM	TRANSDERMAL
14	MD1	PATNUM	OPHTHALMIC

raw_variable = "MDRTE"

study_ct - Controlled terminoloigy of the study. Example shows just one codelist. The entire object can be passed.

codelist_code	term_code	CodedData	term_value	collected_value	term_preferred_term	term_synonyms	raw_codelist
C66729	C28161	INTRAMUSCULAR	INTRAMUSCULAR	IM (Intramuscular)	Intramuscular Route of Administration	NA_character_	ROUTE_CV1
C66729	C38210	EPIDURAL	EPIDURAL	EP (Epidural)	Epidural Route of Administration	NA_character_	ROUTE_CV1
C66729	C38222	INTRA-ARTERIAL	INTRA-ARTERIAL	IA (Intra-arterial)	Intraarterial Route of Administration	NA_character_	ROUTE_CV1
C66729	C38223	INTRA-ARTICULAR	INTRA-ARTICULAR	IJ (Intra-articular)	Intraarticular Route of Administration	NA_character_	ROUTE_CV1
C66729	C38287	OPHTHALMIC	OPHTHALMIC	OP (Ophthalmic)	Ophthalmic Route of Administration	NA_character_	ROUTE_CV1
C66729	C38288	ORAL	ORAL	PO (Oral)	Oral Route of Administration	Intraoral Route of Administration; PO	ROUTE_CV1
C66729	C38305	TRANSDERMAL	TRANSDERMAL	DE (Transdermal)	Transdermal Route of Administration	NA_character_	ROUTE_CV1
C66729	C38311	UNKNOWN	UNKNOWN	Unknown	Unknown Route of Administration	NA_character_	ROUTE_CV1

target_variable = "CMROUTE"

target_sdtm_variable_codelist_code = "C66729"

target_dataset = cm_inter - Let's assume CMTRT, CMINDC variables are
already derived and CMROUTE is the third variable being processed

oak_id	raw_source	patient_number	CMTRT	CMINDC
1	MD1	PATNUM	BABY ASPIRIN	NA_character_
2	MD1	PATNUM	CORTISPORIN	NAUSEA
3	MD1	PATNUM	ASPIRIN	ANEMIA
4	MD1	PATNUM	DIPHENHYDRAMINE HCL	NAUSEA
5	MD1	PATNUM	PARCETEMOL	PYREXIA
6	MD1	PATNUM	VOMIKIND	VOMITINGS
7	MD1	PATNUM	ZENFLOX OZ	DIARHHEA
8	MD1	PATNUM	AMITRYPTYLINE	COLD
9	MD1	PATNUM	BENADRYL	FEVER
10	MD1	PATNUM	DIPHENHYDRAMINE HYDROCHLORIDE	LEG PAIN
11	MD1	PATNUM	TETRACYCLINE	FEVER
12	MD1	PATNUM	BENADRYL	COLD
13	MD1	PATNUM	SOMINEX	COLD
14	MD1	PATNUM	ZQUILL	PAIN

merge_to_topic_by - oak_id_vars

Relevant Output

Option 1 - When the function call is

assign_ct(
raw_dataset = MD1,
raw_variable = "MDTRE",
study_ct = study_ct,
target_sdtm_variable = "CMROUTE", 
target_sdtm_variable_codelist_code = "C66729",
target_dataset = cm_inter,
merge_to_topic_by = c("oak_id","raw_source","patient_number"))

output dataset from the function

oak_id	raw_source	PATIENT_NUM	CMTRT	CMINDC	CMROUTE
1	MD1	PATNUM	BABY ASPIRIN	NA_character_	ORAL
2	MD1	PATNUM	CORTISPORIN	NAUSEA	ORAL
3	MD1	PATNUM	ASPIRIN	ANEMIA
4	MD1	PATNUM	DIPHENHYDRAMINE HCL	NAUSEA	ORAL
5	MD1	PATNUM	PARCETEMOL	PYREXIA	ORAL
6	MD1	PATNUM	VOMIKIND	VOMITINGS	ORAL
7	MD1	PATNUM	ZENFLOX OZ	DIARHHEA	INTRAMUSCULAR
8	MD1	PATNUM	AMITRYPTYLINE	COLD	INTRA-ARTERIAL
9	MD1	PATNUM	BENADRYL	FEVER
10	MD1	PATNUM	DIPHENHYDRAMINE HYDROCHLORIDE	LEG PAIN	NON-STANDARD
11	MD1	PATNUM	TETRACYCLINE	FEVER	RANDOM_VALUE
12	MD1	PATNUM	BENADRYL	COLD	INTRA-ARTICULAR
13	MD1	PATNUM	SOMINEX	COLD	TRANSDERMAL
14	MD1	PATNUM	ZQUILL	PAIN	OPHTHALMIC

Option 2 - When used without merging

assign_ct(
raw_dataset = MD1,
raw_variable = "MDTRE",
study_ct = study_ct,
target_sdtm_variable = "CMROUTE", 
target_sdtm_variable_codelist_code = "C66729")

Output dataset

oak_id	raw_source	PATIENT_NUM	CMROUTE
1	MD1	PATNUM	ORAL
2	MD1	PATNUM	ORAL
3	MD1	PATNUM
4	MD1	PATNUM	ORAL
5	MD1	PATNUM	ORAL
6	MD1	PATNUM	ORAL
7	MD1	PATNUM	INTRAMUSCULAR
8	MD1	PATNUM	INTRA-ARTERIAL
9	MD1	PATNUM
10	MD1	PATNUM	NON-STANDARD
11	MD1	PATNUM	RANDOM_VALUE
12	MD1	PATNUM	INTRA-ARTICULAR
13	MD1	PATNUM	TRANSDERMAL
14	MD1	PATNUM	OPHTHALMIC

Reproducible Example/Pseudo Code

library(sdtm.oak)
library(dplyr)

cm <- cm_daw_data |>
  # Derive topic variable
  assign_no_ct(
    raw_dataset = MD1, 
    raw_variable = MDRAW,
    target_sdtm_var = CMTRT
  )  |>
  assign_no_ct(
    raw_dataset = MD1,
    raw_variable = MDIND,
    target_sdtm_var = CMINDC,
    merge_to_topic_by = c("oak_id","raw_source","patient_number")
  ) |>
assign_ct(
raw_dataset = MD1,
raw_variable = "MDTRE",
study_ct = study_ct,
target_sdtm_variable = "CMROUTE", 
target_sdtm_variable_codelist_code = "C66729",
target_dataset = cm_inter,
merge_to_topic_by = c("oak_id","raw_source","patient_number"))

Option 2 - Just to derive CMCAT

cm <- cm_daw_data |>
assign_ct(
raw_dataset = MD1,
raw_variable = "MDTRE",
study_ct = study_ct,
target_sdtm_variable = "CMROUTE", 
target_sdtm_variable_codelist_code = "C66729")