% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/vmgeom_vst.R
\name{vmgeom_vst}
\alias{vmgeom_vst}
\alias{vmgeom_vst_from_magn}
\alias{vmgeom_vst_to_r}
\title{Variance-Stabilizing Transformation for Geometric Visual Meteor Magnitudes}
\usage{
vmgeom_vst_from_magn(m, lm)

vmgeom_vst_to_r(tm, log = FALSE, deriv_degree = 0L)
}
\arguments{
\item{m}{integer; meteor magnitude.}

\item{lm}{numeric; limiting magnitude.}

\item{tm}{numeric; transformed magnitude.}

\item{log}{logical; if \code{TRUE}, the logarithm of the population index \code{r} is returned.}

\item{deriv_degree}{integer; the order of the derivative at \code{tm} to return
instead of \code{r} or \code{log(r)}. Must be \code{0}, \code{1}, or \code{2}.}
}
\value{
\itemize{
\item \code{vmgeom_vst_from_magn}: numeric value, the transformed meteor magnitude.
\item \code{vmgeom_vst_to_r}: numeric value of the population index \code{r}, derived from
the mean of \code{tm}.
}

The argument \code{deriv_degree} can be used to apply the delta method.
If \code{log = TRUE}, the logarithm of \code{r} is returned.
}
\description{
Applies a variance-stabilizing transformation to visual meteor magnitudes
under the geometric model.
}
\details{
Many linear models require the variance of visual meteor magnitudes to be
homoscedastic. The function \code{vmgeom_vst_from_magn} applies a transformation
that produces homoscedastic distributions of visual meteor magnitudes if the
underlying distribution follows a geometric model.

The geometric model of visual meteor magnitudes
depends on the \link[=vmgeom]{population index} \code{r} and the limiting magnitude \code{lm},
resulting in a two-parameter distribution. Without detection probabilities,
the magnitude distribution is purely geometric, and for integer limiting
magnitudes the variance depends only on the population index \code{r}. Since the
limiting magnitude \code{lm} is a fixed parameter and never estimated
statistically, the magnitudes can be transformed such that, for example,
the mean of the transformed magnitudes directly provides an estimate of \code{r}
using the function \code{vmgeom_vst_to_r}.

A key advantage of this transformation is that the limiting magnitude \code{lm}
is already incorporated into subsequent analyses. In this sense, the
transformation acts as a normalization of meteor magnitudes and yields a
variance close to \code{1.0}.

This transformation is valid for \eqn{1.4 \le r \le 3.5}.
The numerical form of the transformation is version-specific and may change
substantially in future releases. Do not rely on equality of transformed
values across package versions.
}
\note{
The internal approximations used here are derived from the perception
probabilities produced by \link{vmperception}.
For details on the derivation, see the script \code{inst/derivation/vmgeom_vst.R} in the
package's source code.
}
\examples{
N <- 100
r <- 2.0
limmag <- 6.3

# Simulate magnitudes
m <- rvmgeom(N, limmag, r)

# Variance-stabilizing transformation
tm <- vmgeom_vst_from_magn(m, limmag)
tm_mean <- mean(tm)
tm_var <- var(tm)

# Estimator for r from the transformed mean
r_hat <- vmgeom_vst_to_r(tm_mean)

# Derivative dr/d(tm) at tm_mean (needed for the delta method)
dr_dtm <- vmgeom_vst_to_r(tm_mean, deriv_degree = 1L)

# Variance of the sample mean of tm
var_tm.mean <- tm_var / N

# Delta method: variance and standard error of r_hat
var_r.hat <- (dr_dtm^2) * var_tm.mean
se_r.hat <- sqrt(var_r.hat)

# Results
print(r_hat)
print(se_r.hat)
}
\seealso{
\link{vmgeom} \link{vmperception}
}
