LogisticRegression

Fits binomial generalized linear models with stats::glm(family = binomial()) for binary outcomes. associate$regression instantiates this family for model = "glm", which model = "auto" also picks for a logical outcome, a two-level factor, a numeric column whose values are all in {0, 1}, or a character column with at most two distinct values.

The outcome is recoded to 0/1 before fitting: a logical takes its integer form, a factor or character takes its second level as the case. The fit aborts when the outcome is a factor or character with a number of levels other than two, a numeric with a value outside {0, 1}, or any other type.

The fitted model is outcome ~ predictor [* interaction] [+ covariates] on complete cases, with case weights when the resolved frame carries a weights column.

Result rows follow the "glm" association schema (schemaGlm() in associate-schemas.R): one row per predictor main and interaction coefficient, on the log-odds scale (effect.scale = "log.odds", test = "z"), with normal Wald limits and n.cases/n.controls counted from the fitted 0/1 response.

The single artifact is prediction.grid, evaluated with predict(type = "response") so fitted.value is a probability, across the observed predictor range with covariates at their reference values.

PolyGenius::RegressionFamily -> LogisticRegression

Public methods

• LogisticRegression$new()
• LogisticRegression$validate.frame()
• LogisticRegression$prepare.frame()
• LogisticRegression$describe.model.terms()
• LogisticRegression$build.formula()
• LogisticRegression$fit.model()
• LogisticRegression$build.summary.rows()
• LogisticRegression$build.artifacts()
• LogisticRegression$clone()

Method new()

Register this family under the key "glm".

Usage

LogisticRegression$new()

Returns

A new LogisticRegression.

Method validate.frame()

Check that the outcome column is binary before any model is built.

Usage

LogisticRegression$validate.frame(frame, cell, fit.specs, conf.level)

Arguments

frame — A data.table resolved from a PolyGeniusStudy, whose roles() tags identify the outcome column.

cell — Named list describing one fit cell. Unused; the outcome is resolved from the frame's roles.

fit.specs — Named list of extra fitting options. Unused.

conf.level — Numeric scalar in (0, 1). Unused.

Returns

TRUE, invisibly. Aborts when the outcome is not logical, not 0/1 numeric, and not a two-level factor or character column.

Method prepare.frame()

Reduce the resolved frame to the columns this fit uses, recode the outcome to a 0/1 integer, and drop rows missing any of them.

Usage

LogisticRegression$prepare.frame(frame, cell, fit.specs, conf.level)

Arguments

frame — A data.table resolved from a PolyGeniusStudy, whose roles() tags identify the outcome, predictor, interaction, covariate and weight columns.

cell — Named list describing one fit cell. Unused; columns come from the frame's roles.

fit.specs — Named list of extra fitting options. Unused.

conf.level — Numeric scalar in (0, 1). Unused.

Returns

Named list: data (complete-case data.frame with a 0/1 outcome), outcome.name, predictor.name, predictor.label, interaction.name, covariate.names, weights.name (NA_character_ when none) and row.id, the retained row indices into frame.

Method describe.model.terms()

Extend the shared right-hand-side term descriptors with the binary outcome, which is non-estimable when every observation is a case or every observation is a control.

Usage

LogisticRegression$describe.model.terms(fit.data)

Arguments

fit.data — Named list returned by prepare.frame().

Returns

List of list(column, role, label) descriptors: the base class's terms plus one with role = "outcome.binary".

Method build.formula()

Build outcome ~ predictor [* interaction] [+ covariates] from the original column names.

Usage

LogisticRegression$build.formula(frame)

Arguments

frame — Named list returned by prepare.frame().

Returns

A formula, carrying its printable form as the "display.formula" attribute.

Method fit.model()

Fit the model with stats::glm(family = binomial()), adding case weights when prepare.frame() resolved a weights column.

Usage

LogisticRegression$fit.model(formula, frame, ...)

Arguments

formula — A formula from build.formula().

frame — Named list returned by prepare.frame().

... — Further arguments passed to stats::glm().

Returns

A fitted glm object.

Method build.summary.rows()

Turn the fitted model's predictor coefficients into standard result rows on the log-odds scale, counting n.cases and n.controls from the fitted 0/1 response.

Usage

LogisticRegression$build.summary.rows(
  fit,
  fit.data,
  cell,
  fit.specs,
  conf.level,
  formula
)

Arguments

fit — A fitted glm object.

fit.data — Named list returned by prepare.frame().

cell — Named list describing one fit cell: fit.id, analysis.id, family, outcome, predictor, interaction, stratum.

fit.specs — Named list of extra fitting options. Unused.

conf.level — Numeric scalar in (0, 1). Confidence level for lower/upper, taken from the normal distribution.

formula — Character scalar. Display formula recorded on each row.

Returns

A data.table of "glm"-schema rows, one per predictor main and interaction coefficient. Aborts when no coefficient name matches the predictor.

Method build.artifacts()

Build the fitted-probability grid that effect plots read.

Usage

LogisticRegression$build.artifacts(
  fit,
  fit.data,
  cell,
  fit.specs,
  conf.level,
  formula
)

Arguments

fit — A fitted glm object.

fit.data — Named list returned by prepare.frame().

cell — Named list describing one fit cell.

fit.specs — Named list of extra fitting options. Unused.

conf.level — Numeric scalar in (0, 1). Unused.

formula — Character scalar. Unused; present for interface parity.

Returns

Named list with one element, prediction.grid: a data.frame of predictor.value, fitted.value (a probability) and se alongside the fit identity columns (analysis.id, fit.id, schema, family, outcome, predictor, stratum).

Method clone()

The objects of this class are cloneable with this method.

Usage

LogisticRegression$clone(deep = FALSE)

Arguments

deep — Whether to make a deep clone.

associate$regression, LinearRegression for continuous outcomes, CoxRegression and CompetingRiskRegression for survival outcomes.

Other regression-families: CompetingRiskRegression, CoxRegression, KaplanMeierRegression, LinearRegression, RegressionFamily