Merge pull request #17 from lshtm-gigs/dev

gigs 0.3.0

README.md

@@ -4,11 +4,11 @@
 <!-- badges: end -->
 
 ## About
-Produced as part of the Guidance for International Growth Standards (GIGS) project, 
-`gigs` provides a single, simple interface for working with the WHO Child Growth
-Standards and outputs from the INTERGROWTH-21<sup>st</sup> project. You will 
-find functions for converting between anthropometric measures (e.g. weight or 
-length) to z-scores and percentiles, and the inverse. Also included are 
+Produced as part of the Guidance for International Growth Standards (GIGS) 
+project, `gigs` provides a single, simple interface for working with the WHO 
+Child Growth Standards and outputs from the INTERGROWTH-21<sup>st</sup> project.
+You will find functions for converting between anthropometric measures (e.g. 
+weight or length) to z-scores and centiles, and the inverse. Also included are 
 functions for classifying newborn and infant growth according to 
 literature-based cut-offs.
 
@@ -40,15 +40,15 @@ files.
   Component standards
   </summary>
 
-  | Acronym  | Description                                | Unit  | `gest_age()` range |
-  |----------|--------------------------------------------|-------|--------------------|
-  | `wfga`   | Weight-or-gestational age                  | kg    | 168 to 300 days    |
-  | `lfga`   | Length-for-gestational age                 | cm    | 168 to 300 days    |
-  | `hcfga`  | Head circumference-for-gestational age     | cm    | 168 to 300 days    |
-  | `wlrfga` | Weight-to-length ratio-for-gestational age | kg/cm | 168 to 300 days    |
-  | `ffmfga` | Fat-free mass-for-gestational age          | kg    | 266 to 294 days    |
-  | `bfpfga` | Body fat percentage-for-gestational age    | %     | 266 to 294 days    |
-  | `fmfga`  | Fat mass-for-gestational age               | kg    | 266 to 294 days    |
+  | Acronym  | Description                                | Unit  | `gest_days()` range |
+  |----------|--------------------------------------------|-------|---------------------|
+  | `wfga`   | Weight-or-gestational age                  | kg    | 168 to 300 days     |
+  | `lfga`   | Length-for-gestational age                 | cm    | 168 to 300 days     |
+  | `hcfga`  | Head circumference-for-gestational age     | cm    | 168 to 300 days     |
+  | `wlrfga` | Weight-to-length ratio-for-gestational age | kg/cm | 168 to 300 days     |
+  | `ffmfga` | Fat-free mass-for-gestational age          | kg    | 266 to 294 days     |
+  | `bfpfga` | Body fat percentage-for-gestational age    | %     | 266 to 294 days     |
+  | `fmfga`  | Fat mass-for-gestational age               | kg    | 266 to 294 days     |
 
   </details>
 - `ig_png` - INTERGROWTH-21<sup>st</sup> standards for postnatal growth in
@@ -78,8 +78,8 @@ files.
   | `bfa`   | BMI-for-age                  | kg/m<sup>2</sup> | 0 to 1856 days  |
   | `lhfa`  | length/height-for-age        | cm               | 0 to 1856 days  |
   | `hcfa`  | head circumference-for-age   | cm               | 0 to 1856 days  |
-  | `wfl`   | weight-for-height            | kg               | 45 to 110 cm    |
-  | `wfh`   | weight-for-length            | kg               | 65 to 120 cm    |
+  | `wfl`   | weight-for-length            | kg               | 45 to 110 cm    |
+  | `wfh`   | weight-for-height            | kg               | 65 to 120 cm    |
   | `acfa`  | arm circumference-for-age    | cm               | 91 to 1856 days |
   | `ssfa`  | subscapular skinfold-for-age | mm               | 91 to 1856 days |
   | `tsfa`  | triceps skinfold-for-age     | mm               | 91 to 1856 days |
@@ -90,27 +90,29 @@ files.
 Each conversion function has similar syntax. The main function call determines
 the set of standards in use, the `acronym` parameter specifies which component 
 standard is being used, and the `conversion` parameter specifies the type of 
-conversion you wish to perform. The `sex()` and `sexcode()` options are used to 
-give the function sex data - as the growth standards are sex-specific, the
-standards cannot be applied correctly without this information.
+conversion you wish to perform. This `conversion` parameter can take one of four
+values: `"v2z"` (value-to-z-score), `"v2c"` (value-to-centile), `"z2v"` 
+(z-score-to-value), `"c2v"` (centile-to-value). The `sex()` and `sexcode()` 
+options are used to  give the function sex data - as the growth standards are 
+sex-specific, the standards cannot be applied correctly without this information.
 
 ### INTERGROWTH-21<sup>st</sup> Newborn Size standards, including very preterm
 This function can be used to convert between measurements and 
-z-scores/percentiles in each of the INTERGROWTH-21<sup>st</sup> Newborn Size
+z-scores/centiles in each of the INTERGROWTH-21<sup>st</sup> Newborn Size
 Standards. 
 
 ![](./readme/readme_ignbs.png)
 
 ### INTERGROWTH-21<sup>st</sup> Postnatal Growth standards
 This function can be used to convert between measurements and 
-z-scores/percentiles in each of the INTERGROWTH-21<sup>st</sup> Postnatal 
+z-scores/centiles in each of the INTERGROWTH-21<sup>st</sup> Postnatal 
 Growth of Preterm Infants Standards.
 
 ![](./readme/readme_igpng.png)
 
 ### WHO Child Growth Standards
 This function can be used to convert between measurements and 
-z-scores/percentiles in each of the WHO Child Growth Standards.
+z-scores/centiles in each of the WHO Child Growth Standards.
 
 ![](./readme/readme_whogs.png)
 
@@ -121,7 +123,8 @@ cut-offs. These publications are discussed in the attached [paper]().
 #### Size for gestational age
 ![](./readme/readme_csga.png)
 
-This function outputs a variable with the following values and labels:
+This function outputs a variable with the following values and labels. Severely
+SGA infants are only labelled if the `severe` option is specified:
 
 | Value | Meaning                               | Centile range                      |
 |-------|---------------------------------------|------------------------------------|
@@ -130,10 +133,26 @@ This function outputs a variable with the following values and labels:
 | 0     | Appropriate for gestational age (AGA) | 10<sup>th</sup> to 90<sup>th</sup> |
 | 1     | Large for gestational age (LGA)       | \>90<sup>th</sup>                  |
 
+#### Small vulnerable newborns
+![](./readme/readme_csvn.png)
+
+This function outputs a variable with the following values and labels:
+
+| Value | Meaning     | Term Status | Centile range                      |
+|-------|-------------|-------------|------------------------------------|
+| -4    | Preterm SGA | Preterm     | <10<sup>th</sup>                   |
+| -3    | Preterm AGA | Preterm     | 10<sup>th</sup> to 90<sup>th</sup> |
+| -2    | Preterm LGA | Preterm     | \>90<sup>th</sup>                  |
+| -1    | Term    SGA | Term        | <10<sup>th</sup>                   |
+| 0     | Term    AGA | Term        | 10<sup>th</sup> to 90<sup>th</sup> |
+| 1     | Term    LGA | Term        | \>90<sup>th</sup>                  |
+
+
 #### Stunting
 ![](./readme/readme_cstunting.png)
 
-The function outputs a variable with the following values and labels:
+The function outputs a variable with the following values and labels. Outlier
+observations are only labelled if the `outliers` option is specified:
 
 | Value | Meaning         | Z-score range |
 |-------|-----------------|---------------|
@@ -145,7 +164,8 @@ The function outputs a variable with the following values and labels:
 #### Wasting
 ![](./readme/readme_cwasting.png)
 
-The function outputs a variable with the following values and labels:
+The function outputs a variable with the following values and labels. Outlier
+observations are only labelled if the `outliers` option is specified:
 
 | Value | Meaning        | Z-score range |
 |-------|----------------|---------------|
@@ -158,7 +178,8 @@ The function outputs a variable with the following values and labels:
 #### Weight-for-age
 ![](./readme/readme_cwfa.png)
 
-The function outputs a variable with the following values and labels:
+The function outputs a variable with the following values and labels. Outlier
+observations are only labelled if the `outliers` option is specified:
 
 | Value | Meaning              | Z-score range |
 |-------|----------------------|---------------|
@@ -283,10 +304,6 @@ remove any observations which were not made at birth. We then use the
 ```
 
 ## Known issues and bug reporting
-For coefficient-based standards (i.e. the `who_gs()` standards and some of the `ig_nbs()`
-standards), providing floats/doubles to the `xvar()` or `gest_age()` options may result 
-in massive slowdowns. This is going to be addressed in a coming update.
-
 We kindly request that users note any bugs, issues, or feature requests on the GitHub 
 [issues page](https://github.com/lshtm-gigs/gigs-stata/issues).
 

_gclassify_sga.ado

@@ -1,6 +1,6 @@
 capture program drop _gclassify_sga
 capture program drop SGA_Badsyntax
-*! version 0.2.4 (SJxx-x: dmxxxx)
+*! version 0.3.0 (SJxx-x: dmxxxx)
 program define _gclassify_sga
 	version 16
 	preserve
@@ -18,13 +18,14 @@ program define _gclassify_sga
 		error 198
 	}
 
+	syntax [if] [in], GEST_days(varname numeric) sex(varname) SEXCode(string) /*
+		*/ [SEVere by(string)]
+
 	if `"`by'"' != "" {
 		_egennoby classify_sga() `"`by'"'
 		/* NOTREACHED */
 	}
 
-	syntax [if] [in], gest_age(varname numeric) sex(varname) SEXCode(string)
-
 	local 1 `sexcode'
 	*zap commas to spaces (i.e. commas indulged)
 	local 1 : subinstr local 1 "," " ", all
@@ -53,17 +54,23 @@ program define _gclassify_sga
     marksample touse
 
  	tempvar p_temp
-	egen double `p_temp' = ig_nbs(`input', "wfga", "v2p"), ///
-		gest_age(`gest_age') sex(`sex') sexcode(m="`male'", f="`female'")
+	egen double `p_temp' = ig_nbs(`input', "wfga", "v2c"), ///
+		gest_days(`gest_days') sex(`sex') sexcode(m="`male'", f="`female'")
 	qui {
 	    generate `type' `return' = 0
 	    replace `return' = -1 if float(`p_temp') < 0.1
 	    replace `return' = 1 if float(`p_temp') > 0.9
-	    replace `return' = -2 if float(`p_temp') < 0.03
 	    replace `return' = . if `p_temp' == . | `touse' == 0
-	} 
-	capture label define sga_labels -2 "severely SGA" -1 "SGA" 0 "AGA" 1 "LGA"
-	label values `return' sga_labels
+	}
+	cap la de sga_labels -1 "SGA" 0 "AGA" 1 "LGA"
+	cap la de sev_sga_labels -2 "severely SGA" -1 "SGA" 0 "AGA" 1 "LGA"
+	if "`severe'"=="" {
+		la val `return' sga_labels
+	}
+	else {
+		replace `return' = -2 if float(`p_temp') < 0.03
+	    la val `return' sev_sga_labels
+	}
 	restore, not
 end
 

_gclassify_stunting.ado

@@ -1,5 +1,5 @@
 capture program drop _gclassify_stunting
-*! version 0.2.4 (SJxx-x: dmxxxx)
+*! version 0.3.0 (SJxx-x: dmxxxx)
 program define _gclassify_stunting
 	version 16
 	preserve
@@ -16,15 +16,15 @@ program define _gclassify_stunting
 	if `"`paren'"' != ")" {
 		error 198
 	}
-
+
+	syntax [if] [in], GEST_days(varname numeric) age_days(varname numeric) /*
+		*/ sex(varname) SEXCode(string) [OUTliers BY(string)]
+
 	if `"`by'"' != "" {
 		_egennoby classify_stunting() `"`by'"'
 		/* NOTREACHED */
 	}
-
-	syntax [if] [in], GA_at_birth(varname numeric) age_days(varname numeric) /*
-		*/ lenht_method(varname) LENHTCode(string) sex(varname) SEXCode(string) 
-
+
 	local 1 `sexcode'
 	local 1 : subinstr local 1 "," " ", all
 	tokenize `"`1'"', parse("= ")
@@ -48,79 +48,43 @@ program define _gclassify_stunting
  		local female "`3'"
  	} 
 	else StuntingSex_Badsyntax	
-
-	local 2 `lenhtcode'
-	local 2 : subinstr local 2 "," " ", all
-	tokenize `"`2'"', parse("= ")
-
- 	if "`1'" == substr("length", 1, length("`1'")) {
-		if "`2'" ~= "=" | "`5'" ~= "=" | /*
-		*/ "`4'" ~= substr("height", 1, length("`4'")) | /*
-		*/ "`7'" ~= "" {
- 			StuntingLenht_Badsyntax
- 		}
- 		local length "`3'"
-  		local height "`6'"
-	} 
-	else if "`1'" == substr("height", 1, length("`1'")) {
-	    if "`2'" ~= "=" | "`5'" ~= "=" | /*
- 		*/ "`4'" ~= substr("length", 1, length("`4'") | /*
- 		*/ "`7'" ~= "" {
- 			StuntingLenht_Badsyntax
- 		}
- 		local length "`6'"
- 		local height "`3'"
- 	} 
-	else StuntingLenht_Badsyntax
 
 	marksample touse
-
-	tempvar lenht_cm
-	qui {
-		generate double `lenht_cm' = `input'
-		replace `lenht_cm' = `lenht_cm' - 0.7 ///
-			if `age_days' >= 731 & `lenht_method' == "`length'"
-		replace `lenht_cm' = `lenht_cm' + 0.7 ///
-			if `age_days' < 731 & `lenht_method' == "`height'"
-	}
-
 	tempvar pma_weeks z_PNG z_WHO z
 	qui {
-		gen double `pma_weeks' = round((`age_days' + `ga_at_birth') / 7)
-		egen double `z_PNG' = ig_png(`lenht_cm', "lfa", "v2z"), ///
+		gen double `pma_weeks' = floor((`age_days' + `gest_days') / 7)
+		egen double `z_PNG' = ig_png(`input', "lfa", "v2z"), ///
 			xvar(`pma_weeks') sex(`sex') sexcode(m="`male'", f="`female'")
-		egen double `z_WHO' = who_gs(`lenht_cm', "lhfa", "v2z"), ///
+		egen double `z_WHO' = who_gs(`input', "lhfa", "v2z"), ///
 			xvar(`age_days') sex(`sex') sexcode(m="`male'", f="`female'")
 
 		gen double `z' = `z_PNG' if ///
-		    `ga_at_birth' >= 182 & `ga_at_birth' < 259 & ///
-			`pma_weeks' >= 27 & `pma_weeks' < 64 
-		replace `z' = `z_WHO' if ///
-			`ga_at_birth' < 182 | `ga_at_birth' >= 259 | `pma_weeks' < 27 | ///
-			`pma_weeks' >= 64
+		    `gest_days' >= 182 & `gest_days' < 259 & ///
+			`pma_weeks' >= 27 & `pma_weeks' <= 64
+		replace `z' = `z_WHO' if `gest_days' >= 259 | ///
+		    (`gest_days' < 259 & `pma_weeks' > 64)
 
 		generate `type' `return' = .
 		replace `return' = -1 if float(`z') <= -2
 		replace `return' = -2 if float(`z') <= -3
-		replace `return' = -10 if float(`z') < -6
 		replace `return' = 0 if float(`z') > -2
-		replace `return' = -10 if float(`z') > 6
 		replace `return' = . if `z' == . | `touse' == 0
 	}
-	capture label define stunting_labels -10 "implausible" ///
-	   -2 "severe stunting"  -1 "stunting" 0 "normal"
-	label values `return' stunting_labels
+	cap la de stunting_labs -2 "severe stunting" -1 "stunting" 0 "normal"
+	cap la de stunting_labs_out -2 "severe stunting" -1 "stunting" 0 "normal" /*
+	    */ 999 "outlier"
+	if "`outliers'"=="" {
+		la val `return' stunting_labs
+	}
+	else  {
+		qui replace `return' = 999 if abs(float(`z')) > 6 & `return' != .
+		la val `return' stunting_labs_out
+	}
 	restore, not
 end
 
 capture prog drop StuntingSex_Badsyntax
 program StuntingSex_Badsyntax
 	di as err "sexcode() option invalid: see {help ig_nbs}"
 	exit 198
-end
-
-capture prog drop StuntingLenht_Badsyntax
-program StuntingLenht_Badsyntax
-	di as err "lenhtcode() option invalid: see {help classify_stunting}"
-	exit 198
 end