---
title: "The nutrient modeling R project readme"
author: "Gerald C. Nelson"
date: "April 17, 2016"
output: word_document
---

# The nutrient modeling R project
The goal of this R project is to provide estimates of the nutritional consequences of changes arising in scenarios of both socioeconomic and climate futures. It integrates data from 

* FAO's Food Balance Sheets, 
* the Shared Socioeconomic Profiles used in the IPCC's Fifth Assessment Report and many other studies, 
* quantitative scenario modeling results from IFPRI's IMPACT model,
* a lookup table that is used to convert food consumption by a representative consumer in a country (including optionally a measure of nutrient loss during food preparation) to it macro and micro constituents, and 
* age- and gender-adjusted nutrient requirements.

The latest versions of the code and most of the data are at <https://github.com/GeraldCNelson/nutmod>

# Directory structure
The directory hierarchy of the project is as follows. Second level directories are in parentheses:
* data (IMPACTData) --- contains .xlsx and .rds files generated by the dataPrep and dataManagement R scripts
* data---raw (FBSData, IMPACTData, NutrientData, SSPData) --- data files from FAO, SSP, IMPACT, the nutrient lookup table
* R --- R scripts
* Results --- results from the analysis, contains .xlsx and .rds files

# R code file naming conventions
All R code is in the R directory. File naming conventions are:
* dataPrep.xxx.R --- reads in the raw data from the data---raw directory and processes it into .rds (and sometimes .xlsx) files and writes these to the data or IMPACTData directory
* dataManagement.xxx.R --- reads in .rds data files from the data or IMPACTData directory, does more processing and writes writes these to the data or IMPACTData directory.
* xxxFunctions.R --- has generic functions used in the xxx R scripts. A special functions script is nutrientModFunctions.R. In addition to R functions it holds the names of key variables such as file names and directory paths. All other scripts read this information in with functions from this script.

* nutrientCalcs.R --- all final calculations are (currently) done in this script.

# Results files
All file names have a standard format --- shortName, creation date, suffix. An example is metaData.2016-04-17.xlsx.

* suffix --- .xlsx or .rds (a compressed file format used in R)

## shortNames
   + General --- metaData, nut.requirements, food.group, staples
   + requirements --- req.EARxxx, req.RDA.vitsxxx, req.RDA.minrls, req.RDA.macroxxx, req.UL.vitsxxx,req.UL.minrlsxxx
   + type of results --- ratio of nutrient consumption by commodity/staple/food group to total consumption, ratio of nutrient consumption by commodity/staple/food group to requirement 

# Variable naming conventions
* scenario --- name of the IMPACT scenario, currently SSP2-GFDL, SSP2-MIROC, SSP2-NoCC
* region --- the aggregation from individual countries to larger regions. Currently region_code.IMPACT3
* year --- 4 digit year with an X to start with so it is a character value. Example - X2020
* IMPACT_code --- a 4 or 5 digit code for each of the IMPACT commodities. Example - cwhea - the quantity of wheat consumed by a representative consumer
* food.group.code --- the code for a food group. Example - cereals.
* staple.code --- the code for a food group. Example - staple
* foodAvailpDay --- the per capita quantity of an IMPACT commodity available for consumption by a representative consumer. Units - kg/day
* nutrient.code --- a nutrient code combines the common name of the nutrient and the units it is in. Example - folate_µg"   
* nutrient.Q --- the quantity of a nutrient available from an IMPACT commodity per day
* nutrient.sum [.all, .staple, .foodGroup] --- The sum of nutrient.Q for all commodities, for each staple group, for each food group.
* nutrient.ratio [.all, .staple, .foodGroup] --- The ratio of a nutrient to the total consumed
* nutrient.req.ratio [.all, .staple, .foodGroup] --- The ratio of a nutrient to the the daily requirement