ForLion (version 0.1.0)

ForLion_MLM_Optimal: ForLion function for multinomial logit models

Description

Function for ForLion algorithm to find D-optimal design under multinomial logit models with mixed factors. Reference Section 3 of Huang, Li, Mandal, Yang (2024). Factors may include discrete factors with finite number of distinct levels and continuous factors with specified interval range (min, max), continuous factors, if any, must serve as main-effects only, allowing merging points that are close enough. Continuous factors first then discrete factors, model parameters should in the same order of factors.

Usage

ForLion_MLM_Optimal(
  J,
  n.factor,
  factor.level,
  hfunc,
  h.prime,
  bvec,
  link = "continuation",
  Fi.func = Fi_MLM_func,
  delta = 1e-05,
  epsilon = 1e-12,
  reltol = 1e-05,
  rel.diff = 0,
  maxit = 100,
  random = FALSE,
  nram = 3,
  rowmax = NULL,
  Xini = NULL,
  random.initial = FALSE,
  nram.initial = 3,
  optim_grad = FALSE
)

Value

m the number of design points

x.factor matrix of experimental factors with rows indicating design point

p the reported D-optimal approximate allocation

det the determinant of the maximum Fisher information

convergence TRUE or FALSE, whether converge

min.diff the minimum Euclidean distance between design points

x.close pair of design points with minimum distance

itmax iteration of the algorithm

Arguments

J

number of response levels in the multinomial logit model

n.factor

vector of numbers of distinct levels, "0" indicates continuous factors, "0"s always come first, "2" or above indicates discrete factor, "1" is not allowed

factor.level

list of distinct levels, (min, max) for continuous factor, continuous factors first, should be the same order as n.factor

hfunc

function for obtaining model matrix h(y) for given design point y, y has to follow the same order as n.factor

h.prime

function to obtain dX/dx

bvec

assumed parameter values of model parameters beta, same length of h(y)

link

link function, default "continuation", other choices "baseline", "cumulative", and "adjacent"

Fi.func

function to calculate row-wise Fisher information Fi, default is Fi_MLM_func

delta

tuning parameter, the generated design pints distance threshold, || x_i(0) - x_j(0) || >= delta, default 1e-5

epsilon

for determining f.det > 0 numerically, f.det <= epsilon will be considered as f.det <= 0, default 1e-12

reltol

the relative convergence tolerance, default value 1e-5

rel.diff

points with distance less than that will be merged, default value 0

maxit

the maximum number of iterations, default value 100

random

TRUE or FALSE, if TRUE then the function will run lift-one with additional "nram" number of random approximate allocation, default to be FALSE

nram

when random == TRUE, the function will run lift-one nram number of initial proportion p00, default is 3

rowmax

maximum number of points in the initial design, default NULL indicates no restriction

Xini

initial list of design points, default NULL will generate random initial design points

random.initial

TRUE or FALSE, if TRUE then the function will run ForLion with additional "nram.initial" number of random initial design points, default FALSE

nram.initial

when random.initial == TRUE, the function will run ForLion algorithm with nram.initial number of initial design points Xini, default is 3

optim_grad

TRUE or FALSE, default is FALSE, whether to use the analytical gradient function or numerical gradient for searching optimal new design point

Examples

m=5
p=10
J=5
link.temp = "cumulative"
n.factor.temp = c(0,0,0,0,0,2)  # 1 discrete factor w/ 2 levels + 5 continuous
## Note: Always put continuous factors ahead of discrete factors,
## pay attention to the order of coefficients paring with predictors
factor.level.temp = list(c(-25,25), c(-200,200),c(-150,0),c(-100,0),c(0,16),c(-1,1))
hfunc.temp = function(y){
if(length(y) != 6){stop("Input should have length 6");}
 model.mat = matrix(NA, nrow=5, ncol=10, byrow=TRUE)
 model.mat[5,]=0
 model.mat[1:4,1:4] = diag(4)
 model.mat[1:4, 5] =((-1)*y[6])
 model.mat[1:4, 6:10] = matrix(((-1)*y[1:5]), nrow=4, ncol=5, byrow=TRUE)
 return(model.mat)
 }
bvec.temp=c(-1.77994301, -0.05287782,  1.86852211, 2.76330779, -0.94437464, 0.18504420,
-0.01638597, -0.03543202, -0.07060306, 0.10347917)

h.prime.temp = NULL #use numerical gradient (optim_grad=FALSE)
ForLion_MLM_Optimal(J=J, n.factor=n.factor.temp, factor.level=factor.level.temp, hfunc=hfunc.temp,
h.prime=h.prime.temp, bvec=bvec.temp, link=link.temp, optim_grad=FALSE)