LogNormal

il y a 9 heures

Library "LogNormal"
A collection of functions used to model skewed distributions as log-normal.

Prices are commonly modeled using log-normal distributions (ie. Black-Scholes) because they exhibit multiplicative changes with long tails; skewed exponential growth and high variance. This approach is particularly useful for understanding price behavior and estimating risk, assuming continuously compounding returns are normally distributed.

Because log space analysis is not as direct as using math.log(price), this library extends the Error Functions library to make working with log-normally distributed data as simple as possible.

- - -

QUICK START

1. Import library into your project
   
2. Initialize model with a mean and standard deviation
   
3. Pass model params between methods to compute various properties
   

var LogNorm model = LN.init(arr.avg(), arr.stdev()) // Assumes the library is imported as LN
var mode = model.mode()

Outputs from the model can be adjusted to better fit the data.

var Quantile data = arr.quantiles()
var more_accurate_mode = mode.fit(model, data) // Fits value from model to data

Inputs to the model can also be adjusted to better fit the data.

datum = 123.45
model_equivalent_datum = datum.fit(data, model) // Fits value from data to the model
area_from_zero_to_datum = model.cdf(model_equivalent_datum)

- - -

TYPES
There are two requisite UDTs: LogNorm and Quantile. They are used to pass parameters between functions and are set automatically (see Type Management).

LogNorm
  Object for log space parameters and linear space quantiles.
  Fields:
    mu (float): Log space mu ( µ ).
    sigma (float): Log space sigma ( σ ).
    variance (float): Log space variance ( σ² ).
    quantiles (Quantile): Linear space quantiles.

Quantile
  Object for linear quantiles, most similar to a seven-number summary.
  Fields:
    Q0 (float): Smallest Value
    LW (float): Lower Whisker Endpoint
    LC (float): Lower Whisker Crosshatch
    Q1 (float): First Quartile
    Q2 (float): Second Quartile
    Q3 (float): Third Quartile
    UC (float): Upper Whisker Crosshatch
    UW (float): Upper Whisker Endpoint
    Q4 (float): Largest Value
    IQR (float): Interquartile Range
    MH (float): Midhinge
    TM (float): Trimean
    MR (float): Mid-Range

- - -

TYPE MANAGEMENT
These functions reliably initialize and update the UDTs. Because parameterization is interdependent, avoid setting the LogNorm and Quantile fields directly.

init(mean, stdev, variance)
  Initializes a LogNorm object.
  Parameters:
    mean (float): Linearly measured mean.
    stdev (float): Linearly measured standard deviation.
    variance (float): Linearly measured variance.
  Returns: LogNorm Object

set(ln, mean, stdev, variance)
  Transforms linear measurements into log space parameters for a LogNorm object.
  Parameters:
    ln (LogNorm): Object containing log space parameters.
    mean (float): Linearly measured mean.
    stdev (float): Linearly measured standard deviation.
    variance (float): Linearly measured variance.
  Returns: LogNorm Object

quantiles(arr)
  Gets empirical quantiles from an array of floats.
  Parameters:
    arr (array<float>): Float array object.
  Returns: Quantile Object

- - -

DESCRIPTIVE STATISTICS
Using only the initialized LogNorm parameters, these functions compute a model's central tendency and standardized moments.

mean(ln)
  Computes the linear mean from log space parameters.
  Parameters:
    ln (LogNorm): Object containing log space parameters.
  Returns: Between 0 and ∞

median(ln)
  Computes the linear median from log space parameters.
  Parameters:
    ln (LogNorm): Object containing log space parameters.
  Returns: Between 0 and ∞

mode(ln)
  Computes the linear mode from log space parameters.
  Parameters:
    ln (LogNorm): Object containing log space parameters.
  Returns: Between 0 and ∞

variance(ln)
  Computes the linear variance from log space parameters.
  Parameters:
    ln (LogNorm): Object containing log space parameters.
  Returns: Between 0 and ∞

skewness(ln)
  Computes the linear skewness from log space parameters.
  Parameters:
    ln (LogNorm): Object containing log space parameters.
  Returns: Between 0 and ∞

kurtosis(ln, excess)
  Computes the linear kurtosis from log space parameters.
  Parameters:
    ln (LogNorm): Object containing log space parameters.
    excess (bool): Excess Kurtosis (true) or regular Kurtosis (false).
  Returns: Between 0 and ∞

hyper_skewness(ln)
  Computes the linear hyper skewness from log space parameters.
  Parameters:
    ln (LogNorm): Object containing log space parameters.
  Returns: Between 0 and ∞

hyper_kurtosis(ln, excess)
  Computes the linear hyper kurtosis from log space parameters.
  Parameters:
    ln (LogNorm): Object containing log space parameters.
    excess (bool): Excess Hyper Kurtosis (true) or regular Hyper Kurtosis (false).
  Returns: Between 0 and ∞

- - -

DISTRIBUTION FUNCTIONS
These wrap Gaussian functions to make working with model space more direct. Because they are contained within a log-normal library, they describe estimations relative to a log-normal curve, even though they fundamentally measure a Gaussian curve.

pdf(ln, x, empirical_quantiles)
  A Probability Density Function estimates the probability density. For clarity, density is not a probability.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    x (float): Linear X coordinate for which a density will be estimated.
    empirical_quantiles (Quantile): Quantiles as observed in the data (optional).
  Returns: Between 0 and ∞

cdf(ln, x, precise)
  A Cumulative Distribution Function estimates the area under a Log-Normal curve between Zero and a linear X coordinate.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    x (float): Linear X coordinate [0, ∞].
    precise (bool): Double precision (true) or single precision (false).
  Returns: Between 0 and 1

ccdf(ln, x, precise)
  A Complementary Cumulative Distribution Function estimates the area under a Log-Normal curve between a linear X coordinate and Infinity.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    x (float): Linear X coordinate [0, ∞].
    precise (bool): Double precision (true) or single precision (false).
  Returns: Between 0 and 1

cdfinv(ln, a, precise)
  An Inverse Cumulative Distribution Function reverses the Log-Normal cdf() by estimating the linear X coordinate from an area.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    a (float): Normalized area [0, 1].
    precise (bool): Double precision (true) or single precision (false).
  Returns: Between 0 and ∞

ccdfinv(ln, a, precise)
  An Inverse Complementary Cumulative Distribution Function reverses the Log-Normal ccdf() by estimating the linear X coordinate from an area.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    a (float): Normalized area [0, 1].
    precise (bool): Double precision (true) or single precision (false).
  Returns: Between 0 and ∞

cdfab(ln, x1, x2, precise)
  A Cumulative Distribution Function from A to B estimates the area under a Log-Normal curve between two linear X coordinates (A and B).
  Parameters:
    ln (LogNorm): Object of log space parameters.
    x1 (float): First linear X coordinate [0, ∞].
    x2 (float): Second linear X coordinate [0, ∞].
    precise (bool): Double precision (true) or single precision (false).
  Returns: Between 0 and 1

ott(ln, x, precise)
  A One-Tailed Test transforms a linear X coordinate into an absolute Z Score before estimating the area under a Log-Normal curve between Z and Infinity.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    x (float): Linear X coordinate [0, ∞].
    precise (bool): Double precision (true) or single precision (false).
  Returns: Between 0 and 0.5

ttt(ln, x, precise)
   A Two-Tailed Test transforms a linear X coordinate into symmetrical ± Z Scores before estimating the area under a Log-Normal curve from Zero to -Z, and +Z to Infinity.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    x (float): Linear X coordinate [0, ∞].
    precise (bool): Double precision (true) or single precision (false).
  Returns: Between 0 and 1

ottinv(ln, a, precise)
  An Inverse One-Tailed Test reverses the Log-Normal ott() by estimating a linear X coordinate for the right tail from an area.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    a (float): Half a normalized area [0, 0.5].
    precise (bool): Double precision (true) or single precision (false).
  Returns: Between 0 and ∞

tttinv(ln, a, precise)
  An Inverse Two-Tailed Test reverses the Log-Normal ttt() by estimating two linear X coordinates from an area.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    a (float): Normalized area [0, 1].
    precise (bool): Double precision (true) or single precision (false).
  Returns: Linear space tuple : [ lower_x, upper_x ]

- - -

UNCERTAINTY
Model-based measures of uncertainty, information, and risk.

sterr(sample_size, fisher_info)
  The standard error of a sample statistic.
  Parameters:
    sample_size (float): Number of observations.
    fisher_info (float): Fisher information.
  Returns: Between 0 and ∞

surprisal(p, base)
  Quantifies the information content of a single event.
  Parameters:
    p (float): Probability of the event [0, 1].
    base (float): Logarithmic base (optional).
  Returns: Between 0 and ∞

entropy(ln, base)
  Computes the differential entropy (average surprisal).
  Parameters:
    ln (LogNorm): Object of log space parameters.
    base (float): Logarithmic base (optional).
  Returns: Between 0 and ∞

perplexity(ln, base)
  Computes the average number of distinguishable outcomes from the entropy.  
  Parameters:
    ln (LogNorm)
    base (float): Logarithmic base used for Entropy (optional).
  Returns: Between 0 and ∞

value_at_risk(ln, p, precise)
  Estimates a risk threshold under normal market conditions for a given confidence level.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    p (float): Probability threshold, aka. the confidence level [0, 1].
    precise (bool): Double precision (true) or single precision (false).
  Returns: Between 0 and ∞

value_at_risk_inv(ln, value_at_risk, precise)
  Reverses the value_at_risk() by estimating the confidence level from the risk threshold.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    value_at_risk (float): Value at Risk.
    precise (bool): Double precision (true) or single precision (false).
  Returns: Between 0 and 1

conditional_value_at_risk(ln, p, precise)
  Estimates the average loss beyond a confidence level, aka. expected shortfall.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    p (float): Probability threshold, aka. the confidence level [0, 1].
    precise (bool): Double precision (true) or single precision (false).
  Returns: Between 0 and ∞

conditional_value_at_risk_inv(ln, conditional_value_at_risk, precise)
  Reverses the conditional_value_at_risk() by estimating the confidence level of an average loss.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    conditional_value_at_risk (float): Conditional Value at Risk.
    precise (bool): Double precision (true) or single precision (false).
  Returns: Between 0 and 1

partial_expectation(ln, x, precise)
  Estimates the partial expectation of a linear X coordinate.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    x (float): Linear X coordinate [0, ∞].
    precise (bool): Double precision (true) or single precision (false).
  Returns: Between 0 and µ

partial_expectation_inv(ln, partial_expectation, precise)
  Reverses the partial_expectation() by estimating a linear X coordinate.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    partial_expectation (float): Partial Expectation [0, µ].
    precise (bool): Double precision (true) or single precision (false).
  Returns: Between 0 and ∞

conditional_expectation(ln, x, precise)
  Estimates the conditional expectation of a linear X coordinate.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    x (float): Linear X coordinate [0, ∞].
    precise (bool): Double precision (true) or single precision (false).
  Returns: Between X and ∞

conditional_expectation_inv(ln, conditional_expectation, precise)
  Reverses the conditional_expectation by estimating a linear X coordinate.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    conditional_expectation (float): Conditional Expectation [0, ∞].
    precise (bool): Double precision (true) or single precision (false).
  Returns: Between 0 and ∞

fisher(ln, log)
  Computes the Fisher Information Matrix for the distribution, not a linear X coordinate.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    log (bool): Sets if the matrix should be in log (true) or linear (false) space.
  Returns: FIM for the distribution

fisher(ln, x, log)
  Computes the Fisher Information Matrix for a linear X coordinate, not the distribution itself.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    x (float): Linear X coordinate [0, ∞].
    log (bool): Sets if the matrix should be in log (true) or linear (false) space.
  Returns: FIM for the linear X coordinate

confidence_interval(ln, x, sample_size, confidence, precise)
  Estimates a confidence interval for a linear X coordinate.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    x (float): Linear X coordinate [0, ∞].
    sample_size (float): Number of observations.
    confidence (float): Confidence level [0,1].
    precise (bool): Double precision (true) or single precision (false).
  Returns: CI for the linear X coordinate

- - -

CURVE FITTING
An overloaded function that helps transform values between spaces. The primary function uses quantiles, and the overloads wrap the primary function to make working with LogNorm more direct.

fit(x, a, b)
  Transforms X coordinate between spaces A and B.
  Parameters:
    x (float): Linear X coordinate from space A [0, ∞].
    a (LogNorm | Quantile | array<float>): LogNorm, Quantile, or float array.
    b (LogNorm | Quantile | array<float>): LogNorm, Quantile, or float array.
  Returns: Adjusted X coordinate

- - -

EXPORTED HELPERS
Small utilities to simplify extensibility.

z_score(ln, x)
  Converts a linear X coordinate into a Z Score.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    x (float): Linear X coordinate.
  Returns: Between -∞ and +∞

x_coord(ln, z)
  Converts a Z Score into a linear X coordinate.
  Parameters:
    ln (LogNorm): Object of log space parameters.
    z (float): Standard normal Z Score.
  Returns: Between 0 and ∞

iget(arr, index)
  Gets an interpolated value of a pseudo-element (fictional element between real array elements). Useful for quantile mapping.
  Parameters:
    arr (array<float>): Float array object.
    index (float): Index of the pseudo element.
  Returns: Interpolated value of the arrays pseudo element.

il y a 9 heures

Notes de version

v2
Removed thumbnail code form library.