Compute Actual Nutrient Intake from 24h Recall Data

This function computes actual nutrient intakes at either the food-level or recall-level using reported gram intakes from 24-hour dietary recall data. It multiplies reported intakes by nutrient composition values (per 100g edible portion) from either the built-in food composition database (fct_db) from the dietracallkitR repository or a user-supplied nutrient mapping table. Intakes are adjusted for edible conversion factors (ECF) and reported food gram weights.

Usage

compute_actual_nutrient_intake(
  recall_data,
  id_col,
  recall_col,
  food_item_col,
  actual_gram_intake_col = "actual_gram_intake",
  use_fct_db = FALSE,
  nutrient_map_data = NULL,
  nutrient_map_food = NULL,
  ecf_col = NULL,
  nutrient_cols = NULL,
  output_level = c("recall_level", "food_level")
)

Arguments

recall_data

A data frame containing at least an ID column, a recall column, a food item column, and a numeric gram intake column.

id_col

Character string. Column name in recall_data identifying survey respondents or household IDs.

recall_col

Character string. Column name in recall_data identifying the recall occasion.

food_item_col

Character string. Column name in recall_data containing reported food items.

actual_gram_intake_col

Character string. Column name in recall_data containing numeric gram intakes (default "actual_gram_intake").

use_fct_db

Logical. If TRUE, mapping is automatically pulled from the built-in food composition database (fct_db). Cannot be used simultaneously with nutrient_map_data. Default is FALSE.

nutrient_map_data

Optional. A user-supplied nutrient database (must contain per-100g values). Required if use_fct_db = FALSE.

nutrient_map_food

Character string. Column name in nutrient_map_data containing food item names.

ecf_col

Character string. Column name in nutrient database for edible conversion factor. Default "Edible conversion factor".

nutrient_cols

Character vector of nutrient columns (per 100g edible portion) to calculate actual intakes for. If use_fct_db = TRUE, defaults to a hardcoded set of nutrient columns from the built-in database.

output_level

Character string, either "recall_level" (default) or "food_level". indicating whether the output should be aggregated by recall or left at the food item level for debugging purposes.

Value

A tibble with nutrient intakes per recall (default) or per food item (if output_level = "food_level"). Columns include:

• Food-level output: nutrient intakes per food item within each recall.

• Recall-level output: total nutrient intakes per recall.

Details

• Assumes nutrient values in the FCT are expressed per 100g edible portion.

• Actual intakes are computed for each food item per observation as: \((`nutrient_value` x `edible_conversion_factor` x `actual_gram_intake`)/100\).

• Blank nutrient values are treated as NA (missing), not zero. This ensures that missing data is not confused with true zero intake.

• If unmapped food items are found, a warning is issued.

Examples

if (FALSE) { # \dontrun{
# Example with built-in fct_db
recall <- tibble::tibble(
  survey_id = c(1, 1),
  recall_id = c(1, 2),
  food_item = c("Beans, broad, dry, raw", "Orange (chungwa), pulp, raw"),
  actual_gram_intake = c(150, 200)
)

result <- compute_actual_nutrient_intake(
  recall_data   = recall,
  id_col        = "survey_id",
  recall_col    = "recall_id",
  food_item_col = "food_item",
  use_fct_db    = TRUE
)

# Example with custom mapping
recall <- tibble::tibble(
  id = c(1, 1, 2),
  recall_day = c(1, 1, 1),
  food = c("Ugali", "Beans", "Soda"),
  grams = c(200, 50, 300)
)

nutrient_map <- tibble::tibble(
  item = c("Ugali", "Beans", "Soda"),
  ecf = c(1, 1, 1),
  Energy.kcal = c(110, 330, 40), # kcal per 100g
  Protein.g = c(2, 21, 0), # g per 100g
  Fat.g = c(0.5, 1.5, 0) # g per 100g
)

result <- compute_actual_nutrient_intake(
  recall_data = recall,
  id_col = "id",
  recall_col = "recall_day",
  food_item_col = "food",
  actual_gram_intake_col = "grams",
  use_fct_db = FALSE,
  nutrient_map_data = nutrient_map,
  nutrient_map_food = "item",
  ecf_col = "ecf",
  nutrient_cols = c("Energy.kcal", "Protein.g", "Fat.g"),
  output_level = "recall_level"
)
} # }