Calculate a standardised CARTBEQ value from various inputs — CARTBEQ

This function includes various ways of calculating a standardised beta-carotene equivalents (CARTBEQ) value. The most appropriate calculation is selected based on the availability of input data.

Usage

CARTBEQ_standardised(
  df,
  item_ID = "fdc_id",
  CARTAmcg = "CARTAmcg",
  CARTBmcg = "CARTBmcg",
  CARTBEQmcg = "CARTBEQmcg",
  CARTBEQmcg_std = "CARTBEQmcg_std",
  CRYPXBmcg = "CRYPXBmcg",
  VITAmcg = "VITAmcg",
  VITA_RAEmcg = "VITA_RAEmcg",
  RETOLmcg = "RETOLmcg",
  comment_col = "comments",
  compile = T,
  carotene = T,
  comment = T
)

Arguments

df: Required - the data.frame the data is currently stored in
item_ID: Required - default: 'fdc_id' - The column which contains the data for the ID column name
CARTAmcg: Optional - default: 'CARTAmcg' - A potential input variable; the column which contains the data for alpha-carotene in micrograms
CARTBmcg: Optional - default: 'CARTBmcg' - A potential input variable; the column which contains the data for beta-carotene in micrograms
CARTBEQmcg: Optional - default: 'CARTBEQmcg' - A potential input variable; the column which contains the data for beta-carotene equivalent in micrograms
CARTBEQmcg_std: Optional - default: 'CARTBEQmcg_std' - A potential input variable; the column which contains the data for standardised beta-carotene equivalent in micrograms
CRYPXBmcg: OPtional - default: 'CRYPXBmcg' - A potential input variable; the column which contains the data for beta-crpytoxanthin in micrograms
VITAmcg: Optional - default: 'VITAmcg' - A potential input variable; the column which contains the data for Vitamin-A in micrograms
VITA_RAEmcg: Optional - default: 'VITA_RAEmcg' - A potential input variable; the column which contains the data for Vitamin-A in Retinol Activity Equivalents, in micrograms
RETOLmcg: Optional - default: 'RETOLmcg' - A potential input variable; the column which contains the data for Retinol in micrograms
comment_col: Optional - default: 'comments' - A potential input variable; the column which contains the metadata comments for the food item in question
compile: Optional - default: T - TRUE or FALSE. If compile is set to T (as it is by default), then when Beta-Carotene (CARTBmcg) is not available then Beta-Carotene Eq. (CARTBEQ) is used as the value for Beta-Carotene equivalent (standardised).
carotene: Optional - default: T - TRUE or FALSE. If carotene is set to T (as it is by default), then when Beta-Carotene (CARTBmcg) is available then it is used as the value for Beta-Carotene equivalent (standardised)
comment: Optional - default: T - TRUE or FALSE. If compile is set to T (as it is by default), then when the function is run a description of the calculation used to find CARTBEQ_standardised is added to the comment_col. If no comment_col is selected, and comment = T, one is created, called comments.

Value

A data.frame that mirrors df, but with a new column - recalculated_CARTBEQmcg_std - added. New comments may also be added.

Details

The Standardiser can use 6 different ways of calculating Beta-Carotene, on a case-by-case (or row-by-row) basis to ensure that each item has the most appropriate calculation used on it. If the most appropriate calculation cannot be completed (due to incomplete input data) then the next most appropriate calculation is used, and so on. The calculations and their position in the hierarchy is shown below:

1. recalculated_CARTBEQmcg_std = CARTBmcg_value + 0.5*CARTAmcg_value + 0.5*CRYPXBmcg_value. Beta-Carotene Equivalents (standardised) value (CARTBEQ_std) is calculated from its base elements, dependent on valid Alpha-Carotene (CARTA), Beta-Carotene (CARTB), and Beta-Cryptoxanthin CRYPXB) values.
2. recalculated_CARTBEQmcg_std = CARTBEQmcg_std_value. If the base elements for the calculation are unavailable, but a standardised CARTBEQ value already exists, it is used.
3. recalculated_CARTBEQmcg_std = CARTBEQmcg _value. If neither the base elements for the calculation or a standardised CARTBEQ value are unavailable then the non-standardised CARTBEQ value is used instead, if it exists.
4. recalculated_CARTBEQmcg_std = CARTBmcg _value. If neither the base elements for the calculation, or a CARTBEQ value (standardised or otherwise) exist, then the Beta-Carotene (CARTB) value is used if available.
5. recalculated_CARTBEQmcg_std = (VITA_RAEmcg_value - RETOLmcg_value)*12. If none of the above are available, then CATBEQ_std is calculated from Vitamin A Retinol Activity Equivalent (VITA_RAE) and Retinol (RETOL).
6. recalculated_CARTBEQmcg_std = (VITAmcg_value - RETOLmcg_value)*6. If none of the above are available, then CATBEQ_std is calculated from Vitamin A (VITA) and Retinol (RETOL).

This hierarchy remains unchanged – however, the equations in the hierarchy can be altered depending on the compile and carotene input options. If both are set to True, then the full list of 6 equations are made available. If compile == F, then options 2 and 3 (to use pre-existing CARTBEQ_std or CARTBEQ values) are removed, meaning that the only options 1, 4, 5, 6 are available in the Hierarchy. Similarly, if carotene == F, then option 4 (to use a pre-existing CARTB value) is removed, leaving only options 1, 5, 6 if both are set to false. If none of those options are available (i.e. the data is incomplete, and no value can be calculated and no fill-in value used) then the CARTBEQ_std value is set to NA.

Examples

#The most common usage scenario will be covered. First we will create a test
#data.frame with dummy data to use the function on. This function is designed
#to be able to be used with patchy data - if certain columns are incomplete
#then then the best calculation will be used on a row-by-row basis.

test_df <- data.frame( ID = c("test_01", "test_02", "test_03", "test_04",
"test_05", "test_06", "test_07", "test_08", "test_09", "test_10" ), food_name
= c("Bread (wholemeal)", "Pepper, ground, black", "Milk, cow, whole, fresh,
raw", "Orange Juice", "Butter (cow milk), salted", "Salt, Iodized", "Egg,
chicken, whole, raw", "Tomato, red, ripe, raw", "Mushroom, fresh, raw",
"Parsley, fresh, raw"), "CART B (mcg)" = c(NA, 105, "", 130, NA, "", 111, NA,
112, 101), "CART A (mcg)" = c(0, 35, 23, 27, 6, 34, NA, 18, "", 40), "CRYPXB
(mcg)" = c(110, 67, 72, NA, 160, 102, 98, 37, 28, 60), "CART B eq (std) (mcg)"
= c("", 107, 102, NA, "", NA, 72, "", "", 143), "CART B eq (mcg)" = c(159,
103, 132, NA, "", "", "", 78, NA, 92), "Vit A RAE (mcg)" = c(13, 8, NA, 15,
13, NA, NA, NA, 7, 10), "Vit A (mcg)" = c(12, 11, 8, 13, 3, 1, 10, 15, 3, 6),
"Retinol (mcg)" = c(0, 7, 12, NA, 5, 2, 10, 6, "", 1), "comments" = c(
"Imaginary values", "Completely fictional values", "Fictional values #2",
"More fictional values", "Fictional #4", "Fictional no. 5", "fictional 6",
"more fiction", "again, fiction", "Fictional number 9" ), check.names = FALSE)

#In this case the data.frame we want to run through is called test_df.
#However the standard INFOODS names haven't been used, so the assumed nutrient
#column names won't work, and they will have to be manually assigned. However,
#the comment column is named the default name (comments) and so even if left
#out will still be valid.

output_df <- CARTBEQ_standardised(df = test_df, item_ID = 'ID', CARTAmcg =
'CART A (mcg)', CARTBmcg = 'CART B (mcg)', CARTBEQmcg = 'CART B eq (mcg)',
CARTBEQmcg_std = 'CART B eq (std) (mcg)',  CRYPXBmcg = 'CRYPXB (mcg)',
VITAmcg = 'Vit A (mcg)',  VITA_RAEmcg = 'Vit A RAE (mcg)',  RETOLmcg =
'Retinol (mcg)')
#> Item test_01 CARTBEQ_standardised calculated to be 159mcg. CARTBEQ_standardised compiled from previous CARTBEQmcg value.
#> Item test_02 CARTBEQ_standardised calculated to be 107mcg. CARTBEQ_standardised compiled from previous CARTBEQmcg_std value.
#> Item test_03 CARTBEQ_standardised calculated to be 102mcg. CARTBEQ_standardised compiled from previous CARTBEQmcg_std value.
#> Item test_04 CARTBEQ_standardised calculated to be 130mcg. CARTBEQ_standardised compiled from previous CARTBmcg value.
#> Item test_05 CARTBEQ_standardised calculated to be 96mcg. CARTBEQ_standardised calculated from VITA_RAE and RETOL.
#> Item test_06 CARTBEQ_standardised calculated to be 0mcg. CARTBEQ_standardised calculated from VITA and RETOL - recalculated_CARTBEQmcg_std calculated to be less than 0. Value reset to 0.
#> Item test_07 CARTBEQ_standardised calculated to be 72mcg. CARTBEQ_standardised compiled from previous CARTBEQmcg_std value.
#> Item test_08 CARTBEQ_standardised calculated to be 78mcg. CARTBEQ_standardised compiled from previous CARTBEQmcg value.
#> Item test_09 CARTBEQ_standardised calculated to be 112mcg. CARTBEQ_standardised compiled from previous CARTBmcg value.
#> Item test_10 CARTBEQ_standardised calculated to be 143mcg. CARTBEQ_standardised compiled from previous CARTBEQmcg_std value.

#The resulting output will have a modified comments column, and a new column -
#recalculated_CARTBEQmcg_std