Package 'naomi'

Description

Add labels to output indicators

Usage

add_output_labels(naomi_output, geometry = FALSE)

Arguments

Value

Labelled output indicators

Description

Plotly barplot comparing age distribution of survey inputs and naomi outputs

Usage

age_bar_plotly(df, ind, quarter)

Arguments

Description

Take ANC and shape file paths or data files and aggregate art_current according to area hierarchy provided

Usage

aggregate_anc(anc, shape)

Arguments

Value

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

Description

Take ART and shape file paths or files and aggregate art_current according to area hierarchy provided

Usage

aggregate_art(art, shape)

Arguments

Value

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

Description

Align model data inputs and model estimates

Usage

align_inputs_outputs(naomi_data, indicators, meta_area)

Arguments

Description

Prepare Model Frames for Programme Datasets

Usage

anc_testing_prev_mf(year, anc_model_mf)

anc_testing_artcov_mf(year, anc_model_mf)

anc_testing_clients_mf(year, anc_model_mf)

Arguments

Value

Calculated prevalence

Description

Build artnum model frame

Usage

artnum_mf(calendar_quarter, art_number, naomi_mf)

Arguments

Details

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

Description

Check whether PJNZ contains .shiny90 file

Usage

assert_pjnz_shiny90(pjnz)

Arguments

Value

Logical whether PJNZ file contains a .shiny90 file

Description

Plotly barplot comparing geographical distribution of data inputs and naomi outputs

Usage

bar_plotly(df, ind, quarter, age_disag = "Y015_049", sex_disag = "both")

Arguments

Description

Return the translated label & description for a set of plot types

Usage

build_hierarchy_label(meta_areas)

Arguments

Value

For each plot type the label and description as a list of lists containing id, label and description

Description

Calculate prevalence and ART coverage from ANC input data

Usage

calculate_prevalence_art_coverage(data)

Arguments

Value

Data frame with prevalence and ART coverage

Description

Calibrate naomi model outputs

Usage

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"
)

Arguments

Details

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:

1. Aggregate Spectrum totals to specified stratification by level/sex/age to calculate the target totals within each stratification.

2. Adjust fine area/sex/age-group mean values to match targeted total using either "logistic" or "proportional" scaling.

3. Aggregate revised mean count values to all stratifications of Naomi outputs.

4. Calculate calibrated mean for proportion indicators.

5. Adjust outputs for all statistics (mean, median, mode, se, range).

6. 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.

Description

Converts a date to DHS Century Month Code (CMC).

Usage

cmc_date(date)

Arguments

Details

CMC date is defined as the number of months since 1900:

$cmc = (year - 1900) * 12 + momth$

Value

an integer vector of CMC dates

References

https://dhsprogram.com/Data/Guide-to-DHS-Statistics/Organization_of_DHS_Data.htm?rhtocid=_4_2_0#Structure_of_DHS_Databc-1

Examples

cmc_date(Sys.Date())
cmc_date(as.Date("1987-02-11", format = "%Y-%m-%d"))

Description

Create adjacency matrix from spatial polygons

Usage

create_adj_matrix(sh)

Arguments

Details

Input sh can be either sf class or SpatialPolygons from sp. Uses spdep package to convert shapefile to neighbor list to adjacency matrix.

Value

an adjacency matrix with 1s and 0s

Description

Long data frame mapping area hierarchy areas to model level areas

Usage

create_area_aggregation(model_area_ids, areas, drop_partial_areas = TRUE)

Arguments

Examples

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)

Description

Constructs and validates an areas object as an S3 class.

Usage

create_areas(
  levels = NULL,
  hierarchy = NULL,
  boundaries = NULL,
  area_merged = NULL
)

Arguments

Value

An object of class naomi_areas

Examples

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

Description

Create edgelist from adjacency matrix

Usage

create_edge_list(adj_matrix)

Arguments

Description

Wrapper for ⁠[cut()]⁠ to return five year age groups with

Usage

cut_naomi_age_group(age)

Arguments

Value

a vector of strings with five year age groups.

See Also

get_age_groups

Description

Get id to label mapping for calibration plot data type

Usage

data_type_labels()

Value

List of ID & label mappings

Description

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.

Usage

demo_anc_testing

demo_art_number

Format

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 830 rows and 10 columns.

Details

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:

1. The data in this file are owned by the Ministry of Health (MOH), Malawi.

2. These data are shared in order to support the National HIV Program.

3. 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.

4. 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.

5. 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.

Source

Department of HIV & AIDS, Minitry of Health, Malawi. http://hiv.health.gov.mw/index.php/our-documents

See Also

quarter_labels, get_age_groups.

Description

Malawi area boundaries.

Usage

demo_area_boundaries

Format

sf object representing area boundaries

Source

Malawi

Description

Malawi area hierarchy

Usage

demo_area_hierarchy

Format

Data frame

Source

Malawi

Description

Malawi area levels.

Usage

demo_area_levels

Format

Data frame

Source

Malawi

Description

Malawi age-sex stratified population data

Usage

demo_population_agesex

Format

Data frame

Source

Malawi

Description

Malawi survye biomarkers

Usage

demo_survey_biomarker

Format

Data frame

Source

Malawi

Description

Malawi survey clusters

Usage

demo_survey_clusters

Format

Data frame

Source

Malawi

Description

Malawi HIV indicators

Usage

demo_survey_hiv_indicators

Format

Data frame

Source

Malawi

Description

Malawi survey individuals

Usage

demo_survey_individuals

Format

Data frame

Source

Malawi

Description

Malawi survey metadata

Usage

demo_survey_meta

Format

Data frame

Source

Malawi

Description

Malawi survey regions

Usage

demo_survey_regions

Format

Data frame

Source

Malawi

Description

Disaggregate output indicators for the 0-4 age group proportional to Spectrum distribution for each age group.

Usage

disaggregate_0to4_outputs(output, naomi_mf)

Arguments

Description

Create district bar plot

Usage

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")
)

Arguments

Value

District barplot

Description

Automatically make drop drop buttons for plotly filter

Usage

dropdown_buttons(df, var)

Arguments

Value

Drop down buttons for plotly filter

Description

If the .shiny90 file does not exist within the .PJNZ, the function will silently not return values, even if extract_shiny90 = TRUE.

Usage

extract_pjnz_naomi(pjnz_list, extract_shiny90 = TRUE)

Arguments

Value

A data.frame with Spectrum indicators.

Examples

pjnz <- system.file("extdata/demo_mwi2019.PJNZ", package = "naomi")
spec <- extract_pjnz_naomi(pjnz)

Description

Extract ART and ANC testing program data inputs from Spectrum PJNZ

Usage

extract_pjnz_program_data(pjnz_list)

Arguments

Value

A list with a two data.frames of ANC testing data and number on ART, respectively.

Examples

pjnz <- system.file("extdata/demo_mwi2019.PJNZ", package = "naomi")
spec <- extract_pjnz_program_data(pjnz)

Description

Export estimates for proportion aware of status from a Shiny90 output file to five-year age groups 15-19 to 50+.

Usage

extract_shiny90_age_sex(shiny90_path, pjnz_path = NULL, years = NULL)

Arguments

Details

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.

Value

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.

Examples

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)

Description

Fit TMB model

Usage

fit_tmb(
  tmb_input,
  outer_verbose = TRUE,
  inner_verbose = FALSE,
  max_iter = 250,
  progress = NULL
)

Arguments

Value

Fit model.

Description

Return a data frame consisting of master age groups

Usage

get_age_groups()

Value

data frame

Description

Metadata for ANC plot types used in the input time series plots. Mainly for internal use.

Usage

get_anc_metadata(anc)

Arguments

Value

List of plot_types and cols_keep (columns that are present in the actual data out of the known list of columns)

Description

Get a collection of areas defined by a level and nested within a collection of higher level area(s).

Usage

get_area_collection(areas, level = NULL, area_scope = NULL)

Arguments

Details

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_ids 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()

Description

Metadata for ART plot types used in the input time series plots. Mainly for internal use.

Usage

get_art_metadata(art)

Arguments

Value

List of plot_types and cols_keep (columns that are present in the actual data out of the known list of columns) and calendar_quarters

Description

Get 5 year age groups

Usage

get_five_year_age_groups()

Value

ID for 5 year age groups

Examples

get_five_year_age_groups()

Description

Get indicator metadata

Usage

get_meta_indicator()

Value

data.frame of indicator ids, labels, descriptions, and parameter mapping.

Examples

get_meta_indicator()

Description

Get indicator metadata as a data frame

Usage

get_metadata()

Value

Metadata about indicators as a list

Description

Return the translated label & description for a set of plot types

Usage

get_plot_type_column_metadata(plot_type)

Arguments

Value

For each plot type the label and description as a list of lists containing id, label and description

Description

Get plotting metadata for a particular country

Usage

get_plotting_metadata(iso3)

Arguments

Value

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.

Examples

get_plotting_metadata("MWI")

Description

Interpolate Spectrum to quarter_id

Usage

get_spec_aggr_interpolation(spec_aggr, calendar_quarter_out)

Arguments

Description

Take a previously generated hintr_output object and calibrate. Format response as another hintr_output object.

Usage

hintr_calibrate(
  output,
  calibration_options,
  plot_data_path = tempfile(fileext = ".qs"),
  calibrate_output_path = tempfile(fileext = ".qs")
)

Arguments

Value

Calibrated hintr_output object

Description

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.

Usage

hintr_calibrate_plot(output)

Arguments

Value

Calibrated, unadjusted and spectrum estimates of indicators

Description

Takes hintr_output object, reads data and prepares data in format needed for plotting comparison barchart to compare input and output data.

Usage

hintr_comparison_plot(output)

Arguments

Value

Calibrated, unadjusted and spectrum estimates of indicators

Description

Prepare AGYW tool download

Usage

hintr_prepare_agyw_download(output, pjnz, path = tempfile(fileext = ".xlsx"))

Arguments

Value

Path to output file and metadata for file

Description

Prepare coarse age group download

Usage

hintr_prepare_coarse_age_group_download(
  output,
  path = tempfile(fileext = ".zip")
)

Arguments

Value

Path to output file and metadata for file

Description

Prepare comparison report download

Usage

hintr_prepare_comparison_report_download(
  output,
  path = tempfile(fileext = ".html")
)

Arguments

Value

Path to output file and metadata for file

Description

Prepare Datapack download

Usage

hintr_prepare_datapack_download(
  output,
  path = tempfile(fileext = ".xlsx"),
  vmmc_file = NULL,
  ids = NULL
)

Arguments

Value

Path to output file and metadata for file

Description

Prepare spectrum download

Usage

hintr_prepare_spectrum_download(
  output,
  path = tempfile(fileext = ".zip"),
  notes = NULL,
  vmmc_file = NULL
)

Arguments

Value

Path to output file and metadata for file

Description

Prepare summary report download

Usage

hintr_prepare_summary_report_download(
  output,
  path = tempfile(fileext = ".html")
)

Arguments

Value

Path to output file and metadata for file

Description

This prepares the model inputs from data and options and saves output as a qs file.

Usage

hintr_run_model(
  data,
  options,
  model_output_path = tempfile(fileext = ".qs"),
  validate = TRUE
)

Arguments

Details

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

Value

Paths to output files

Description

This can throw validation errors or warnings which will be shown to user in naomi web app

Usage

hintr_validate_anc_programme_data(anc_naomi_spectrum_comparison)

Arguments

Description

This can throw validation errors or warnings which will be shown to user in naomi web app

Usage

hintr_validate_art_programme_data(art_naomi_spectrum_comparison)

Arguments

Description

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)

Description

Log-linear interpolation of age/sex stratified population

Usage

interpolate_population_agesex(population_agesex, calendar_quarters)

Arguments

Details

zoo::na.approx() is used to interpolate log(population).

Value

A data.frame with same columns as pop_agesex interpolated to times.

See Also

convert_quarter_id()

Examples

## 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)

Description

Log-linear interpolation of NA values

Usage

log_linear_interp(y, x, rule = 2, replace_na = 0)

Arguments

Examples

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)

Description

Create output map plot

Usage

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
)

Arguments

Value

Mapped outputs

Description

Construct Model Frames and Adjacency Structures

Usage

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
)

Arguments

Details

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.

Value

Naomi model frame

Description

R implementation of Naomi model

Usage

naomi_objective_function_r(d, p)

Arguments

Details

This is primarily written to enable stepping through the TMB model line by line.

Value

A list consisting of (1) reported objects from the TMB model, and (2) the value of the objective function.

Description

Model Frame and Linear Transform for Aggregated Model Outputs

Usage

naomi_output_frame(
  mf_model,
  area_aggregation,
  age_groups = unique(mf_model[["age_group"]]),
  sexes = unique(mf_model[["sex"]])
)

Arguments

Value

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

Description

Generate naomi warning for specific strata of simulated outputs

Usage

output_naomi_warning(naomi_output, ind, threshold, locations)

Arguments

Description

Build output package from fit

Usage

output_package(naomi_fit, naomi_data, na.rm = FALSE)

Arguments

Details

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.

Value

List containing output indicators and metadata.

Description

Create population pyramid plot

Usage

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")
)

Arguments

Value

Pop pyramid

Description

Take uploaded ANC and shape file paths or objects and format as data which can be used to draw input time series graphs.

Usage

prepare_input_time_series_anc(anc, shape)

Arguments

Value

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

Description

Take uploaded ART and shape file paths and format as data which can be used to draw input time series graphs.

Usage

prepare_input_time_series_art(art, shape)

Arguments

Value

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

Description

Compare aggregated subnational Naomi + spectrum totals for comparison table

Usage

prepare_spectrum_naomi_comparison(art, anc, shape, pjnz)

Arguments

Description

Prepare inputs for TMB model.

Usage

prepare_tmb_inputs(naomi_data, report_likelihood = 1L)

Arguments

Value

Inputs ready for TMB model

See Also

select_naomi_data

Description

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$.

Usage

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)

Arguments

Details

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.

Examples

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")

Description

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.

Usage

read_hintr_output(path)

Arguments

Value

The read data

Description

Read Naomi structured input files

Usage

read_population(file)

read_survey_indicators(file)

read_art_number(file, all_columns = FALSE)

read_anc_testing(file)

read_area_merged(file)

Arguments

Examples

anc_path <- system.file("extdata/demo_anc_testing.csv", package = "naomi")
anc_testing <- read_anc_testing(anc_path)

Description

Read Spectrum Projection Name from Spectrum PJNZ

Usage

read_spectrum_projection_name(pjnz)

Arguments

Value

Spectrum projection name as character string.

Examples

pjnz <- system.file("extdata/demo_mwi2019.PJNZ", package = "naomi")
read_spectrum_projection_name(pjnz)

Description

Read Subnational Region Code from Spectrum PJNZ

Usage

read_spectrum_region_code(pjnz)

Arguments

Details

The region code is 0 if a national Spectrum file.

Value

Spectrum subnational region code as an integer.

Examples

pjnz <- system.file("extdata/demo_mwi2019.PJNZ", package = "naomi")
read_spectrum_region_code(pjnz)

Description

Read Subnational Region Name from Spectrum PJNZ

Usage

read_spectrum_region_name(pjnz)

Arguments

Details

Value NA corresponds to region code 0 for a national Spectrum file.

Value

Spectrum subnational region name as a string. Returns NA if no subnational region.

Examples

pjnz <- system.file("extdata/demo_mwi2019.PJNZ", package = "naomi")
read_spectrum_region_name(pjnz)

Description

Calculate Posterior Mean and Uncertainty Via TMB sdreport()

Usage

report_tmb(naomi_fit)

Arguments

Description

Sample TMB fit

Usage

sample_tmb(
  fit,
  nsample = 1000,
  rng_seed = NULL,
  random_only = TRUE,
  verbose = FALSE
)

Arguments

Value

Sampled fit.

Description

Save outputs to zip file

Usage

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
)

Arguments

Value

Path to created zip file

Description

Save outputs to zip file

Usage

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)

Arguments

Value

Path to created zip file

Description

This function scales the precision matrix of a GMRF such that the geometric mean of the marginal variance is one.

Usage

scale_gmrf_precision(
  Q,
  A = matrix(1, ncol = ncol(Q)),
  eps = sqrt(.Machine$double.eps)
)

Arguments

Details

This implements the same thing as INLA::inla.scale.model. The marginal variance of each connected component is one.

Description

Plotly scatterplot data inputs and naomi outputs

Usage

scatter_plotly(
  df,
  ind,
  quarter,
  input_data,
  input_data_type,
  age_disag = "Y015_049",
  sex_disag = "both"
)

Arguments

Description

Select data for model fitting

Usage

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
)

Arguments

Details

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.

See Also

demo_survey_hiv_indicators, demo_anc_testing, demo_art_number, convert_quarter_id

Description

Spread area hierarchy to wide format

Usage

spread_areas(
  areas,
  min_level = min(areas$area_level),
  max_level = max(areas$area_level)
)

Arguments

Description

Subset the results returned in Naomi output package

Usage

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
)

Arguments

Details

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.

Value

A naomi output package with a subset of results.

Description

This function reads an output package, subsets it using subset_naomi_output() and resaves the ouput package.

Usage

subset_output_package(path, output_path, ...)

Arguments

Details

See ?subset_naomi_output() for subsetting arguments and options.

Value

path to saved output package.

See Also

subset_naomi_output()

Description

Prepare model frames for survey datasets

Usage

survey_mf(
  survey_ids,
  indicator,
  survey_hiv_indicators,
  naomi_mf,
  use_kish = TRUE,
  deff = 1,
  min_age = 0,
  max_age = 80,
  use_aggregate = FALSE
)

Arguments

Description

ggplot2 theme for plotting maps

Usage

th_map()

Description

This validates that a set of model options can be used to run the model

Usage

validate_model_options(data, options)

Arguments

Value

TRUE if valid otherwise throw an error

Description

Export naomi outputs to PEPFAR Data Pack format

Usage

write_datapack_csv(naomi_output, path, psnu_level = NULL, dmppt2_output = NULL)

Arguments

Details

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.)

Description

Write UNAIDS Estimates Navigator checklist CSV

Usage

write_navigator_checklist(naomi_output, path)

Arguments