Help for package AutoWMM

Type:

Package

Title:

Perform the Weighted Multiplier Method on Trees

Version:

1.0.2

Maintainer:

Mallory J Flynn <mallory.flynn@stat.ubc.ca>

Description:

When many possible multiplier method estimates of a target population are available, a weighted sum of estimates from each back-calculated path can be achieved with this package. Variance-minimizing weights are used and with any admissible tree-structured data. The methodological basis used to create this package can be found in Flynn (2023) http://hdl.handle.net/2429/86174.

License:

GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]

URL:

https://github.com/malfly/AutoWMM

Depends:

R (≥ 4.3.0)

Imports:

data.tree, DiagrammeR, dplyr, gtools, MASS, rlang, magrittr, tidyselect

Suggests:

knitr, rmarkdown, testthat (≥ 3.0.0)

Encoding:

UTF-8

LazyData:

true

RoxygenNote:

7.3.1

VignetteBuilder:

knitr

Config/testthat/edition:

NeedsCompilation:

Packaged:

2025-05-20 05:39:33 UTC; mallory

Author:

Mallory J Flynn [cre, aut]

Repository:

CRAN

Date/Publication:

2025-05-20 09:10:02 UTC

Nhats

Description

Estimation helper function: Returns Nhat for each sample from the WMM (rather than the aggregate value given by the average, this calculates weights and applies the weighted sum to each of the samples)

Usage

Nhats(tree)

Arguments

tree

A makeTree object

Value

Returns a vector of root population size estimates from each sample run of the wmmTree function

Examples


 data(treeData1)
 tree <- makeTree(treeData1)
 Zhats <- wmmTree(tree, sample_length = 3)
 Nhats(tree)

confInts

Description

Estimation helper function: Method that takes samples and generates confidence intervals for nodes other than the root. Assume raw data (not log), with normal distributed log data for confidence interval construction

Usage

confInts(v)

Arguments

v

A vector

Value

Returns a confidence interval. For non-root nodes

Examples


 data(treeData1)
 tree <- makeTree(treeData1)
 message("note - longer run time example")
 Zhats <- wmmTree(tree, sample_length = 10)
 confInts(Zhats$estimates)

countTree

Description

Visualize post-wmmTree tree with root estimate and marginal counts Also displays average of probability samples on each branch

Usage

countTree(tree)

Arguments

tree

A makeTree object

Value

Returns a tree plot

Examples


  message("note - longer run time example")
  data(treeData1)
  tree <- makeTree(treeData1)
  Zhats <- wmmTree(tree, sample_length = 3)
  countTree(tree)

drawTree

Description

Visualize tree with descriptions and probabilities; can be used pre-WMM analysis

Usage

drawTree(tree, probs = TRUE, desc = TRUE)

Arguments

tree

A makeTree object

probs

A logical with default TRUE to specify whether to display probabilities on branches

desc

A logical with default TRUE to specify whether to display node descriptions

Value

Returns a descriptive tree plot

Examples

data(treeData1)
tree <- makeTree(treeData1)
drawTree(tree)

estTree

Description

Visualize post-wmmTree tree with root estimate given by each branch, and weighted sum at the root (for post-analysis). Also displays average of probability samples on each branch.

Usage

estTree(tree)

Arguments

tree

A makeTree object

Value

Returns a tree plot

Examples


  message("note - longer run time example")
  data(treeData1)
  tree <- makeTree(treeData1)
  Zhats <- wmmTree(tree, sample_length = 3)
  estTree(tree)

ko.weights

Description

Estimation helper function: Calculating variance minimizing weights. Only assigns weights to informative paths

Usage

ko.weights(tree)

Arguments

tree

A makeTree object

Value

Returns vector of variance-minimizing weights on informative paths

Examples


 data(treeData1)
 tree <- makeTree(treeData1)
 Zhats <- wmmTree(tree, sample_length = 3)
 ko.weights(tree)

logEstimates

Description

Estimation helper function: Creates a vector of mean estimate values given by each informative path

Usage

logEstimates(tree)

Arguments

tree

A makeTree object

Value

Returns a vector of mean log estimate values of the root population size from each informative path

Examples


  message("note - longer run time example")
  data(treeData1)
  tree <- makeTree(treeData1)
  Zhats <- wmmTree(tree, sample_length = 3)
  logEstimates(tree)

makeTree

Description

Assuming a specific structure, create a tree with the following columns: from (node label), to (node label), Estimate (+ integer), Total (+ integer), and Count (for terminal nodes with marginal counts). 'from' and 'to' describe the edge for that row of data, where 'Estimate' and 'Total' are assumed to come from surveys of size 'Total' (a sample of the population at node 'from'), and observe 'Estimate' number of those individuals at 'Total' which move to the node described by 'to'. 'Estimate' and 'Total' columns are used for branching probabilities only. 'Count' column is NA for rows where 'to' nodes are not leaves; and also for all leaves without a marginal count. A Population (logical) column is not needed, but can be added if 'Estimate' and 'Total' come from population numbers, rather than samples. A 'Description' column (string) is also possible to include if particulars are desired on the tree diagram. 'TerminalCount' (binary) will be created for functional purposes, where marginal counts are included on leaves.

Usage

makeTree(data)

Arguments

data

A dataframe object

Value

Returns a makeTree object

Examples

data(treeData1)
tree <- makeTree(treeData1)

mmEstimate

Description

Helper function: Performs the multiplier method from a single terminal node (o) and returns the root estimate given that path, and the probabilities of each branch on that path.

Usage

mmEstimate(o)

Arguments

o

A node from a makeTree object

Value

Returns node with modified attributes

Examples


 data(treeData1)
 tree <- makeTree(treeData1)
 mmEstimate(tree$A)
 mmEstimate(tree$B)
 tree$A$targetEst
 tree$B$targetEst

root.confInt

Description

Estimation helper function: Method for generating confidence interval for root node. Assumes unlogged input data and normally distributed logged data. Completes conversion internally.

Usage

root.confInt(tree, int.type = "quantiles")

Arguments

tree

A makeTree object

int.type

A string specifying interval type, passed from the wmmTree function.

Value

Returns a confidence interval for the root population size estimate in un-logged form.

Examples


 message("note - longer run time example")
 data(treeData1)
 tree <- makeTree(treeData1)
 Zhats <- wmmTree(tree, sample_length = 3)
 root.confInt(tree)

sampleBeta

Description

Helper function: Method for sampling from a Beta distribution given the survey estimates

Usage

sampleBeta(x, n, pop, node)

Arguments

x

An integer; typical use case is survey numerator

n

An integer; typical use case is survey sample size

pop

A logical value which takes TRUE if sample size is population size

node

A node from a makeTree object; carried forever from

Value

Returns sample from Beta distribution with parameters dependent on x, n

Examples


 data(treeData1)
 tree <- makeTree(treeData1)
 Zhats <- wmmTree(tree, sample_length = 3)
 sampleBeta(10, 55, pop = FALSE, tree$A)

ss.confInts

Description

Estimation helper function: Method that takes samples and generates confidence intervals for nodes in single source sibling tree (single.source = TRUE)

Usage

ss.confInts(o, digits = 3)

Arguments

o

A node of a makeTree object

digits

The number of significant digits to report

Value

A confidence interval for nodes of the tree that only use a single source of sibling data.

Examples


 data(treeData1)
 tree <- makeTree(treeData1)
 Zhats <- wmmTree(tree, sample_length = 3)
 ss.confInts(tree$B)

ssEstimate

Description

Helper function: Performs the closed form calculation of variances and means based on a "single-source sibling" tree. Engages when single.source = TRUE in wmmTree function. See documentation for further details.

Usage

ssEstimate(o)

Arguments

o

A node from a makeTree object

Value

Returns node with modified attributes

Examples


 data(treeData1)
 tree <- makeTree(treeData1)
 Zhats <- wmmTree(tree, sample_length = 3)
 ssEstimate(tree$B)

Simple Tree Data

Description

Small, artificially generated toy data set to demonstrate package functionality

Usage

data(treeData1)

Format

An object of class "data.frame"

from: A node label and started point of directed edge (parent node)
to: A node label and endpoint of directed edge (child node)
Estimate: A numerical value assumed to be survey count belonging to 'to' node (integer)
Total: A numerical value assumed to be survey sample size (integer)
Count: A numerical value for marginal count if leaf node (integer)
Population: A boolean value for if survey size is entire population (logical)
Description: A string describing 'to' node (string)

References

This data set was artificially created for the AutoWMM package.

Examples

data(treeData1)
head(treeData1)

Larger Tree Data

Description

Larger artificially generated toy data set to demonstrate package functionality

Usage

data(treeData2)

Format

An object of class "data.frame"

from: A node label and started point of directed edge (parent node)
to: A node label and endpoint of directed edge (child node)
Estimate: A numerical value assumed to be survey count belonging to 'to' node (integer)
Total: A numerical value assumed to be survey sample size (integer)
Count: A numerical value for marginal count if leaf node (integer)

References

This data set was artificially created for the AutoWMM package.

Examples

data(treeData2)
head(treeData2)

wmmTree

Description

Main function. Generate weighted estimates using the weighted multiplier method.

Usage

wmmTree(
  tree,
  sample_length = 10,
  method = "mmEstimate",
  int.type = "quants",
  single.source = FALSE
)

Arguments

tree

A makeTree object

sample_length

An integer for number of samples

method

Method specifying weighting. Only default compatible with 'mmEstimate' at this time

int.type

A string specifying interval type. Default "quants" generates the interval using the quantiles giving the central 95% of the samples. Alternatively, "var" can be used to generate a variance-weighted confidence interval, and "cox" generates a Cox interval.

single.source

Set to TRUE if all data comes from single, fully informed source. Default is FALSE.

Value

Returns a makeTree object with branches and nodes now associated with estimates and samples generated with the weighted multiplier method

Examples


  data(treeData1)
  tree <- makeTree(treeData1)
  Zhats <- wmmTree(tree, sample_length = 3)

  message("Another example with a larger tree")
  message("note - longer run time example")
  data(treeData2)
  tree2 <- makeTree(treeData2)
  Zhats <- wmmTree(tree2, sample_length = 3)
  Zhats$estimates # print the estimates of the root node generated by the 15 iterations
  Zhats$weights # prints the weights of each branch
  Zhats$root # prints the final estimate of the root node by WMM
  Zhats$uncertainty # prints the final rounded estimate of the root with conf. int.

  message(paste("show the average root estimate with 95% confidence interval,",
          "as well as average estimates with confidence interval for each parameter"))
  tree2$Get('uncertainty')

  message("show the samples generated from each path which provides root estimates")
  tree2$Get('targetEst_samples')

  message("show the probabilities sampled at each branch leading into the given node")
  tree2$Get('probability_samples')