Package {fmx}

Type:	Package
Title:	Finite Mixture Parametrization
Version:	0.2.0
Date:	2026-07-16
Description:	A parametrization framework for finite mixture distribution using S4 objects. Density, cumulative density, quantile and simulation functions are defined. Currently normal, Tukey g-&-h, skew-normal and skew-t distributions are well tested. The gamma, negative binomial distributions are being tested.
License:	GPL-2
Encoding:	UTF-8
Language:	en-US
Depends:	R (≥ 4.6.0)
Imports:	methods, goftest, LaplacesDemon, rstpm2, sn, param2moment, TukeyGH77 (≥ 0.2.0)
Config/roxygen2/version:	8.0.0
NeedsCompilation:	no
Packaged:	2026-07-16 21:35:34 UTC; tingtingzhan
Author:	Tingting Zhan [aut, cre]
Maintainer:	Tingting Zhan <tingtingzhan@gmail.com>
Repository:	CRAN
Date/Publication:	2026-07-16 21:50:09 UTC

Finite Mixture Parametrization

Description

A parametrization framework for finite mixture distribution using S4 objects.

Density, cumulative density, quantile and simulation functions are defined.

Currently normal, Tukey g-&-h, skew-normal and skew-t distributions are well tested. The gamma, negative binomial distributions are being tested.

Author(s)

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

Authors:

• Tingting Zhan tingtingzhan@gmail.com (ORCID)

Subset of Components in fmx Object

Description

Taking subset of components in fmx object

Usage

## S3 method for class 'fmx'
x[i]

Arguments

Value

An fmx object consisting of a subset of components. Information about the observations (e.g. slots '@data' and '@data.name'), will be lost.

Empirical Density Function

Description

..

Usage

approxdens(x, ...)

Arguments

Details

approx inside density.default

another 'layer' of approxfun

Value

The function [approxdens()] returns a function.

Examples

set.seed(135); x = rnorm(1e3L)
(f = approxdens(x))
x[1:3] |> f()

Turn Various Objects to fmx Class

Description

Turn various objects created in other R packages to fmx class.

Usage

as.fmx(x, ...)

Arguments

Details

Various mixture distribution estimates obtained from other R packages are converted to fmx class, so that we could take advantage of all methods defined for fmx objects.

Value

S3 generic function [as.fmx()] returns an fmx object.

Parameter Estimates of fmx object

Description

..

Usage

## S3 method for class 'fmx'
coef(object, internal = FALSE, ...)

Arguments

Details

The function [coef.fmx()] returns the estimates of the user-friendly parameters (‘parm = ’user''), or the internal/unconstrained parameters (parm = 'internal'). When the distribution has constraints on one or more parameters, function [coef.fmx()] does not return the estimates (which is constant 0) of the constrained parameters.

Value

The function [coef.fmx()] returns a numeric vector.

Confidence Interval of fmx Object

Description

...

Usage

## S3 method for class 'fmx'
confint(object, ..., level = 0.95)

Arguments

Details

The function [confint.fmx()] returns the Wald-type confidence intervals based on the user-friendly parameters (‘parm = ’user''), or the internal/unconstrained parameters (‘parm = ’internal''). When the distribution has constraints on one or more parameters, function [confint.fmx()] does not return the confident intervals of for the constrained parameters.

Value

The function [confint.fmx()] returns a matrix

Inverse of [fmx2dbl], for internal use

Description

..

Usage

dbl2fmx(x, K, distname, ...)

Arguments

Details

Only used in downstream function 'QuantileGH::QLMDe' and unexported function 'QuantileGH:::qfmx_gr', not compute intensive.

Value

The function [dbl2fmx()] returns a list with two elements '$pars' and '$w'

Density, Distribution and Quantile of Finite Mixture Distribution

Description

Density function, distribution function, quantile function and random generation for a finite mixture distribution with normal or Tukey g-&-h components.

Usage

dfmx(
  x,
  dist,
  distname = dist@distname,
  K = dim(pars)[1L],
  pars = dist@pars,
  w = dist@w,
  ...,
  log = FALSE
)

pfmx(
  q,
  dist,
  distname = dist@distname,
  K = dim(pars)[1L],
  pars = dist@pars,
  w = dist@w,
  ...,
  lower.tail = TRUE,
  log.p = FALSE
)

qfmx(
  p,
  dist,
  distname = dist@distname,
  K = dim(pars)[1L],
  pars = dist@pars,
  w = dist@w,
  interval = qfmx_interval(dist = dist),
  ...,
  lower.tail = TRUE,
  log.p = FALSE
)

rfmx(
  n,
  dist,
  distname = dist@distname,
  K = dim(pars)[1L],
  pars = dist@pars,
  w = dist@w
)

Arguments

Details

A computational challenge in function [dfmx()] is when mixture density is very close to 0, which happens when the per-component log densities are negative with big absolute values. In such case, we cannot compute the log densities (i.e., '-Inf').

The function [qfmx()] gives the quantile function, by numerically solving [pfmx]. One major challenge when dealing with the finite mixture of Tukey g-&-h family distribution is that Brent–Dekker's method needs to be performed in both pGH and [qfmx] functions, i.e. *two layers* of root-finding algorithm.

Value

The function [dfmx()] returns a numeric vector of probability density values of an fmx object at specified quantiles 'x'.

The function [pfmx()] returns a numeric vector of cumulative probability values of an fmx object at specified quantiles 'q'.

The function [qfmx()] returns an unnamed numeric vector of quantiles of an fmx object, based on specified cumulative probabilities 'p'.

The function [rfmx()] generates random deviates of an fmx object.

Note

The function qnorm returns an unnamed vector of quantiles, although quantile returns a named vector of quantiles.

Name(s) of Formal Argument(s) of Distribution

Description

To obtain the name(s) of distribution parameter(s).

Usage

distArgs(distname)

Arguments

Value

The function [distArgs()] returns a character vector.

See Also

formalArgs

Distribution Type

Description

..

Usage

distType(type = c("discrete", "nonNegContinuous", "continuous"))

Arguments

Value

The function [distType()] returns a character vector.

Distribution Parameters that needs to have a log-transformation

Description

..

Usage

dist_logtrans(distname)

Arguments

Value

The function [dist_logtrans()] returns an integer scalar

Create fmx Object for Finite Mixture Distribution

Description

To create fmx object for finite mixture distribution.

Usage

fmx(distname, w = 1, ...)

Arguments

Value

The function [fmx()] returns an fmx object.

fmx Class: Finite Mixture Parametrization

Description

An S4 object to specify the parameters and type of distribution of a one-dimensional finite mixture distribution.

Slots

distname

character scalar, name of parametric distribution of the mixture components. Currently, normal (''norm'') and Tukey g-&-h (''GH'') distributions are supported.

pars

double matrix, all distribution parameters in the mixture. Each row corresponds to one component. Each column includes the same parameters of all components. The order of rows corresponds to the (non-strictly) increasing order of the component location parameters. The columns match the formal arguments of the corresponding distribution, e.g., ''mean'‘ and '’sd'' for Normal mixture, or ''A'‘, '’B'‘, '’g'‘ and '’h'' for Tukey g-&-h mixture.

w

numeric vector of mixing proportions that must sum to 1

data

(optional) numeric vector, the one-dimensional observations

data.name

(optional) character scalar, a human-friendly name of the observations

vcov_internal

(optional) variance-covariance matrix of the internal (i.e., unconstrained) estimates

vcov

(optional) variance-covariance matrix of the mixture distribution (i.e., constrained) estimates

dist.ks

(optional) double scalar, Kolmogorov-Smirnov distance, via ks.test

dist.cvm

(optional) double scalars, Cramer von Mises distance, via cvm.test

dist.kl

(optional) double scalars, Kullback-Leibler distance

logd

(optional) double vector, point-wise log-density

logLik

(optional) logLik object, log-likelihood

Reparameterization of fmx Object

Description

To convert the parameters of fmx object into unrestricted parameters.

Usage

fmx2dbl(
  x,
  distname = x@distname,
  pars = x@pars,
  K = dim(pars)[1L],
  w = x@w,
  ...
)

Arguments

Details

For the first parameter

• A_1 \rightarrow A_1

• A_2 \rightarrow A_1 + \exp(\log(d_1))

• A_k \rightarrow A_1 + \exp(\log(d_1)) + \cdots + \exp(\log(d_{k-1}))

For mixing proportions to multinomial logits.

For ''norm'': 'sd -> log(sd)' for ''GH'': 'B -> log(B), h -> log(h)'

Value

The function [fmx2dbl()] returns a numeric vector.

See Also

[dbl2fmx()]

Parameter Constraint(s) of Mixture Distribution

Description

Determine the parameter constraint(s) of a finite mixture distribution fmx, either by the value of parameters of such mixture distribution, or by a user-specified string.

Usage

fmx_constraint(
  dist,
  distname = dist@distname,
  K = dim(dist@pars)[1L],
  pars = dist@pars
)

Arguments

Value

The function [fmx_constraint()] returns the indices of internal parameters (only applicable to Tukey g-&-h mixture distribution, yet) to be constrained, based on the input fmx object 'dist'.

TeX Label (of Parameter Constraint(s)) of fmx Object

Description

Create TeX label of (parameter constraint(s)) of fmx object

Usage

getTeX(dist, print_K = FALSE)

Arguments

Value

The function [getTeX()] returns a character scalar (of TeX expression) of the constraint, primarily intended for end-users in plots.

Log-Likelihood of fmx Object

Description

Log-likelihood of an fmx object.

Usage

## S3 method for class 'fmx'
logLik(object, ...)

Arguments

Value

The function [logLik.fmx()] returns a logLik object.

Multinomial Probabilities & Logits

Description

Transformation between the vectors of multinomial probabilities and logits.

Usage

qmlogis(p)

pmlogis(q)

Arguments

Details

The function [pmlogis()] takes a length k-1 double vector of multinomial logits q and convert them into length k multinomial probabilities p, regarding the *first* category as reference.

The function [qmlogis()] takes a length k double vector of multinomial probabilities p and convert them into length k-1 multinomial logits q, regarding the *first* category as reference.

Value

The function [pmlogis()] returns a double vector of multinomial probabilities p.

The function [qmlogis()] returns a double vector of multinomial logits q.

Note

This transformation is a generalization of functions plogis (i.e., logit to probability) and qlogis (i.e., probability to logit).

Examples

c(2,5,3) |> qmlogis() |> pmlogis()

# various exceptions
c(1, 0) |> qmlogis() |> pmlogis()
c(0, 1) |> qmlogis() |> pmlogis()
c(0, 0, 1) |> qmlogis() |> pmlogis()
c(1, 0, 0, 0) |> qmlogis() |> pmlogis()
c(0, 1, 0, 0) |> qmlogis() |> pmlogis()
c(0, 0, 1, 0) |> qmlogis() |> pmlogis()
   

Creates fmx Object with Given Component-Wise Moments

Description

Creates fmx Object with Given Component-Wise Moments

Usage

moment2fmx(distname, w, ...)

Arguments

Value

The function [moment2fmx()] returns a fmx object.

Moment of Each Component in an fmx Object

Description

To find moments of each component in an fmx object.

Usage

moment_fmx(object)

Arguments

Details

The function [moment_fmx()] calculates the moments and distribution characteristics of each mixture component of an S4 fmx object.

Value

The function [moment_fmx()] returns an object of the S4 moment-class.

Number of Observations in fmx Object

Description

Number of observations in an fmx object.

Usage

## S3 method for class 'fmx'
nobs(object, ...)

Arguments

Details

The function [nobs.fmx()] finds the sample size of '@data' slot of an fmx object.

Value

The function [nobs.fmx()] returns an integer scalar.

Number of Parameters of fmx Object

Description

..

Usage

npar.fmx(dist)

Arguments

Details

Also the degree-of-freedom in logLik, as well as 'stats:::AIC.logLik' and 'stats:::BIC.logLik'

Value

The function [npar.fmx()] returns an integer scalar.

S3 print of fmx Object

Description

..

Usage

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

Arguments

Value

The function [print.fmx()] returns the input fmx object invisibly.

Obtain 'interval' for vuniroot for Function [qfmx()]

Description

Obtain 'interval' for vuniroot for Function [qfmx()]

Usage

qfmx_interval(
  dist,
  p = c(1e-06, 1 - 1e-06),
  distname = dist@distname,
  K = dim(pars)[1L],
  pars = dist@pars,
  w = dist@w,
  ...
)

Arguments

Value

The function [qfmx_interval()] returns a length-2 numeric vector.

Show fmx Object

Description

Print the parameters of an fmx object and plot its density curves.

Usage

## S4 method for signature 'fmx'
show(object)

Arguments

Value

The show method for fmx object does not have a returned value.

Formalize User-Specified Constraint of fmx Object

Description

Formalize user-specified constraint of fmx object

Usage

user_constraint(x, distname, K)

Arguments

Value

The function [user_constraint()] returns the indices of internal parameters (only applicable to Tukey's g-&-h mixture distribution, yet) to be constrained, based on the type of distribution 'distname', number of components 'K' and a user-specified string (e.g., ‘c(’g2', 'h1')').

Variance-Covariance of fmx Object

Description

..

Usage

## S3 method for class 'fmx'
vcov(object, internal = FALSE, ...)

Arguments

Details

The function [vcov.fmx()] returns the approximate asymptotic variance-covariance matrix of the user-friendly parameters via delta-method (‘parm = ’user''), or the asymptotic variance-covariance matrix of the internal/unconstrained parameters (‘parm = ’internal''). When the distribution has constraints on one or more parameters, function [vcov.fmx()] does not return the variance/covariance involving the constrained parameters.

Value

The function [vcov.fmx()] returns a matrix.