multimersim_mix: Mixed Multimer Simulation
In rolandrolandroland/rTEM: R package for statistical analysis of TEM data

multimersim_mix

R Documentation

Mixed Multimer Simulation

Description

Under construction. See multimersim for stable version. Simulates multimers (groups of two/dimers, three/trimers, etc.) in underlying point pattern (upp) to match domain and number of points in guest_pattern.

Usage

multimersim_mix(
  guest_pattern = NULL,
  upp,
  output = "guest pattern type",
  n_guests = NA,
  min_thick = NA,
  max_thick = NA,
  ztrim = 0,
  size_fracs = c(0, 1),
  num_neighbors = 6,
  sample_method = "rank",
  exponent = 1,
  weights = list(c(1, 1, 1), c(1, 1, 0)),
  weights_fracs = c(0.5, 0.5),
  probs = c(1, 0, 0, 0),
  intensity_upp = NA
)

Arguments

`guest_pattern`	point pattern of class ppp or pp3. The final multtimer pattern will match this pattern in class, intensity, and domain. If this is left as NULL, then the domain will match that of upp, will be of the class specified in output, and have number of guests specified in n_guest
`upp`	point pattern of class ppp or pp3 to use as underlying point pattern. Multimers will be selected from these points.
`output`	leave as "guest pattern type" if specifying guest_pattern. Otherwise, set to "ppp" for 2D output or pp3 for 3D output
`n_guests`	leave as NA if specifying guest_pattern. Otherwise, set to integer for number of guests in multimer pattern
`min_thick`	if guest_pattern is 2d (ppp) and upp is 3d (pp3) this determines the smallest z value to keep before collapsing into 2d.
`max_thick`	if guest_pattern is 2d (ppp) and upp is 3d (pp3) this determines the largest z value to keep before collapsing into 2d.
`ztrim`	a numeric. This will trim this amount from both top and bottom (positive and negative z) after multimers are generated and before pp3 pattern is collapsed into ppp. Only applies if upp is 3D (pp3)
`size_fracs`	= a vector of numerics. This will be the fraction of all guest points that are assigned to groups of each size. For example, if size_fracs = c(0.2, 0.3, 0.1, 0.4), then 20% of guests will be randomly assigned, 30% will be in dimers, 10% will be in trimers, and 30% will be quadramers (group of 4)
`num_neighbors`	An integer. Number of nearest neighbors to select from when forming dimers, trimers, etc.. Must be at least at least one less than the length of size_fracs
`sample_method`	if equal to "rank", the probability of a point of rank x being chosen as a guest is probs[x]. If equal to "exp", the probability of a point of rank x being chosen as a guest is probs[x] exp(-exponent * distances[ranks]))*
`exponent`	a numeric. If sample_method = "exp", then this is the value of exponent in exp(-exponent distances[ranks])*
`weights`	list of vectors of length equal to number of dimensions in upp. the weighted distance to each of num_neighbors nearest neighbors is calculated using `\sqrt{w_1 x^2 + w_2 y^2 + w_3 z^2}`, where weights = (`w_1, w_2, w_3`). Set to c(1, 1, 0) for vertical dimers.
`weights_fracs`	vector of numerics. This will be the fraction of all guests that are assigned to the corresponding element of the 'weights' list
`probs`	vector of probabilities. For `probs = c(p_1, p_2, p_3, p_4)`, the probability of the first NN being selected in `p_1`, the probability of the second is `p_2`, and so on
`intensity_upp`	the upp will be rescaled to have this intensity before the marks are assigned. Leave as NA to use upp as it is

Details

Algorithm steps: Case 1: 2D Guest pattern, 3D UPP

Step 1: Prechecks. If no guest pattern is used, are both 'n_guests' and 'output' explicitly defined? Is 'n_guests' smaller than number of points in the 'upp'? If there are fewer probabilities than the number of neighbors to be cosidered (‘num_neighbors') then append 0’s onto the 'probs' vector until it is long enough. Normalize the 'size_fracs' vector so that it sums to 1. Rescale 'upp' so that it has an intensity of 'intensity_upp', unless such is left as 'NA'
Step 2: Select points in the scaled upp that are inside the x-y limits of guest_pattern and the z limits difined by 'min_thick' and 'max_thick' (default values are z limits of 'upp')
Step 3: Determine total number of guests to be assigned. We will scale the number of guests either in the given 'guest_pattern' or 'n_guests' by the difference in volumes between the trimmed and untrimmed patterns. Therefore, say 'guest_pattern' has 1,000 points, 'min_thick = 0', 'max_thick = 40', and 'ztrim = 10', 'n_points' will be increased to 1,000 * (40-0)/(30-10) = 2,000. This way, after the trimming, about 1,000 guest points will remain (for dimers, this is number of guests / 2) and assign this many points in the scaled subsetted UPP to be guests. These are the "centroids"
Step 4: Determine the number of groups of each size. The number of points in groups of each size is simply the input variable 'size_fracs'. So We can divide this by the number of points in such a group size (1 for monomers, 2 for dimers, 3 for trimers, etc), and multiply by the total number of guest points
Step 5: Randomly relabel the scaled, subsetted UPP so that there is one point labeled guest type for each group and the rest are labeled host type.
Step 6: Randomly sample from the guest type points chosen in Step 5 a number of points equal to the number of groups that need to have two or more points
Step 7: Use create_groups to make one NN of each point chosen in Step 6 guest type. NN's are selected only in points from points assigned as hosts in Step 5.
Step 8: Repeat Steps 6 and 7 for trimers, quadramers, etc.
Step 9: Filter out all guest type points chosen in Steps 5-8 that all within 'ztrim' units of the top (+z) or bottom (-z)
Step 10: Create a 2D point pattern (class 'ppp') by ignoring the z coordinates of each point. Label guest type points "G" and host type points "H"