valueAtRisk

Compute value-at-risk values for returns distribution

Since R2025a

collapse all in page

    Syntax

    VaR = valueAtRisk("normal",VaRLevels)
    VaR = valueAtRisk("normal",VaRLevels,Name=Value)
    VaR = valueAtRisk("t",VaRLevels,DegreesOfFreedom=dof)
    VaR = valueAtRisk("t",VaRLevels,DegreesOfFreedom=dof,Name=Value)
    VaR = valueAtRisk("empirical",VaRLevels,InputData=data)
    VaR = valueAtRisk(pdobj,VaRLevels)

    Description

    VaR = valueAtRisk("normal",VaRLevels) computes the value-at-risk (VaR) values for a standard normal distribution. The VaR levels represent the potential loss percentage within a portfolio.

    example

    VaR = valueAtRisk("normal",VaRLevels,Name=Value) specifies optional name-value arguments for a normal distribution. For example, valueAtRisk("normal",VaRLevels,Mean=10) specifies the mean value of the distribution and computes the VaR values.

    VaR = valueAtRisk("t",VaRLevels,DegreesOfFreedom=dof) computes the VaR values for a standard t location-scale distribution with the specified degrees of freedom. The standard t location-scale distribution is centered at 0 along the x-axis and has a scale value of 1.

    VaR = valueAtRisk("t",VaRLevels,DegreesOfFreedom=dof,Name=Value) specifies optional name-value arguments for the t location-scale distribution. You can use the Location name-value argument to shift the center of the distribution along the x-axis. Use the Scale name-value argument to control the spread of the distribution. For example, valueAtRisk("t",VaRLevels,DegreesOfFreedom=3,Location=5,Scale=2) computes the VaR values using a t distribution centered at 5 with a scale of 2.

    example

    VaR = valueAtRisk("empirical",VaRLevels,InputData=data) computes the VaR values for an empirical distribution for the matrix data, where the rows correspond to the distributions and the columns represent the observations.

    VaR = valueAtRisk(pdobj,VaRLevels) computes the VaR values for the probability distribution object, pdobj, which you can create for any of the following supported distributions:

    • Normal distribution

    • t location-scale distribution

    • Piecewise linear distribution

    • Kernel distribution

    • Empirical distribution

    Use the makedist function to create probability distribution objects for normal, t location-scale, and piecewise linear distributions. Create objects for kernel and empirical distributions by using the fitdist function.

    example

    Examples

    collapse all

    Open Live Script

    Compute the VaR values for a standard normal distribution for the specified VaR levels.

    VaRLevels = [0.95,0.975,0.99];
VaR = valueAtRisk("normal",VaRLevels)
    VaR = 1×3

    1.6449    1.9600    2.3263
    Open Live Script

    Compute the VaR values for a t location-scale distribution by using a probability distribution object. Use the makedist and specify "tLocationScale" for the distribution name to create the probability distribution object. Specify the following distribution parameters:

    • mu represents the location.

    • sigma represents the scale.

    • nu represents the degrees of freedom.

    distname = "tLocationScale";
pdobj = makedist(distname,mu=0,sigma=1,nu=5);

    Specify the VaR levels and return the VaR values.

    VaRLevels = [0.95,0.99];
VaR = valueAtRisk(pdobj,VaRLevels)
    VaR = 1×2

    2.0150    3.3649
    Open Live Script

    Compute the VaR values for a t location-scale distribution with specified location and scale parameters.

    Set the following distribution parameters:

    • nu represents the degrees of freedom.

    • mu represents the location.

    • sigma represents the scale.

    nu = 5;
mu = 0;
sigma = 1;

    Choose your VaR levels and return the VaR values.

    VaRLevels = [0.95,0.975,0.99];
VaR = valueAtRisk("t",VaRLevels,DegreesOfFreedom=nu,Location=mu,Scale=sigma)
    VaR = 1×3

    2.0150    2.5706    3.3649

    Input Arguments

    collapse all

    VaR levels, specified as a numeric vector with values between 0 and 1. These values represent the potential loss percentage within a portfolio.

    Degrees of freedom for the t location-scale distribution, specified as a numeric scalar greater than or equal to 3.

    Empirical distribution data, specified as a numeric matrix. The number of rows corresponds to the number of distributions, whereas the number of columns corresponds to the number of observations in your data.

    Probability distribution, specified as a probability distribution object. Use the makedist function to create objects for normal, t location-scale, and piecewise linear distributions. Create objects for kernel and empirical distributions by using the fitdist function. For example, fitdist(randn(1000,1),"Empirical") creates an empirical distribution object by fitting the empirical distribution to a sample of 1000 values drawn from a normal distribution.

    Example: pdobj = makedist("normal"); VaR = valueAtRisk(pdobj,VaRLevels)

    Name-Value Arguments

    expand all

    Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

    Example: VaR = valueAtRisk("normal",VaRLevels,Mean=Mu,StandardDeviation=Sigma)

    Normal Distribution

    expand all

    Mean value of a normal distribution, specified as a numeric vector.

    Example: valueAtRisk("normal",VaRLevels,Mean=[5,10])

    Standard deviation of a normal distribution, specified as a numeric vector.

    Example: valueAtRisk("normal",VaRLevels,StandardDeviation=[0.01,0.02])

    t Location-Scale Distribution

    expand all

    Distribution location, specified as a numeric vector. Use the Location name-value argument to shift the center of the distribution along the x-axis without changing the shape of the distribution.

    Example: valueAtRisk("t",VaRLevels,DegreesOfFreedom=4,Location=[5,10])

    Distribution scale, specified as a numeric vector. Use the Scale name-value argument to control the spread of the distribution. For example, set the scale to a higher value when you want to stretch the distribution or a lower value to compress the distribution.

    Example: valueAtRisk("t",VaRLevels,DegreesOfFreedom=4,Scale=[1,2])

    Version History

    Introduced in R2025a

    expand all

    See Also

    |