Type: Package
Title: Additional Predictor with Maximum Effect Size
Version: 0.2.0
Description: Methods of selecting one from many numeric predictors for a regression model, to ensure that the additional predictor has the maximum effect size.
RoxygenNote: 7.3.3
Encoding: UTF-8
License: GPL-2
Depends: R (≥ 4.5)
Language: en-US
URL: https://github.com/tingtingzhan/maxEff
Imports: parallel, doParallel, foreach, caret, rpart, spatstat.geom, groupedHyperframe (≥ 0.3.0)
Suggests: knitr, quarto, rmarkdown, survival
VignetteBuilder: quarto
NeedsCompilation: no
Packaged: 2025-10-14 01:27:02 UTC; tingtingzhan
Author: Tingting Zhan ORCID iD [aut, cre], Inna Chervoneva ORCID iD [aut]
Maintainer: Tingting Zhan <tingtingzhan@gmail.com>
Repository: CRAN
Date/Publication: 2025-10-14 10:40:02 UTC

maxEff: Additional Predictor with Maximum Effect Size

Description

Methods of selecting one from many numeric predictors for a regression model, to ensure that the additional predictor has the maximum effect size.

Note

Help files of individual functions are intentionally suppressed in this pdf manual. Users are encouraged to get started with

vignette('intro', package = 'maxEff')

Author(s)

Maintainer: Tingting Zhan tingtingzhan@gmail.com (ORCID)

Authors:

See Also

Useful links:

Additional logical Predictor

Description

Additional logical Predictor

Usage

add_dummy(
  start.model,
  x,
  data = eval(start.model$call$data),
  mc.cores = getOption("mc.cores"),
  ...
)

Arguments

start.model

a regression model, e.g., lm, glm, or coxph, etc.

x

one-sided formula, numeric predictors x's as the columns of one matrix column in data

data

(optional) data.frame in the model call of start.model

mc.cores

integer scalar, see function mclapply

Value

Function add_dummy() returns an object of class 'add_dummy'.

Additional logical Predictor via Repeated Partitioning

Description

Additional logical Predictor via Repeated Partitioning

Usage

add_dummy_partition(
  start.model,
  x,
  data = eval(start.model$call$data),
  times,
  mc.cores = getOption("mc.cores"),
  ...
)

Arguments

start.model

a regression model, e.g., lm, glm, or coxph, etc.

x

one-sided formula, numeric predictors x's as the columns of one matrix column in data

data

(optional) data.frame in the model call of start.model

times, ...

additional parameters of function createDataPartition or statusPartition()

mc.cores

integer scalar, see function mclapply

Value

Function add_dummy_partition() returns an object of class 'add_dummy'.

Additional Predictor as numeric

Description

Additional predictor as numeric.

Usage

add_numeric(
  start.model,
  x,
  data = eval(start.model$call$data),
  mc.cores = getOption("mc.cores"),
  ...
)

Arguments

start.model

a regression model (e.g., lm, glm, or coxph, etc.)

x

one-sided formula to specify the numeric predictors x's as the columns of one matrix column in data

data

data.frame

mc.cores

integer scalar, see function mclapply

...

additional parameters, currently of no use

Details

Function add_numeric() treats each additional predictor as a numeric variable, and updates the starting model with each additional predictor.

Value

Function add_numeric() returns an add_numeric object, which is a listof objects with an internal class 'add_numeric_'.

Get Cutoff Value from a Dichotomizing Rule node1()

Description

To get the cutoff value from a Dichotomizing Rule node1().

Usage

get_cutoff(x)

## S3 method for class 'node1'
get_cutoff(x)

Arguments

x

see Usage

Value

Function get_cutoff.node1() returns a numeric scalar.

labels.add_dummy

Description

labels.add_dummy

Usage

## S3 method for class 'add_dummy'
labels(object, ...)

Arguments

object

a add_dummy object

...

..

Value

Function labels.add_dummy() returns a character vector.

labels.add_numeric

Description

labels.add_numeric

Usage

## S3 method for class 'add_numeric'
labels(object, ...)

Arguments

object

a add_numeric object

...

..

Value

Function labels.add_numeric() returns a character vector.

Find labels from node1

Description

Find labels from node1

Usage

## S3 method for class 'node1'
labels(object, ...)

Arguments

object

a node1 object

...

additional parameters, currently not in use

Value

Function labels.node1() returns a character scalar.

Dichotomize via 1st Node of Recursive Partitioning

Description

Dichotomize via 1st Node of Recursive Partitioning

Usage

node1(object, nm = as.symbol(rownames(s)[1L]), ...)

Arguments

object

an rpart.object

nm

symbol, or name, of the variable being partitioned

...

additional parameters, currently not in use

Value

Function node1() returns an object of class 'node1', which is a function with one parameter newx taking a double vector.

Note

In future integer and factor predictors will be supported.

Predict by node1()

Description

Predict by node1()

Usage

## S3 method for class 'node1'
predict(object, newdata, ...)

Arguments

object

a node1 object

newdata

a data.frame or hyperframe

...

place holder for S3 generic

Regression Models with Optimal Dichotomizing Predictors

Description

Regression models with optimal dichotomizing predictor(s), used either as boolean or continuous predictor(s).

Usage

## S3 method for class 'add_dummy'
predict(object, ...)

## S3 method for class 'add_dummy_'
predict(object, newdata, ...)

Arguments

object

an add_dummy_ object, as an element of the listof return from functions add_dummy() or add_dummy_partition()

...

additional parameters, currently not in use

newdata

data.frame, candidate numeric predictors x's must have the same name and dimension as the training data. If missing, the training data is used

Value

Function predict.add_dummy() returns a listof regression models.

Function predict.add_dummy_() returns a updated regression model.

Regression Models with Optimal Dichotomizing Predictors

Description

Regression models with optimal dichotomizing predictor(s), used either as boolean or continuous predictor(s).

Usage

## S3 method for class 'add_numeric'
predict(object, ...)

## S3 method for class 'add_numeric_'
predict(object, newdata, ...)

Arguments

object

an add_numeric object

...

additional parameters of function predict.add_numeric_, e.g., newdata

Value

Function predict.add_numeric() returns a listof regression models.

print.add_dummy

Description

print.add_dummy

Usage

## S3 method for class 'add_dummy'
print(x, ...)

Arguments

x

an object returned from functions add_dummy_partition() or add_dummy()

...

additional parameters, currently not in use

Details

..

Value

Function print.add_dummy() does not have a returned value

print.add_numeric

Description

print.add_numeric

Usage

## S3 method for class 'add_numeric'
print(x, ...)

Arguments

x

a add_numeric object

...

..

sort_by.add_

Description

sort_by.add_

Usage

## S3 method for class 'add_'
sort_by(x, y, ...)

Arguments

x

an object returned from functions add_dummy_partition(), add_dummy() or add_numeric()

y

language, see function sort_by

...

additional parameters of S3 generic sort_by, etc.

Details

Function sort_by.add_() sorts the elements of an 'add_' object by a certain criterion y. We suggest using y = abc(effsize) and decreasing = TRUE order of the absolute values of the effect sizes of additional predictor.

Value

Function sort_by.add_() returns an object of the same class as input x.

Split-Dichotomized Regression Model

Description

Split-dichotomized regression model.

Usage

splitd(start.model, x_, x, data, id, ...)

Arguments

start.model

a regression model

x_

language

x

numeric vector

data

hyperframe

id

logical vector, indices of training (TRUE) and test (FALSE) subjects

...

additional parameters, currently not in use

Value

Function splitd() returns a function, the dichotomizing rule \mathcal{D} based on the training set (y_0, x_0), with additional attributes

attr(,'p1')

double scalar, p_1 = \text{Pr}(\mathcal{D}(x_1)=1)

attr(,'effsize')

double scalar, univariable regression coefficient estimate of y_1\sim\mathcal{D}(x_1)

Split-Dichotomized Regression Model

Function splitd() performs a univariable regression model on the test set with a dichotomized predictor, using a dichotomizing rule determined by a recursive partitioning of the training set. Specifically, given a training-test sample split,

  1. find the dichotomizing rule \mathcal{D} of the predictor x_0 given the response y_0 in the training set (via function node1());

  2. fit a univariable regression model of the response y_1 with the dichotomized predictor \mathcal{D}(x_1) in the test set.

Currently the Cox proportional hazards (coxph) regression for Surv response, logistic (glm) regression for logical response and linear (lm) regression for gaussian response are supported.

Stratified Partition

Description

A variation of createDataPartition, to split Surv y by survival status instead of the percentiles survival time.

Usage

statusPartition(y, times, p = 0.8, ...)

Arguments

y

response y, a Surv object

times

positive integer scalar n, number of replicates of partitions. Default 1L.

p

double scalar between 0 and 1, percentage p of training subjects, default .8

...

additional parameters, currently not in use

Details

See vignette('intro', package = 'maxEff').

Value

Function statusPartition() returns a length-n listof integer vectors. In each integer vector indicates the training subjects.

Note

Function caTools::sample.split is not what we need.

S3 Method Dispatches to 'add_dummy' Class

Description

S3 Method Dispatches to 'add_dummy' Class

Usage

## S3 method for class 'add_dummy'
subset(x, subset, ...)

Arguments

x

an object returned from functions add_dummy_partition() or add_dummy()

subset

language

...

additional parameters of function predict.add_dummy_(), e.g., newdata

Details

Function subset.add_dummy(), default subset (p1>.15 & p1<.85). See explanation of p_1 in function splitd().

Value

Function subset.add_dummy() returns a add_dummy() object.