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

    Use the makedist function to create a probability distribution object for the normal, t location-scale, or piecewise linear distributions. Create a probability distribution object for the kernel distribution 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 probability distribution object. Use the makedist function to create a probability distribution object for the normal, t location-scale, and piecewise linear distributions. Create a probability distribution object for the kernel distribution by using the fitdist function.

    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

    See Also

    |