srnorm_optimize: Optimizing Normal Distribution proposal
In stors: Step Optimised Rejection Sampling

srnorm_optimize

R Documentation

Optimizing Normal Distribution proposal

Description

The srnorm_optimize() function generates an optimized proposal for a targeted Normal distribution. The proposal can be customized and adjusted based on various options provided by the user.

Usage

srnorm_optimize(
  mean = NULL,
  sd = NULL,
  xl = -Inf,
  xr = Inf,
  steps = NULL,
  proposal_range = NULL,
  theta = 0.1,
  target_sample_size = 1000,
  verbose = FALSE,
  symmetric = FALSE
)

Arguments

`mean`	(optional) Numeric. Mean parameter of the Normal distribution. Defaults to `NULL`, which implies a scalable proposal with `mean = 0`.
`sd`	(optional) Numeric. Standard deviation of the target Normal distribution. Defaults to `NULL`, which implies a scalable proposal with `sd = 1`.
`xl`	Numeric. Left truncation bound for the target distribution. Defaults to `-Inf`, representing no left truncation.
`xr`	Numeric. Right truncation bound for the target distribution. Defaults to `Inf`, representing no right truncation.
`steps`	(optional) Integer. Desired number of steps in the proposal. Defaults to `NULL`, which means the number of steps is determined automatically during optimization.
`proposal_range`	(optional) Numeric vector. Specifies the range for optimizing the steps part of the proposal. Defaults to `NULL`, indicating automatic range selection.
`theta`	Numeric. A parameter for proposal optimization. Defaults to 0.1.
`target_sample_size`	(optional) Integer. Target sample size for proposal optimization. Defaults to `1000`.
`verbose`	Boolean. If `TRUE`, detailed optimization information, including areas and steps, will be displayed. Defaults to `FALSE`.
`symmetric`	Boolean. If `TRUE`, the proposal will target only the right tail of the distribution, reducing the size of the cached proposal and making sampling more memory-efficient. An additional uniform random number will be sampled to determine the sample's position relative to the mode of the distribution. While this improves memory efficiency, the extra sampling may slightly impact performance, especially when the proposal efficiency is close to 1. Defaults to `FALSE`.

Details

When srnorm_optimize() is explicitly called:

A proposal is created and cached. If no parameters are provided, a standard proposal is created (mean = 0, sd = 1).
Providing mean or sd creates a custom proposal, which is cached for use with srnorm_custom().
The optimization process can be controlled via parameters such as steps, proposal_range, or theta. If no parameters are provided, the proposal is optimized via brute force based on the. target_sample_size.

Value

The user does not need to store the returned value, because the package internally cashes the proposal. However, we explain here the full returned proposal for advanced users.

A list containing the optimized proposal and related parameters for the specified built-in distribution:

data

A data frame with detailed information about the proposal steps, including:

x: The start point of each step on the x-axis.
s_upper: The height of each step on the y-axis.
p_a: Pre-acceptance probability for each step.
s_upper_lower: A vector used to scale the uniform random number when the sample is accepted.

areas

A numeric vector containing the areas under:

left_tail: The left tail bound.
steps: The middle steps.
right_tail: The right tail bound.

steps_number

An integer specifying the number of steps in the proposal.

sampling_probabilities

A numeric vector with:

left_tail: The probability of sampling from the left tail.
left_and_middle: The combined probability of sampling from the left tail and middle steps.

unif_scaler

A numeric scalar, the inverse probability of sampling from the steps part of the proposal (\frac{1}{p(lower < x < upper)}). Used for scaling uniform random values.

lt_properties

A numeric vector of 5 values required for Adaptive Rejection Sampling (ARS) in the left tail.

rt_properties

A numeric vector of 6 values required for ARS in the right tail.

alpha

A numeric scalar representing the uniform step area.

tails_method

A string, either "ARS" (Adaptive Rejection Sampling) or "IT" (Inverse Transform), indicating the sampling method for the tails.

proposal_bounds

A numeric vector specifying the left and right bounds of the target density.

cnum

An integer representing the cache number of the created proposal in memory.

symmetric

A numeric scalar indicating the symmetry point of the proposal, or NULL if not symmetric.

f_params

A list of parameters for the target density that the proposal is designed for.

mean: The mean of the target distribution.
sd: The standard deviation of the target distribution.

is_symmetric

A logical value indicating whether the proposal is symmetric.

proposal_type

A string indicating the type of the generated proposal:

"scaled": The proposal is "scalable" and standardized with mean = 0 and sd = 1. This is used when parameters mean and sd are either NULL or not provided. Scalable proposals are compatible with srnorm.
"custom": The proposal is "custom" when either mean or sd is provided. Custom proposals are compatible with srnorm_custom.

target_function_area

A numeric scalar estimating the area of the target distribution.

dens_func

A string containing the hardcoded density function.

density_name

A string specifying the name of the target density distribution.

lock

An identifier used for saving and loading the proposal from disk.

Examples

# Generate scalable proposal that with mean = 0 and sd = 1, that has 4096 steps
scalable_proposal <- srnorm_optimize(steps = 4096)


# Generate custom proposal that with mean = 2 and sd = 1
scalable_proposal <- srnorm_optimize(mean = 2, sd = 1)

stors documentation built on April 3, 2025, 6:16 p.m.