Title: | Naomi Model for Subnational HIV Estimates |
---|---|
Description: | This package implements the Naomi model for subnational HIV estimates. |
Authors: | Jeff Eaton [aut, cre] |
Maintainer: | Jeff Eaton <[email protected]> |
License: | MIT + file LICENSE |
Version: | 2.9.28 |
Built: | 2024-10-07 10:19:22 UTC |
Source: | https://github.com/mrc-ide/naomi |
Add labels to output indicators
add_output_labels(naomi_output, geometry = FALSE)
add_output_labels(naomi_output, geometry = FALSE)
naomi_output |
Naomi output object. |
geometry |
logical whether to include geometry from meta_area. |
Labelled output indicators
Plotly barplot comparing age distribution of survey inputs and naomi outputs
age_bar_plotly(df, ind, quarter)
age_bar_plotly(df, ind, quarter)
df |
Inputs_outputs dataframe containing matched model estimates and data inputs. |
ind |
Indicator filter. |
quarter |
Calendar quarter filter. |
Take ANC and shape file paths or data files and aggregate art_current according to area hierarchy provided
aggregate_anc(anc, shape)
aggregate_anc(anc, shape)
anc |
Path to file containing ANC data or ANC data object |
shape |
Path to file containing geojson areas data or areas data object |
Aggregated ANC data containing columns area_id, area_name, area_level, area_level_label, sex,age_group, time_period, year, quarter, calendar_quarter, anc_clients, anc_known_neg, anc_already_art, anc_tested and anc_tested_pos, births_clients_ratio
Take ART and shape file paths or files and aggregate art_current according to area hierarchy provided
aggregate_art(art, shape)
aggregate_art(art, shape)
art |
Path to file containing ART data or ART data object |
shape |
Path to file containing geojson areas data or areas data object |
Aggregated ART data containing columns area_id, area_name, area_level, area_level_label, parent_area_id, sex, age_group, time_period, year, quarter,calendar_quarter and art_current
Align model data inputs and model estimates
align_inputs_outputs(naomi_data, indicators, meta_area)
align_inputs_outputs(naomi_data, indicators, meta_area)
naomi_data |
Naomi object of class "naomi_data" and "naomi_mf" |
indicators |
Naomi indicators created by |
meta_areas |
Prepare Model Frames for Programme Datasets
anc_testing_prev_mf(year, anc_model_mf) anc_testing_artcov_mf(year, anc_model_mf) anc_testing_clients_mf(year, anc_model_mf)
anc_testing_prev_mf(year, anc_model_mf) anc_testing_artcov_mf(year, anc_model_mf) anc_testing_clients_mf(year, anc_model_mf)
year |
Calendar year |
anc_testing |
ART data frame |
naomi_mf |
Naomi model frame |
Calculated prevalence
Build artnum model frame
artnum_mf(calendar_quarter, art_number, naomi_mf)
artnum_mf(calendar_quarter, art_number, naomi_mf)
calendar_quarter |
Calendar quarter |
Number on ART at desired quarter are linearly interpolated within the dataset. If the desired quarter is before the earliest data, the first value may be carried back by up to one year (four quarters). Data are never carried forward
Check whether PJNZ contains .shiny90 file
assert_pjnz_shiny90(pjnz)
assert_pjnz_shiny90(pjnz)
pjnz |
file path to PJNZ |
Logical whether PJNZ file contains a .shiny90 file
Plotly barplot comparing geographical distribution of data inputs and naomi outputs
bar_plotly(df, ind, quarter, age_disag = "Y015_049", sex_disag = "both")
bar_plotly(df, ind, quarter, age_disag = "Y015_049", sex_disag = "both")
df |
Inputs_outputs dataframe containing matched model estimates and data inputs. |
ind |
Indicator filter. |
quarter |
Calendar quarter filter. |
age_disag |
Age group filter. |
sex_disag |
Sex filter. |
Return the translated label & description for a set of plot types
build_hierarchy_label(meta_areas)
build_hierarchy_label(meta_areas)
meta_areas |
dataframe containing |
For each plot type the label and description as a list of lists containing id, label and description
Calculate prevalence and ART coverage from ANC input data
calculate_prevalence_art_coverage(data)
calculate_prevalence_art_coverage(data)
data |
Data frame of input ANC data |
Data frame with prevalence and ART coverage
Calibrate naomi model outputs
calibrate_outputs( output, naomi_mf, spectrum_plhiv_calibration_level, spectrum_plhiv_calibration_strat, spectrum_artnum_calibration_level, spectrum_artnum_calibration_strat, spectrum_aware_calibration_level, spectrum_aware_calibration_strat, spectrum_infections_calibration_level, spectrum_infections_calibration_strat, calibrate_method = "logistic" )
calibrate_outputs( output, naomi_mf, spectrum_plhiv_calibration_level, spectrum_plhiv_calibration_strat, spectrum_artnum_calibration_level, spectrum_artnum_calibration_strat, spectrum_aware_calibration_level, spectrum_aware_calibration_strat, spectrum_infections_calibration_level, spectrum_infections_calibration_strat, calibrate_method = "logistic" )
output |
Naomi model output package produced by |
naomi_mf |
Naomi model frame, objective of class |
spectrum_plhiv_calibration_level |
Level to calibrate PLHIV, see details. |
spectrum_plhiv_calibration_strat |
Age/sex stratification to calibrate PLHIV, see details. |
spectrum_artnum_calibration_level |
Level to calibrate number on ART, see details. |
spectrum_artnum_calibration_strat |
Age/sex stratification to calibrate number on ART, see details. |
spectrum_aware_calibration_level |
Level to calibrate number aware of HIV positive status, see details. |
spectrum_aware_calibration_strat |
Age/sex stratification to calibrate number aware of HIV positive status, see details. |
spectrum_infections_calibration_level |
Level to calibrate number infections of HIV positive status, see details. |
spectrum_infections_calibration_strat |
Age/sex stratification to calibrate number infections of HIV positive status, see details. |
calibrate_method |
Calibration method, either |
The following indicators are calibrated:
plhiv
art_current_residents
unaware_plhiv_num
infections
art_current
(attending)
aware_plhiv_num
untreated_plhiv_num
prevalence
art_coverage
aware_plhiv_prop
incidence
plhiv_attend
aware_plhiv_attend
Steps in the calibration:
Aggregate Spectrum totals to specified stratification by level/sex/age to calculate the target totals within each stratification.
Adjust fine area/sex/age-group mean values to match targeted total using either "logistic" or "proportional" scaling.
Aggregate revised mean count values to all stratifications of Naomi outputs.
Calculate calibrated mean for proportion indicators.
Adjust outputs for all statistics (mean, median, mode, se, range).
Aggregate totals spectrum_calibration table.
The "logistic" scaling method converts fine counts to logit proportions, then uses numerical optimisation to solve the logit-scale adjustment to the fine district/sex/age proportions such that the adjusted proportions times the denominator sums to the target value.
Calibration proceeds sequentially through the following indicators.
PLHIV
Number of residents on ART
Number unaware of HIV status
Number of new infections
Number of attending ANC by district
Calibration of a previous indicator may affect the denominator for the next indicator. This does not affect the calculation for proportional scaling, but will affect logistic scaling. Inconsistent selections for calibration levels or stratifications could result in a denominator smaller than a target numerator for a particular value. This will throw an error for logistic scaling methods.
The number of attending ARG clients is always calibrated proportionally by sex and five-year age group to the number or residents attending.
Converts a date to DHS Century Month Code (CMC).
cmc_date(date)
cmc_date(date)
date |
a Date vector |
CMC date is defined as the number of months since 1900:
an integer vector of CMC dates
https://dhsprogram.com/Data/Guide-to-DHS-Statistics/Organization_of_DHS_Data.htm?rhtocid=_4_2_0#Structure_of_DHS_Databc-1
cmc_date(Sys.Date()) cmc_date(as.Date("1987-02-11", format = "%Y-%m-%d"))
cmc_date(Sys.Date()) cmc_date(as.Date("1987-02-11", format = "%Y-%m-%d"))
Create adjacency matrix from spatial polygons
create_adj_matrix(sh)
create_adj_matrix(sh)
sh |
a spatial polygons object |
Input sh
can be either sf
class or SpatialPolygons from sp
. Uses spdep
package to convert shapefile to neighbor list to adjacency matrix.
an adjacency matrix with 1s and 0s
Long data frame mapping area hierarchy areas to model level areas
create_area_aggregation(model_area_ids, areas, drop_partial_areas = TRUE)
create_area_aggregation(model_area_ids, areas, drop_partial_areas = TRUE)
model_area_ids |
vector of model areas. |
areas |
naomi_areas object. |
drop_partial_areas |
Drop areas from output if some children are missing (default TRUE). |
area_merged <- read_area_merged(system.file("extdata/demo_areas.geojson", package = "naomi")) areas <- create_areas(area_merged = area_merged) model_area_ids <- area_merged$area_id[area_merged$area_level == 4] create_area_aggregation(model_area_ids, areas)
area_merged <- read_area_merged(system.file("extdata/demo_areas.geojson", package = "naomi")) areas <- create_areas(area_merged = area_merged) model_area_ids <- area_merged$area_id[area_merged$area_level == 4] create_area_aggregation(model_area_ids, areas)
Constructs and validates an areas object as an S3 class.
create_areas( levels = NULL, hierarchy = NULL, boundaries = NULL, area_merged = NULL )
create_areas( levels = NULL, hierarchy = NULL, boundaries = NULL, area_merged = NULL )
levels |
Data frame of area level metadata. |
hierarchy |
Data frame defining area hierarchy and area-level data. |
boundaries |
an |
area_merged |
A merged version of |
An object of class naomi_areas
data(demo_area_levels) data(demo_area_hierarchy) data(demo_area_boundaries) areas <- create_areas(demo_area_levels, demo_area_hierarchy, demo_area_boundaries) areas
data(demo_area_levels) data(demo_area_hierarchy) data(demo_area_boundaries) areas <- create_areas(demo_area_levels, demo_area_hierarchy, demo_area_boundaries) areas
Create edgelist from adjacency matrix
create_edge_list(adj_matrix)
create_edge_list(adj_matrix)
adj_matrix |
Adjacency matrix |
Wrapper for [cut()]
to return five year age groups with
cut_naomi_age_group(age)
cut_naomi_age_group(age)
age |
a vector of ages. |
a vector of strings with five year age groups.
get_age_groups
Get id to label mapping for calibration plot data type
data_type_labels()
data_type_labels()
List of ID & label mappings
Datasets containing Malawi National HIV programme quarterly reported data about:
Reported number currently on ART.
Number of women receiving antenatal care and final antenatal HIV testing.
demo_anc_testing demo_art_number
demo_anc_testing demo_art_number
TODO: Link to demo_areas dataset
demo_art_number
is a dataset with 2042 observations on the following 5 variables:
area_id
District area id – see demo_areas dataset.
sex
Sex as a character vector – all values are "both".
age_group
Value "Y015_999" is age 15+, "Y000_014" is age 0-14.
calendar_quarter
Calendar quarter.
art_current
Number currently on ART at the end of the quarter.
art_new
Number newly initiated ART during the quarter.
TODO: Link to demo_areas dataset
demo_anc_testing
is a dataset with 923 observations on the following 8 variables:
area_id
District area id – see demo_areas dataset.
quarter_id
Quarter ID (integer).
anc_clients
Number of unique ANC clients during quarter.
anc_known_pos
Number of ANC clients already known to be HIV positive prior to first ANC visit and not tested for HIV.
anc_already_art
Number of ANC clients already on ART prior to first ANC visit.
anc_tested
Number of ANC clients tested for HIV and received result.
anc_tested_pos
Number of ANC clients testing HIV postive.
anc_known_pos
Number of ANC clients not tested for HIV due to documented recent HIV negative status (optional).
births_facility
Number of life births recorded at health facilities..
An object of class tbl_df
(inherits from tbl
, data.frame
) with 510 rows and 10 columns.
Data are sourced from quarterly reporting spreadsheets produced via the Quarterly Integrated HIV Program Reports and publicly available from Malawi Ministry of Health: Department of HIV & AIDS website.
Data are provided by the Ministry of Health, Malawi with the following disclaimer:
The data in this file are owned by the Ministry of Health (MOH), Malawi.
These data are shared in order to support the National HIV Program.
Data in this file may not be used by Third Parties for further analysis and dissemination without prior written approval of the Director of the Department for HIV and AIDS, MOH.
Patient-level data are routinely collected by health facility staff using standard monitoring tools. This file contains facility-level aggregates that have been generated by facility staff and that were verified from primary records during quarterly National HIV Program Supervision (coordinated of the Department of HIV and AIDS). While every effort is made to ensure high data quality, individual records may not be complete and accurate.
The official interpretation of these data is presented in Quarterly Integrated HIV Program Reports and any divergent interpretation may be misleading and is not supported by the MOH. Analysis and interpretation of the data requires detailed understsanding of the methods and constraints of the Malawi's National M&E System.
The number of ART by age 0-14 and age 15+ is not reported in aggregate quarterly reporting data. For model illustration purposes, this is approximated as 94% of all ART clients are age 15+ based on Spectrum model outputs which were validated against age distributions from electronic medical records by the Malawi HIV estimates team.
Dataset could contain one observation per district per quarter for all 32 districts for all quarters between Q3 2011 and Q3 2018, but the number of observations is fewer than 32 * 29 = 928 due to a few missing observations.
Department of HIV & AIDS, Minitry of Health, Malawi. http://hiv.health.gov.mw/index.php/our-documents
quarter_labels
, get_age_groups
.
Malawi area boundaries.
demo_area_boundaries
demo_area_boundaries
sf object representing area boundaries
Malawi
Malawi area hierarchy
demo_area_hierarchy
demo_area_hierarchy
Data frame
Malawi
Malawi area levels.
demo_area_levels
demo_area_levels
Data frame
Malawi
Malawi age-sex stratified population data
demo_population_agesex
demo_population_agesex
Data frame
Malawi
Malawi survye biomarkers
demo_survey_biomarker
demo_survey_biomarker
Data frame
Malawi
Malawi survey clusters
demo_survey_clusters
demo_survey_clusters
Data frame
Malawi
Malawi HIV indicators
demo_survey_hiv_indicators
demo_survey_hiv_indicators
Data frame
Malawi
Malawi survey individuals
demo_survey_individuals
demo_survey_individuals
Data frame
Malawi
Malawi survey metadata
demo_survey_meta
demo_survey_meta
Data frame
Malawi
Malawi survey regions
demo_survey_regions
demo_survey_regions
Data frame
Malawi
Disaggregate output indicators for the 0-4 age group proportional to Spectrum distribution for each age group.
disaggregate_0to4_outputs(output, naomi_mf)
disaggregate_0to4_outputs(output, naomi_mf)
output |
a |
naomi_mf |
a |
Create district bar plot
district_barplot( naomi_output, indicator, age, sex_disag, level = NULL, calendar_quarter = 2, label_format, x_title = NULL, fig_title = NULL, legend_title = NULL, colour_palette = "blue", above_label = t_("ABOVE"), below_label = t_("BELOW") )
district_barplot( naomi_output, indicator, age, sex_disag, level = NULL, calendar_quarter = 2, label_format, x_title = NULL, fig_title = NULL, legend_title = NULL, colour_palette = "blue", above_label = t_("ABOVE"), below_label = t_("BELOW") )
naomi_output |
Naomi output object or path to naomi output zip folder |
indicator |
Indicator to plot |
age |
Age group to plot |
sex_disag |
Sexes to plot |
level |
Area level to plot, default all |
calendar_quarter |
Naomi projection quarter to filter data to, default is calendar_quarter_t2 |
label_format |
Label format for y labels |
x_title |
Title for the figure x axis, blank by default |
fig_title |
Title for the figure, blank by default, |
legend_title |
Title for the legend |
colour_palette |
Names or hexcode value for colours to differentiate districts with values above and below the national average. Can be specified as a preset colour palette using "red", "green" and "blue" or manually as a named list: cols <- c(above_colour = "red", below_colour = "blue"). |
above_label |
Label for districts with values higher than national average, default is "Above" |
below_label |
Label for districts with values higher than national average, default is "Below" |
District barplot
Automatically make drop drop buttons for plotly filter
dropdown_buttons(df, var)
dropdown_buttons(df, var)
df |
Input data frame |
var |
Column |
Drop down buttons for plotly filter
If the .shiny90 file does not exist within the .PJNZ, the function will
silently not return values, even if extract_shiny90 = TRUE
.
extract_pjnz_naomi(pjnz_list, extract_shiny90 = TRUE)
extract_pjnz_naomi(pjnz_list, extract_shiny90 = TRUE)
pjnz_list |
Vector of filepaths to Spectrum PJNZ file. |
extract_shiny90 |
Logical; whether to attempt to extract .shiny90 zip |
A data.frame
with Spectrum indicators.
pjnz <- system.file("extdata/demo_mwi2019.PJNZ", package = "naomi") spec <- extract_pjnz_naomi(pjnz)
pjnz <- system.file("extdata/demo_mwi2019.PJNZ", package = "naomi") spec <- extract_pjnz_naomi(pjnz)
Extract ART and ANC testing program data inputs from Spectrum PJNZ
extract_pjnz_program_data(pjnz_list)
extract_pjnz_program_data(pjnz_list)
pjnz_list |
Vector of filepaths to Spectrum PJNZ file. |
A list with a two data.frame
s of ANC testing data and
number on ART, respectively.
pjnz <- system.file("extdata/demo_mwi2019.PJNZ", package = "naomi") spec <- extract_pjnz_program_data(pjnz)
pjnz <- system.file("extdata/demo_mwi2019.PJNZ", package = "naomi") spec <- extract_pjnz_program_data(pjnz)
Export estimates for proportion aware of status from a Shiny90 output file to five-year age groups 15-19 to 50+.
extract_shiny90_age_sex(shiny90_path, pjnz_path = NULL, years = NULL)
extract_shiny90_age_sex(shiny90_path, pjnz_path = NULL, years = NULL)
shiny90_path |
file path to .shiny90 digest file. |
pjnz_path |
file path to PJNZ file |
years |
year(s) to generate estimates; an integer or a vector of integers. If NULL, all years available in estimates are returned (default). |
The 'artnum' divided by 'plhiv' columns in the output will give a different ART coverage than Spectrum output for the same year because these outputs are based on the internal mid-year ART coverage in Spectrum, while Spectrum reports an end of year (Dec 31) ART coverage.
A data frame consisting of the number of PLHIV, aware of status
and on ART by sex and five year age group 15-49 and age 50+ for
specified years
.
pjnz <- system.file("extdata/demo_mwi2019.PJNZ", package = "naomi") shiny90dir <- tempfile() utils::unzip(pjnz, "malawi.zip.shiny90", exdir = shiny90dir) shiny90_path <- file.path(shiny90dir, "malawi.zip.shiny90") extract_shiny90_age_sex(shiny90_path, pjnz, year = 2010:2019)
pjnz <- system.file("extdata/demo_mwi2019.PJNZ", package = "naomi") shiny90dir <- tempfile() utils::unzip(pjnz, "malawi.zip.shiny90", exdir = shiny90dir) shiny90_path <- file.path(shiny90dir, "malawi.zip.shiny90") extract_shiny90_age_sex(shiny90_path, pjnz, year = 2010:2019)
Fit TMB model
fit_tmb( tmb_input, outer_verbose = TRUE, inner_verbose = FALSE, max_iter = 250, progress = NULL )
fit_tmb( tmb_input, outer_verbose = TRUE, inner_verbose = FALSE, max_iter = 250, progress = NULL )
tmb_input |
Model input data |
outer_verbose |
If TRUE print function and parameters every iteration |
inner_verbose |
If TRUE then disable tracing information from TMB |
max_iter |
maximum number of iterations |
progress |
Progress printer, if null no progress printed |
Fit model.
Return a data frame consisting of master age groups
get_age_groups()
get_age_groups()
data frame
Get a collection of areas defined by a level and nested within a collection of higher level area(s).
get_area_collection(areas, level = NULL, area_scope = NULL)
get_area_collection(areas, level = NULL, area_scope = NULL)
areas |
Data frame representing a valid area hierarchy. |
level |
The level to return area collection |
area_scope |
|
This function recursively expands the area hierarchy to identify all areas in
area_level level
which are nested within areas defined by area_scope
.
If level = NULL
areas are returned at the lowest level of the hierarchy.
An error is thrown if level
is not reflected in the hierarchy.
If area_scope = NULL
all areas at area_level level
are returned. In this case
the recursion is shortcut and simply filters the hierarchy to the desired
level for efficiency, but it is equivalent to initialising the recursion
at the highest level of the hierarchy.
If area_scope
is not null, a column area_scope
is returned indicating the
area in which each returned area is nesteed. area_scope
can accept a vector
of area_id
s and they do not have to be
at the same level. If the level of an area in area_scope
is higher than
area_level level
, nothing is returned. An error is thrown if any area_scope
are not recognized.
TODO: Should be an example - where is demo_areas, demo_area_geom? data(demo_areas, demo_area_geom)
areas <- get_area_collection(demo_areas, level = 3, area_scope = c("MWI.1", "MWI.3.5")) areas %>% left_join(demo_area_geom %>% filter(type == "boundary")) %>% sf::st_as_sf() %>% ggplot() + geom_sf()
Get 5 year age groups
get_five_year_age_groups()
get_five_year_age_groups()
ID for 5 year age groups
get_five_year_age_groups()
get_five_year_age_groups()
Get indicator metadata
get_meta_indicator()
get_meta_indicator()
data.frame of indicator ids, labels, descriptions, and parameter mapping.
get_meta_indicator()
get_meta_indicator()
Get indicator metadata as a data frame
get_metadata()
get_metadata()
Metadata about indicators as a list
Return the translated label & description for a set of plot types
get_plot_type_column_metadata(plot_type)
get_plot_type_column_metadata(plot_type)
plot_type |
Plot type ids |
For each plot type the label and description as a list of lists containing id, label and description
Get plotting metadata for a particular country
get_plotting_metadata(iso3)
get_plotting_metadata(iso3)
iso3 |
iso3 code of country to get metadata for or blank for default configuration. |
List of plotting metadata about how to locate data for a specific indicator, data type and plot type. Also returns metadata about colour scheme to use for that country and indicator.
get_plotting_metadata("MWI")
get_plotting_metadata("MWI")
Interpolate Spectrum to quarter_id
get_spec_aggr_interpolation(spec_aggr, calendar_quarter_out)
get_spec_aggr_interpolation(spec_aggr, calendar_quarter_out)
spec_aggr |
a data from of 5-year age group aggregate Spectrum estimates |
calendar_quarter_out |
calendar quarter for desired output time point |
Take a previously generated hintr_output object and calibrate. Format response as another hintr_output object.
hintr_calibrate( output, calibration_options, plot_data_path = tempfile(fileext = ".qs"), calibrate_output_path = tempfile(fileext = ".qs") )
hintr_calibrate( output, calibration_options, plot_data_path = tempfile(fileext = ".qs"), calibrate_output_path = tempfile(fileext = ".qs") )
output |
A hintr_output object. |
calibration_options |
A set of calibration options |
plot_data_path |
Path to store calibrated output indicators as a qs. |
calibrate_output_path |
Path to store data required for re-calibrating model. |
Calibrated hintr_output object
Takes hintr_output object, reads data and prepares data in format needed for plotting calibrate barchart to compare calibrated, spectrum and unadjusted estimates for a set of indicators.
hintr_calibrate_plot(output)
hintr_calibrate_plot(output)
output |
A hintr_output object |
Calibrated, unadjusted and spectrum estimates of indicators
Takes hintr_output object, reads data and prepares data in format needed for plotting comparison barchart to compare input and output data.
hintr_comparison_plot(output)
hintr_comparison_plot(output)
output |
A hintr_output object |
Calibrated, unadjusted and spectrum estimates of indicators
Prepare AGYW tool download
hintr_prepare_agyw_download(output, pjnz, path = tempfile(fileext = ".xlsx"))
hintr_prepare_agyw_download(output, pjnz, path = tempfile(fileext = ".xlsx"))
pjnz |
Path to input PJNZ file |
path |
Path to save output file |
hintr_output |
object |
Path to output file and metadata for file
Prepare coarse age group download
hintr_prepare_coarse_age_group_download( output, path = tempfile(fileext = ".zip") )
hintr_prepare_coarse_age_group_download( output, path = tempfile(fileext = ".zip") )
output |
hintr output object |
path |
Path to save output file |
Path to output file and metadata for file
Prepare comparison report download
hintr_prepare_comparison_report_download( output, path = tempfile(fileext = ".html") )
hintr_prepare_comparison_report_download( output, path = tempfile(fileext = ".html") )
path |
Path to save output file |
hintr_output |
object |
Path to output file and metadata for file
Prepare spectrum download
hintr_prepare_spectrum_download( output, path = tempfile(fileext = ".zip"), notes = NULL, vmmc_file = NULL )
hintr_prepare_spectrum_download( output, path = tempfile(fileext = ".zip"), notes = NULL, vmmc_file = NULL )
output |
hintr output object |
path |
Path to save output file |
notes |
Optional, user added notes from front end of app as a string |
vmmc_file |
Optional file object, with path, filename and hash for VMMC input |
Path to output file and metadata for file
Prepare summary report download
hintr_prepare_summary_report_download( output, path = tempfile(fileext = ".html") )
hintr_prepare_summary_report_download( output, path = tempfile(fileext = ".html") )
output |
hintr output object |
path |
Path to save output file |
Path to output file and metadata for file
This prepares the model inputs from data and options and saves output as a qs file.
hintr_run_model( data, options, model_output_path = tempfile(fileext = ".qs"), validate = TRUE )
hintr_run_model( data, options, model_output_path = tempfile(fileext = ".qs"), validate = TRUE )
data |
List of paths to input data files. |
options |
List of model run options (see details). |
model_output_path |
Path to store model output as qs. Used in calibrating model and producing output downloads. |
validate |
If FALSE validation of inputs & data will be skipped. |
The data
argument must be a list specifying paths to the following:
pjnz
shape
population
survey data
anc_testing
(optional)
art_number
(optional)
Each item in list can either be a character containing the path to the file or another list of the format:
list( path = "path/to/file", hash = "file_hash", filename = "file" )
The options
argument must be a list specifying minimally:
area_scope
area_level
calendar_quarter_t1
calendar_quarter_t2
calendar_quarter_t3
survey_prevalence
survey_art_coverage
survey_recently_infected
include_art_t1
include_art_t2
anc_prevalence_year1
anc_prevalence_year2
anc_art_coverage_year1
anc_art_coverage_year2
Paths to output files
This can throw validation errors or warnings which will be shown to user in naomi web app
hintr_validate_anc(anc, shape, pjnz)
hintr_validate_anc(anc, shape, pjnz)
anc |
Path to file containing ANC data or ANC data object |
shape |
Path to file containing geojson areas data or areas data object |
pjnz |
Path to zip file containing spectrum pjnz file/s |
This can throw validation errors or warnings which will be shown to user in naomi web app
hintr_validate_art(art, shape, pjnz)
hintr_validate_art(art, shape, pjnz)
art |
Path to file containing ART data or ART data object |
shape |
Path to file containing geojson areas data or areas data object |
pjnz |
Path to zip file containing spectrum pjnz file/s |
We need to import these as they are used by dependencies (first90) unalified and need to be available in the package environment for the tests to be able to run in a background progress (i.e. when running in parllel)
Log-linear interpolation of age/sex stratified population
interpolate_population_agesex(population_agesex, calendar_quarters)
interpolate_population_agesex(population_agesex, calendar_quarters)
population_agesex |
a subset of the population_agesex. |
calendar_quarters |
vector of calendar quarters to return interpolation. |
zoo::na.approx()
is used to interpolate log(population).
A data.frame with same columns as pop_agesex interpolated to times
.
## Interpolate Malawi population at level 2 (Zone) at two time points data(demo_population_agesex) calendar_quarters <- c("CY2016Q1", "CY2018Q3") pop_interp <- interpolate_population_agesex(demo_population_agesex, calendar_quarters)
## Interpolate Malawi population at level 2 (Zone) at two time points data(demo_population_agesex) calendar_quarters <- c("CY2016Q1", "CY2018Q3") pop_interp <- interpolate_population_agesex(demo_population_agesex, calendar_quarters)
Log-linear interpolation of NA values
log_linear_interp(y, x, rule = 2, replace_na = 0)
log_linear_interp(y, x, rule = 2, replace_na = 0)
y |
vector of output values, possibly with NAs |
x |
vector of points to interpolate (no NAs) |
rule |
rule for extrapolating outside range (see |
replace_na |
value to replace if interpolation evaluates to NA |
log_linear_interp(c(100, 105, NA, 110), 1:4) log_linear_interp(c(NA, 105, NA, 110), 1:4) log_linear_interp(c(NA, 105, NA, 110, NA), 1:5, rule = 1) log_linear_interp(c(NA, 105, NA, 110, NA), 1:5, rule = 2) log_linear_interp(c(NA, NA, 37), 1:3, rule = 2)
log_linear_interp(c(100, 105, NA, 110), 1:4) log_linear_interp(c(NA, 105, NA, 110), 1:4) log_linear_interp(c(NA, 105, NA, 110, NA), 1:5, rule = 1) log_linear_interp(c(NA, 105, NA, 110, NA), 1:5, rule = 2) log_linear_interp(c(NA, NA, 37), 1:3, rule = 2)
Create output map plot
map_outputs( naomi_geom, indicator, calendar_quarter, age, sex_disag, level = NULL, colour_palette = "red", fig_title = NULL, legend_title = NULL, legend_label = ggplot2::waiver(), breaks = 6 )
map_outputs( naomi_geom, indicator, calendar_quarter, age, sex_disag, level = NULL, colour_palette = "red", fig_title = NULL, legend_title = NULL, legend_label = ggplot2::waiver(), breaks = 6 )
naomi_geom |
Labelled naomi output object with geometry |
indicator |
The indicator to generate plot for |
calendar_quarter |
Naomi projection quarter to filter supplied data to. |
age |
The age group to include in plots |
sex_disag |
Sex diaggregation to use in plot, |
level |
Integer, corresponding to desired area level to filter supplied data to. Default is lowest area level available in supplied data. |
colour_palette |
Names or hexcode value for colour scale to be applied to to lowest and highest value in the supplied data. Can be specified as a preset colour palette using "red", "green" and "blue" or manually as a named list: cols = c( start_colour = "red", end_colour = "blue"). |
fig_title |
Title for the figure, blank by default |
legend_title |
Title for the legend, blank by default |
legend_label |
Legend label |
breaks |
Number of break points to create in scale |
Mapped outputs
Construct Model Frames and Adjacency Structures
naomi_model_frame( area_merged, population_agesex, spec, scope = area_merged$area_id[area_merged$area_level == min(area_merged$area_level)], level = max(area_merged$area_level), calendar_quarter1, calendar_quarter2, calendar_quarter3, calendar_quarter4 = "CY2024Q3", calendar_quarter5 = "CY2025Q3", age_groups = get_five_year_age_groups(), sexes = c("male", "female"), omega = 0.7, rita_param = list(OmegaT0 = 130/365, sigma_OmegaT = ((142 - 118)/365)/(2 * stats::qnorm(0.975)), betaT0 = 0, sigma_betaT = 1e-05, ritaT = 1), sigma_u_sd = 1, artattend = TRUE, artattend_t2 = FALSE, artattend_log_gamma_offset = -4, anchor_home_district = TRUE, rho_paed_15to49f_ratio = TRUE, rho_paed_x_term = FALSE, alpha_xst_term = FALSE, logit_nu_mean = 2, logit_nu_sd = 0.3, spectrum_population_calibration = "national", output_aware_plhiv = TRUE, adjust_area_growth = FALSE, psnu_level = NULL )
naomi_model_frame( area_merged, population_agesex, spec, scope = area_merged$area_id[area_merged$area_level == min(area_merged$area_level)], level = max(area_merged$area_level), calendar_quarter1, calendar_quarter2, calendar_quarter3, calendar_quarter4 = "CY2024Q3", calendar_quarter5 = "CY2025Q3", age_groups = get_five_year_age_groups(), sexes = c("male", "female"), omega = 0.7, rita_param = list(OmegaT0 = 130/365, sigma_OmegaT = ((142 - 118)/365)/(2 * stats::qnorm(0.975)), betaT0 = 0, sigma_betaT = 1e-05, ritaT = 1), sigma_u_sd = 1, artattend = TRUE, artattend_t2 = FALSE, artattend_log_gamma_offset = -4, anchor_home_district = TRUE, rho_paed_15to49f_ratio = TRUE, rho_paed_x_term = FALSE, alpha_xst_term = FALSE, logit_nu_mean = 2, logit_nu_sd = 0.3, spectrum_population_calibration = "national", output_aware_plhiv = TRUE, adjust_area_growth = FALSE, psnu_level = NULL )
area_merged |
Merged version of area hierarchy |
population_agesex |
Population by age group and sex |
spec |
Spec |
scope |
The collection of area IDs to be modelled. Defaults to all area ids. |
level |
Admin level |
calendar_quarter1 |
Calendar quarter at time 1 ("CYyyyyQq") |
calendar_quarter2 |
Calendar quarter at time 2 ("CYyyyyQq") |
calendar_quarter3 |
Calendar quarter at time 3 ("CYyyyyQq") |
calendar_quarter4 |
Calendar quarter at time 4 ("CYyyyyQq") |
calendar_quarter5 |
Calendar quarter at time 5 ("CYyyyyQq") |
age_groups |
Age groups to include in model frame |
sexes |
Sexes |
omega |
Omega |
rita_param |
rita_param |
sigma_u_sd |
sigma_u_sd |
artattend |
logical; whether to estimate neighboring district ART attendance |
artattend_t2 |
logical; whether to allow time-varying neighboring district ART attendance |
artattend_log_gamma_offset |
logit offset for neighboring district ART attendance |
anchor_home_district |
logical; whether to include home district random in ART attendance specification |
rho_paed_15to49f_ratio |
logical; to model paediatric prevalence as ratio of 15-49 female prevalence |
rho_paed_x_term |
logical; to include area interaction for paediatric prevalence |
alpha_xst_term |
logical; to include district-sex-time interaction for ART coverage. Default |
logit_nu_mean |
mean of logit viral load suppression. |
logit_nu_sd |
standard deviation of logit viral load suppression. |
spectrum_population_calibration |
character string values "national", "subnational", "none" |
adjust_area_growth |
TRUE/FALSE: adjust PLHIV population for net change in cohort size |
psnu_level |
Level at which to output PEPFAR Data Pack outputs for planning. This doesn't have anything to do with
calibration, but this is a convenient place to allow user to edit this in model workflow. Default value |
Argument spectrum_population_calibration
determines whether to calibrate population
inputs to match Spectrum population by age and sex. If the Spectrum file is a single
national Spectrum file, then options "national" and "subnational" return the same results.
Naomi model frame
R implementation of Naomi model
naomi_objective_function_r(d, p)
naomi_objective_function_r(d, p)
d |
list of data inputs (from |
p |
list of parameter values (from |
This is primarily written to enable stepping through the TMB model line by line.
A list consisting of (1) reported objects from the TMB model, and (2) the value of the objective function.
Model Frame and Linear Transform for Aggregated Model Outputs
naomi_output_frame( mf_model, area_aggregation, age_groups = unique(mf_model[["age_group"]]), sexes = unique(mf_model[["sex"]]) )
naomi_output_frame( mf_model, area_aggregation, age_groups = unique(mf_model[["age_group"]]), sexes = unique(mf_model[["sex"]]) )
mf_model |
Model frame |
area_aggregation |
data.frame with columns |
age_groups |
Age groups to include in aggregated outputs. |
sexes |
Sexes to include in aggregated outputs. |
A list consisting of a data.frame mf
and a sparse matrix A
. The
data frame mf
provides a model matrix defining the stratifications for
the outputs. The sparse matrix A
defines a linear transform to aggregate
the rows of mf_model to the rows of the output mf
Generate naomi warning for specific strata of simulated outputs
output_naomi_warning(naomi_output, ind, threshold, locations)
output_naomi_warning(naomi_output, ind, threshold, locations)
naomi_output |
Naomi output object |
ind |
Naomi output indicator |
threshold |
Numerical threshold to trigger warning |
locations |
Location where warning should be displayed in front end |
Build output package from fit
output_package(naomi_fit, naomi_data, na.rm = FALSE)
output_package(naomi_fit, naomi_data, na.rm = FALSE)
naomi_fit |
Fitted naomi model |
naomi_data |
Naomi model frame with data |
na.rm |
Whether to remove NA values when calculating summary statistics, default FALSE |
The argument na.rm = TRUE
allows the output package to be
produced when there are errors due to missing values when
generating outputs. This is only for debugging purposes to
review results when there are errors. NA
values in
simulated model results typically mean poor model fit or
non-convergence that needs to be addressed.
List containing output indicators and metadata.
Create population pyramid plot
pop_pyramid_outputs( naomi_output, calendar_quarter = 2, indicator, colour_palette = "blue", x_title = NULL, y_title = t_("AGE_GROUP"), fig_title = NULL, legend_label = abs, masc_label = t_("SEX_MALE"), fem_label = t_("SEX_FEMALE") )
pop_pyramid_outputs( naomi_output, calendar_quarter = 2, indicator, colour_palette = "blue", x_title = NULL, y_title = t_("AGE_GROUP"), fig_title = NULL, legend_label = abs, masc_label = t_("SEX_MALE"), fem_label = t_("SEX_FEMALE") )
naomi_output |
Naomi output object or path to naomi output zip folder |
calendar_quarter |
Naomi projection quarter to filter data to, default is calendar_quarter_t2 |
colour_palette |
Names or hexcode value for right and left side of population pyramid. Can be specified as a preset colour palette using "red", "green" and "blue" or manually as a named list: cols <- c( left_clour = "red", right_colour = "blue"). |
x_title |
Title for the figure x axis, blank by default |
y_title |
Title for the figure y axis, default is "Age Group" |
fig_title |
Title for the figure, blank by default, |
masc_label |
Label for male sex group, default is "Male" |
fem_label |
Label for female sex group, default is "Female" |
Pop pyramid
Take uploaded ANC and shape file paths or objects and format as data which can be used to draw input time series graphs.
prepare_input_time_series_anc(anc, shape)
prepare_input_time_series_anc(anc, shape)
anc |
Path to file containing ANC data or ANC data object |
shape |
Path to file containing geojson areas data or shape sf object |
Data formatted for plotting input ANC time series containing columns area_id, area_name, area_level, area_level_label, parent_area_id, area_sort_order, time_period, year, quarter, calendar_quarter, area_hierarchy, plot, value and missing_ids
Take uploaded ART and shape file paths and format as data which can be used to draw input time series graphs.
prepare_input_time_series_art(art, shape)
prepare_input_time_series_art(art, shape)
art |
Path to file containing ART data or ART data object |
shape |
Path to file containing geojson areas data or area data object |
Data formatted for plotting input time series containing columns area_id, area_name, area_level, area_level_label, parent_area_id, area_sort_order, time_period, year, quarter, calendar_quarter, area_hierarchy, plot, value and missing_ids
Prepare inputs for TMB model.
prepare_tmb_inputs(naomi_data, report_likelihood = 1L)
prepare_tmb_inputs(naomi_data, report_likelihood = 1L)
naomi_data |
Naomi data object |
report_likelihood |
Option to report likelihood in fit object (default true). |
anchor_home_district |
Option to include random effect home district attractiveness to retain residents on ART within home districts (default true). |
Inputs ready for TMB model
Time periods are indexed by integers for efficiency and precision. Quarters are indexed as the number of quarters since the beginning of 1900: $quarter_id = (year - 1900) * 4 + quarter$.
quarter_year_labels(quarter_id) quarter_number(quarter_id) quarter_labels(quarter_id) calendar_quarter_labels(calendar_quarter) calendar_quarter_labels_short(calendar_quarter) year_labels(quarter_id) convert_quarter_id(year, quarter) convert_calendar_quarter(year, quarter) calendar_quarter_to_quarter_id(calendar_quarter) quarter_id_to_calendar_quarter(quarter_id) calendar_quarter_to_year(calendar_quarter) calendar_quarter_to_quarter(calendar_quarter)
quarter_year_labels(quarter_id) quarter_number(quarter_id) quarter_labels(quarter_id) calendar_quarter_labels(calendar_quarter) calendar_quarter_labels_short(calendar_quarter) year_labels(quarter_id) convert_quarter_id(year, quarter) convert_calendar_quarter(year, quarter) calendar_quarter_to_quarter_id(calendar_quarter) quarter_id_to_calendar_quarter(quarter_id) calendar_quarter_to_year(calendar_quarter) calendar_quarter_to_quarter(calendar_quarter)
quarter_id |
vector of integer quarter IDs. |
calendar_quarter |
Vector of calendar quarters to convert. |
year |
vector of integer years. |
quarter |
vector of integer quarters (1,2,3,4). |
Quarters are labelled as "Jan-Mar", "Apr-Jun", "Jul-Sep", "Oct-Dec" instead of "Q1", "Q2", "Q3", "Q4" to avoid confusion between calendar quarters and offset fiscal year quarters.
quarter_ids <- convert_quarter_id(c(2009, 2017), c(3, 1)) quarter_ids calender_quarters <- convert_calendar_quarter(c(2009, 2017), c(3, 1)) quarter_number(quarter_ids) quarter_labels(quarter_ids) year_labels(quarter_ids) quarter_year_labels(quarter_ids) calendar_quarter_labels("CY2015Q2") calendar_quarter_to_year("CY2015Q2") calendar_quarter_to_quarter("CY2015Q2")
quarter_ids <- convert_quarter_id(c(2009, 2017), c(3, 1)) quarter_ids calender_quarters <- convert_calendar_quarter(c(2009, 2017), c(3, 1)) quarter_number(quarter_ids) quarter_labels(quarter_ids) year_labels(quarter_ids) quarter_year_labels(quarter_ids) calendar_quarter_labels("CY2015Q2") calendar_quarter_to_year("CY2015Q2") calendar_quarter_to_quarter("CY2015Q2")
Read the hintr model output or plot data saved as a qs or an rds file. This is the data saved from hintr_run_model or hintr_calibrate before the output zip is generated. This uses the file extension to identify the reading function to use.
read_hintr_output(path)
read_hintr_output(path)
path |
Path to the file |
The read data
Read Naomi structured input files
read_population(file) read_survey_indicators(file) read_art_number(file, all_columns = FALSE) read_anc_testing(file) read_area_merged(file)
read_population(file) read_survey_indicators(file) read_art_number(file, all_columns = FALSE) read_anc_testing(file) read_area_merged(file)
file |
A path to a file. |
anc_path <- system.file("extdata/demo_anc_testing.csv", package = "naomi") anc_testing <- read_anc_testing(anc_path)
anc_path <- system.file("extdata/demo_anc_testing.csv", package = "naomi") anc_testing <- read_anc_testing(anc_path)
Read Spectrum Projection Name from Spectrum PJNZ
read_spectrum_projection_name(pjnz)
read_spectrum_projection_name(pjnz)
pjnz |
file path to Spectrum PJNZ file. |
Spectrum projection name as character string.
pjnz <- system.file("extdata/demo_mwi2019.PJNZ", package = "naomi") read_spectrum_projection_name(pjnz)
pjnz <- system.file("extdata/demo_mwi2019.PJNZ", package = "naomi") read_spectrum_projection_name(pjnz)
Read Subnational Region Code from Spectrum PJNZ
read_spectrum_region_code(pjnz)
read_spectrum_region_code(pjnz)
pjnz |
file path to Spectrum PJNZ file. |
The region code is 0 if a national Spectrum file.
Spectrum subnational region code as an integer.
pjnz <- system.file("extdata/demo_mwi2019.PJNZ", package = "naomi") read_spectrum_region_code(pjnz)
pjnz <- system.file("extdata/demo_mwi2019.PJNZ", package = "naomi") read_spectrum_region_code(pjnz)
Read Subnational Region Name from Spectrum PJNZ
read_spectrum_region_name(pjnz)
read_spectrum_region_name(pjnz)
pjnz |
file path to Spectrum PJNZ file. |
Value NA corresponds to region code 0 for a national Spectrum file.
Spectrum subnational region name as a string. Returns NA if no subnational region.
pjnz <- system.file("extdata/demo_mwi2019.PJNZ", package = "naomi") read_spectrum_region_name(pjnz)
pjnz <- system.file("extdata/demo_mwi2019.PJNZ", package = "naomi") read_spectrum_region_name(pjnz)
sdreport()
Calculate Posterior Mean and Uncertainty Via TMB sdreport()
report_tmb(naomi_fit)
report_tmb(naomi_fit)
naomi_fit |
Fitted TMB model. |
Sample TMB fit
sample_tmb( fit, nsample = 1000, rng_seed = NULL, random_only = TRUE, verbose = FALSE )
sample_tmb( fit, nsample = 1000, rng_seed = NULL, random_only = TRUE, verbose = FALSE )
fit |
The TMB fit |
nsample |
Number of samples |
rng_seed |
seed passed to set.seed. |
random_only |
Random only |
verbose |
If TRUE prints additional information. |
Sampled fit.
Save outputs to zip file
save_output( filename, dir, naomi_output, notes = NULL, vmmc_path = NULL, overwrite = FALSE, with_labels = FALSE, boundary_format = "geojson", single_csv = FALSE, export_datapack = !single_csv )
save_output( filename, dir, naomi_output, notes = NULL, vmmc_path = NULL, overwrite = FALSE, with_labels = FALSE, boundary_format = "geojson", single_csv = FALSE, export_datapack = !single_csv )
filename |
Name of file to create |
dir |
Directory to create zip in |
naomi_output |
Naomi output object |
notes |
Notes to include in output zip |
vmmc_path |
Path to VMMC excel workbook |
overwrite |
If TRUE overwrite any existing file |
with_labels |
If TRUE save indicator ids with labels |
boundary_format |
Either geojson or shp for saving boundary as geojson or shape format |
single_csv |
If TRUE only output the csv of indicators, otherwise save the metadata too |
export_datapack |
If TRUE save CSV of PEPFAR datapack indicators. |
options |
Naomi model options |
Path to created zip file
Save outputs to zip file
save_output_package( naomi_output, filename, dir, notes = NULL, overwrite = FALSE, with_labels = FALSE, boundary_format = "geojson", single_csv = FALSE, export_datapack = !single_csv ) read_output_package(path)
save_output_package( naomi_output, filename, dir, notes = NULL, overwrite = FALSE, with_labels = FALSE, boundary_format = "geojson", single_csv = FALSE, export_datapack = !single_csv ) read_output_package(path)
naomi_output |
Naomi output object |
filename |
Name of file to create |
dir |
Directory to create zip in |
notes |
Notes to include in output zip |
overwrite |
If TRUE overwrite any existing file |
with_labels |
If TRUE save indicator ids with labels |
boundary_format |
Either geojson or shp for saving boundary as geojson or shape format |
single_csv |
If TRUE only output the csv of indicators, otherwise save the metadata too |
export_datapack |
If TRUE save CSV of PEPFAR datapack indicators. |
path |
Path to output zip file. |
Path to created zip file
This function scales the precision matrix of a GMRF such that the geometric mean of the marginal variance is one.
scale_gmrf_precision( Q, A = matrix(1, ncol = ncol(Q)), eps = sqrt(.Machine$double.eps) )
scale_gmrf_precision( Q, A = matrix(1, ncol = ncol(Q)), eps = sqrt(.Machine$double.eps) )
Q |
Precision matrix for a GMRF. |
A |
Linear constraint for Q. |
eps |
Value of the small constant added to the diagonal of Q for invertibility. |
This implements the same thing as INLA::inla.scale.model. The marginal variance of each connected component is one.
Plotly scatterplot data inputs and naomi outputs
scatter_plotly( df, ind, quarter, input_data, input_data_type, age_disag = "Y015_049", sex_disag = "both" )
scatter_plotly( df, ind, quarter, input_data, input_data_type, age_disag = "Y015_049", sex_disag = "both" )
df |
Inputs_outputs dataframe containing matched model estimates and data inputs. |
ind |
Indicator filter. |
quarter |
Calendar quarter filter. |
input_data |
Input data name. |
input_data_type |
Input data type. |
age_disag |
Age group filter. |
sex_disag |
Sex filter. |
Select data for model fitting
select_naomi_data( naomi_mf, survey_hiv_indicators, anc_testing, art_number, prev_survey_ids, artcov_survey_ids, recent_survey_ids, vls_survey_ids = NULL, artnum_calendar_quarter_t1 = naomi_mf[["calendar_quarter1"]], artnum_calendar_quarter_t2 = naomi_mf[["calendar_quarter2"]], anc_clients_year_t2 = year_labels(calendar_quarter_to_quarter_id(naomi_mf[["calendar_quarter2"]])), anc_clients_year_t2_num_months = 12, anc_prev_year_t1 = year_labels(calendar_quarter_to_quarter_id(naomi_mf[["calendar_quarter1"]])), anc_prev_year_t2 = year_labels(calendar_quarter_to_quarter_id(naomi_mf[["calendar_quarter2"]])), anc_artcov_year_t1 = anc_prev_year_t1, anc_artcov_year_t2 = anc_prev_year_t2, use_kish_prev = TRUE, deff_prev = 1, use_kish_artcov = TRUE, deff_artcov = 1, use_kish_recent = TRUE, deff_recent = 1, use_kish_vls = TRUE, deff_vls = 1, use_survey_aggregate = FALSE, spec_program_data = NULL )
select_naomi_data( naomi_mf, survey_hiv_indicators, anc_testing, art_number, prev_survey_ids, artcov_survey_ids, recent_survey_ids, vls_survey_ids = NULL, artnum_calendar_quarter_t1 = naomi_mf[["calendar_quarter1"]], artnum_calendar_quarter_t2 = naomi_mf[["calendar_quarter2"]], anc_clients_year_t2 = year_labels(calendar_quarter_to_quarter_id(naomi_mf[["calendar_quarter2"]])), anc_clients_year_t2_num_months = 12, anc_prev_year_t1 = year_labels(calendar_quarter_to_quarter_id(naomi_mf[["calendar_quarter1"]])), anc_prev_year_t2 = year_labels(calendar_quarter_to_quarter_id(naomi_mf[["calendar_quarter2"]])), anc_artcov_year_t1 = anc_prev_year_t1, anc_artcov_year_t2 = anc_prev_year_t2, use_kish_prev = TRUE, deff_prev = 1, use_kish_artcov = TRUE, deff_artcov = 1, use_kish_recent = TRUE, deff_recent = 1, use_kish_vls = TRUE, deff_vls = 1, use_survey_aggregate = FALSE, spec_program_data = NULL )
naomi_mf |
A Naomi model frame object. |
survey_hiv_indicators |
Data frame of survey estimates, or NULL to exclude any survey data. |
anc_testing |
Data frame of ANC routine testing outcomes, or NULL to exclude any ANC data. |
art_number |
Data frame of number currently receiving ART, or NULL to exclude any ART data. |
prev_survey_ids |
A character vector of |
artcov_survey_ids |
A character vector of |
recent_survey_ids |
A character vector of |
vls_survey_ids |
A character vector of |
artnum_calendar_quarter_t1 |
Calendar quarter for first time point for number on ART. |
artnum_calendar_quarter_t2 |
Calendar quarter for second time point for number on ART. |
anc_clients_year_t2 |
Calendar year (possibly multiple) for number of ANC clients at year 2. |
anc_prev_year_t1 |
Calendar year (possibly multiple) for first time point for ANC prevalence. |
anc_prev_year_t2 |
Calendar year (possibly multiple) for second time point for ANC prevalence. |
anc_artcov_year_t1 |
Calendar year (possibly multiple) for first time point for ANC ART coverage. |
anc_artcov_year_t2 |
Calendar year (possibly multiple) for second time point for ANC ART coverage. |
deff_prev |
Approximate design effect for survey prevalence. |
deff_artcov |
Approximate design effect for survey ART coverage. |
deff_recent |
Approximate design effect for survey proportion recently infected. |
deff_vls |
Approximate design effect for survey viral load suppression. |
spec_program_data |
Object of class |
anc_clients_year_t2_num_monhts |
Number of months of reporting reflected in the year(s) recorded in |
See example datasets for examples of required template for data sets. *_survey_ids
must be reflected
in survey_hiv_indicators
.
ART coverage and VLS survey data should not be included from the same survey. This is checked by the function call and will throw an error.
The deff_*
arguments are approximate design effects used to scale the effective sample size for survey
observations. Stratified design effects are will not be the same as full survey DEFF and there is not
a straightforward way to approximate these.
The option use_aggregate_survey = TRUE
allows for aggregate versions of survey data to be used in model
fitting, for example age 15-49 prevalence instead of five-year age group prevalence or province-level
survey data instead of district level data. This maybe useful if cluster coordinates or survey microdata
are not available. This option assumes that the survey_hiv_indicators
is alreaddy subsetted to exactly
the data to be used. All stratifications must also appear in the naomi_data$mf_out
stratifications.
demo_survey_hiv_indicators, demo_anc_testing, demo_art_number, convert_quarter_id
Spread area hierarchy to wide format
spread_areas( areas, min_level = min(areas$area_level), max_level = max(areas$area_level) )
spread_areas( areas, min_level = min(areas$area_level), max_level = max(areas$area_level) )
areas |
area hierarchy data.frame |
min_level |
integer specifying the minimum level |
max_level |
integer specifying the maximum level TODO: Make this an example - where is areas.rds? areas <- readRDS(system.file("extdata/areas/areas.rds", package = "naomi")) areas_wide <- spread_areas(areas) |
Subset the results returned in Naomi output package
subset_naomi_output( naomi_output, area_id = NULL, area_level = NULL, sex = NULL, age_group = NULL, calendar_quarter = NULL, indicator = NULL, drop = FALSE, check_list = TRUE )
subset_naomi_output( naomi_output, area_id = NULL, area_level = NULL, sex = NULL, age_group = NULL, calendar_quarter = NULL, indicator = NULL, drop = FALSE, check_list = TRUE )
naomi_output |
Naomi output object. |
area_id |
vector of area_ids to include/exclude. |
area_level |
vector of area_levels to include/exclude. |
sex |
vector of sexes to include/exclude. |
age_group |
vector of age_groups to include/exclude. |
calendar_quarter |
vector of calendar_quarters to include/exclude. |
indicator |
vector of indicators to include/exclude. |
drop |
logical whether to drop the supplied indices instead of keep only the supplied indices (default). |
check_list |
logical whether to check that supplied values are in the output package to be subsetted. |
If arguemnts are NULL
(default), no subsetting is done on that dimension.
By default the argument check_list = TRUE
means an error will be thrown
if any of the values in the vectors to subset are not found in the
naomi_output
object supplied. This might be set to FALSE
for some batch
processing applications, for example of the naomi_output
could have already
been partially subsetted.
A naomi output package with a subset of results.
This function reads an output package, subsets it using subset_naomi_output()
and resaves the ouput package.
subset_output_package(path, output_path, ...)
subset_output_package(path, output_path, ...)
path |
file path to naomi output package. |
output_path |
path to resave subsetted output package. |
... |
arguments to |
See ?subset_naomi_output()
for subsetting arguments and options.
path to saved output package.
Prepare model frames for survey datasets
survey_mf( survey_ids, indicator, survey_hiv_indicators, naomi_mf, use_kish = TRUE, deff = 1, min_age = 0, max_age = 80, use_aggregate = FALSE )
survey_mf( survey_ids, indicator, survey_hiv_indicators, naomi_mf, use_kish = TRUE, deff = 1, min_age = 0, max_age = 80, use_aggregate = FALSE )
survey_ids |
Survey IDs |
indicator |
Indicator to filter, character string |
survey_hiv_indicators |
Survey HIV indicators |
naomi_mf |
Naomi model frame |
use_kish |
Logical whether to use Kish effective sample size |
deff |
Assumed design effect for scaling effective sample size |
min_age |
Min age for calculating recent infection |
max_age |
Max age for calculating recent infection |
use_aggregate |
Logical; use aggregate survey data as provided instead of subsetting fine area/sex/age group stratification. |
This validates that a set of model options can be used to run the model
validate_model_options(data, options)
validate_model_options(data, options)
data |
The set of input data for the model run |
options |
Key-value list of model options |
TRUE if valid otherwise throw an error
Export naomi outputs to PEPFAR Data Pack format
write_datapack_csv(naomi_output, path, psnu_level = NULL, dmppt2_output = NULL)
write_datapack_csv(naomi_output, path, psnu_level = NULL, dmppt2_output = NULL)
naomi_output |
a naomi_output object. |
path |
path to save Data Pack CSV. |
psnu_level |
area_level for PEPFAR PSNU to export. If NULL, first looks in lookup table for the correct area_level, and if not defaults to the highest level of the area hierarchy. |
dmppt2_output |
data frame containing the Datapack inputs sheet of DMPPT2 output file. |
The results will include Naomi outputs for area_id at the specified level, irrespective of whether a Datim map_id is available.
If a datim ID is available, the Datim map_name will be used in the column
psnu
. Otherwise the Naomi area_name
will be used for the column psnu
.
PEPFAR indicator codes for Data Pack are in this Datim view: https://www.datim.org/api/sqlViews/DotdxKrNZxG/data.html+css?var=dataSets:j7jzezIhgPj
PEPFAR PSNU UIDs are in this Datim view: https://www.datim.org/api/sqlViews/gsaaxFM8ZN0/data.html+css
(Replace the extensions .html+css
with .csv
to download tables as CSV.)