Type: Package
Title: A 'tidymodels' Engine and Other Extensions for the 'midr' Package
Version: 0.2.0
Description: Provides a 'parsnip' engine for the 'midr' package, enabling users to fit, tune, and evaluate Maximum Interpretation Decomposition (MID) models within the 'tidymodels' framework. Developed through research by the Moonlight Seminar 2025, a study group of actuaries from the Institute of Actuaries of Japan, to enhance practical applications of interpretable modeling. Detailed methodology is available in Asashiba et al. (2025) <doi:10.48550/arXiv.2506.08338>.
License: MIT + file LICENSE
Encoding: UTF-8
Imports: graphics, midr (≥ 0.6.0), rlang, Rcpp, stats, utils
Suggests: colormap, DALEX, ggbeeswarm, ggforce, ggplot2, MetBrewer, parsnip
RoxygenNote: 7.3.2
URL: https://github.com/ryo-asashi/midnight, https://ryo-asashi.github.io/midnight/
BugReports: https://github.com/ryo-asashi/midnight/issues
LinkingTo: Rcpp, RcppEigen
Config/Needs/website: rmarkdown
NeedsCompilation: yes
Packaged: 2026-04-02 21:20:21 UTC; daysb
Author: Ryoichi Asashiba ORCID iD [aut, cre]
Maintainer: Ryoichi Asashiba <ryoichi.asashiba@gmail.com>
Repository: CRAN
Date/Publication: 2026-04-09 08:50:02 UTC

midnight: A 'tidymodels' Engine and Other Extensions for the 'midr' Package

Description

logo

Provides a 'parsnip' engine for the 'midr' package, enabling users to fit, tune, and evaluate Maximum Interpretation Decomposition (MID) models within the 'tidymodels' framework. Developed through research by the Moonlight Seminar 2025, a study group of actuaries from the Institute of Actuaries of Japan, to enhance practical applications of interpretable modeling. Detailed methodology is available in Asashiba et al. (2025) doi:10.48550/arXiv.2506.08338.

Author(s)

Maintainer: Ryoichi Asashiba ryoichi.asashiba@gmail.com (ORCID)

See Also

Useful links:

Fit Multivariate Linear Models

Description

fastLmMatrix() estimates the linear model for multivariate response using one of several methods implemented using the Eigen linear algebra library.

Usage

fastLmMatrix(x, ...)

## Default S3 method:
fastLmMatrix(x, y, tol = 1e-07, method = 0L, ...)

## S3 method for class 'formula'
fastLmMatrix(formula, data = list(), method = 0L, ...)

Arguments

x

a model matrix X.

...

optional parameters passed to methods.

y

the response matrix Y.

tol

tolerance for the rank calculation.

method

an integer with value 0 for the column-pivoted QR decomposition, 1 for the unpivoted QR decomposition, 2 for the LLT Cholesky, 3 for the LDLT Cholesky, and 4 for the Jacobi singular value decomposition (SVD). Default is zero.

formula

an object of class "formula" (or one that can be coerced to that class): a symbolic description of the model to be fitted.

data

an optional data frame, list or environment (or object coercible by as.data.frame to a data frame) containing the variables in the model.

Details

fastLmMatrix() is a performance-optimized version of the standard lm.fit() function. Unlike RcppEigen::fastLm(), it is specifically designed to handle multivariate responses (Y as a matrix). It leverages the Eigen C++ template library for high-performance linear algebra, providing several decomposition methods with different trade-offs between speed and numerical stability.

Value

fastLmMatrix() returns a list with the following components:

coefficients

p \times k matrix of coefficients.

fitted.values

n \times k matrix of fitted values.

residuals

n \times k matrix of residuals.

rank

an integer giving the numeric rank of the model matrix X.

See Also

lm.fit, fastLm

Plot MID Importance with ggplot2

Description

The midnight package extends midr::ggmid() to provide modern distribution plots for MID feature importance. Added types include sina, beeswarm, and violin plots.

Usage

## S3 method for class 'midimp'
ggmid(object, type = NULL, theme = NULL, terms = NULL, max.nterms = 30, ...)

Arguments

object

a "midimp" object to be visualized.

type

the plotting style. In addition to standard types ("barplot", "boxplot", "dotchart", "heatmap"), this extended method supports "violinplot", "sinaplot", and "beeswarm".

theme

a character string or object defining the color theme. See color.theme for details.

terms

an optional character vector specifying which terms to display.

max.nterms

an integer specifying the maximum number of terms to display. Defaults to 30.

...

optional parameters passed on to the layers.

Details

This is an S3 method for the midr::ggmid() generic for "midimp" objects created by midr::mid.importance(). This method replaces the primary layer with modern distribution geoms when type is one of the extended options.

Value

ggmid.midimp() returns a "ggplot" object.

Note

This S3 method is NOT registered automatically when the midnight package is loaded, and activated when nightfall() is explicitly called.

See Also

nightfall, mid.importance

MID Regression

Description

mid_reg() defines a model that can predict numeric values from predictors using a set of functions each with up to two predictors. This function fits a regression model based on the Maximum Interpretation Decomposition.

Usage

mid_reg(
  mode = "regression",
  engine = "midr",
  model = NULL,
  params_main = NULL,
  params_inter = NULL,
  penalty = NULL,
  terms = NULL
)

fit_mid_reg(
  formula,
  data,
  weights = NULL,
  model = NULL,
  params_main = NULL,
  params_inter = NULL,
  penalty = NULL,
  terms = NULL,
  ...
)

Arguments

mode

a single character string for the type of model. Currently, only "regression" is supported.

engine

a single character string specifying the computational engine to use. The default is "midr".

model

an optional fitted model object (black-box model) to be interpreted. Default is NULL.

params_main

an integer specifying the maximum number of sample points (knots) to model main effects. Corresponds to the argument k[1] in midr::interpret().

params_inter

an integer specifying the maximum number of sample points (knots) to model interaction effects. Corresponds to the argument k[2] or k2 in midr::interpret().

penalty

a non-negative number representing the total amount of regularization. Corresponds to the argument lambda in midr::interpret().

terms

a character vector or formula of term labels to be included in the fitting process.

formula

an object of class formula: a symbolic description of the model to be fitted.

data

a data frame containing the variables in the model.

weights

an optional vector of case weights.

...

other arguments to be passed on to midr::interpret().

Details

This function is the main specification for the parsnip model. The underlying fitting is performed by fit_mid_reg(), which is a helper function that connects fit() to the midr::interpret() function.

Value

a "model_spec" object with class "mid_reg".

See Also

interpret

Transition into and out of Midnight

Description

nightfall() activates the extended features provided by the midnight package. It overrides specific S3 methods (such as ggmid.midimp), switches the underlying solvers to highly optimized Eigen-based routines via global options, and applies midnight-themed color palettes.

daybreak() reverses these changes, restoring the default behavior, solvers, and themes of the midr package.

Usage

nightfall(methods = TRUE, solvers = TRUE, themes = TRUE)

daybreak(methods = TRUE, solvers = TRUE, themes = TRUE)

Arguments

methods

logical. If TRUE, overrides (or restores) the ggmid.midimp S3 method.

solvers

logical. If TRUE, sets (or restores) calculation solvers via options() (e.g., midr.solver.qr, midr.solver.svd). These optimized solvers can be utilized by specifying the corresponding method in interpret() (e.g., method = "qr").

themes

logical. If TRUE, applies (or restores) color themes by setting options() for midr.qualitative, midr.sequential, and midr.diverging.

Value

nightfall() and daybreak() return an invisible list containing the previous options for solvers and themes.

Perspective Plot of MID Effects

Description

Visualizes the combined effect of two variables from a "mid" object using a 3D perspective plot.

Usage

## S3 method for class 'mid'
persp(object, xvar, yvar = NULL, ..., xval = NULL, yval = NULL)

Arguments

object

a "mid" object, typically the result of midr::interpret().

xvar

a character string with the name of the variable for the x-axis. Alternatively, a single string in the format xvar:yvar can be provided, in which case yvar can be omitted.

yvar

a character string with the name of the variable for the y-axis.

...

additional arguments passed on to graphics:::persp.default(). Used to customize the plot's appearance, such as view angles (theta, phi) or color (col).

xval

a numeric or character vector specifying the sequence of values for the x-axis.

yval

a numeric or character vector specifying the sequence of values for the y-axis.

Details

This is an S3 method for the persp() generic that calculates the sum of the main effects of xvar and yvar and their interaction effect (xvar:yvar). The resulting sum is plotted as the height on the z-axis.

Value

persp.mid() invisibly returns the viewing transformation matrix, see persp for details. This function is primarily called for its side effect of creating a plot.

See Also

persp

Examples

mid <- midr::interpret(mpg ~ wt * hp + factor(am), data = mtcars, lambda = .5)

# Create a basic perspective plot
persp(mid, xvar = "wt", yvar = "hp")

# Customize the plot by passing arguments to graphics:::persp.default()
persp(mid, "wt", "hp", theta = 210, phi = 20, col = "lightblue", shade = .5)
persp(mid, "factor(am):wt", theta = 210, shade = .2)