Class CurrencyParameterSensitivities

  • All Implemented Interfaces:
    FxConvertible<CurrencyParameterSensitivities>, Serializable, org.joda.beans.Bean, org.joda.beans.ImmutableBean

    public final class CurrencyParameterSensitivities
    extends Object
    implements FxConvertible<CurrencyParameterSensitivities>, org.joda.beans.ImmutableBean, Serializable
    Currency-based parameter sensitivity for parameterized market data, such as curves.

    Parameter sensitivity is the sensitivity of a value to the parameters of parameterized market data objects that are used to determine the value. Common ParameterizedData implementations include Curve and Surface.

    For example, the parameter sensitivity for present value on a FRA might contain two entries, one for the Ibor forward curve and one for the discount curve. Each entry identifies the curve that was queried and the resulting sensitivity values, one for each node on the curve.

    The sensitivity is expressed as a single entry for piece of parameterized market data. The sensitivity represents a monetary value in the specified currency. The order of the list has no specific meaning.

    One way of viewing this class is as a Map from a specific sensitivity key to DoubleArray sensitivity values. However, instead of being structured as a Map, the data is structured as a List, with the key and value in each entry. As such, the sensitivities are always in a "normalized" form.

    See Also:
    Serialized Form
    • Method Detail

      • builder

        public static CurrencyParameterSensitivitiesBuilder builder()
        Returns a builder that can be used to create an instance of CurrencyParameterSensitivities.

        The builder takes into account the parameter metadata when creating the sensitivity map. As such, the parameter metadata added to the builder must not be empty.

        Returns:
        the builder
      • size

        public int size()
        Gets the number of sensitivity entries.
        Returns:
        the size of the internal list of point sensitivities
      • findSensitivity

        public Optional<CurrencyParameterSensitivity> findSensitivity​(MarketDataName<?> name,
                                                                      Currency currency)
        Finds a single sensitivity instance by name and currency.

        If the sensitivity is not found, optional empty is returned.

        Parameters:
        name - the curve name to find
        currency - the currency to find
        Returns:
        the matching sensitivity
      • combinedWith

        public CurrencyParameterSensitivities combinedWith​(CurrencyParameterSensitivity other)
        Combines this parameter sensitivities with another instance.

        This returns a new sensitivity instance with the specified sensitivity added. This instance is immutable and unaffected by this method.

        The sensitivities are merged using market data name and currency as a key. The parameter metadata is not checked, thus the caller must ensure the sensitivities are compatible with the same metadata and parameter count. To combine taking the metadata into account, use mergedWith(CurrencyParameterSensitivities).

        Parameters:
        other - the other parameter sensitivity
        Returns:
        an instance based on this one, with the other instance added
      • combinedWith

        public CurrencyParameterSensitivities combinedWith​(CurrencyParameterSensitivities other)
        Combines this parameter sensitivities with another instance.

        This returns a new sensitivity instance with a combined list of parameter sensitivities. This instance is immutable and unaffected by this method.

        The sensitivities are merged using market data name and currency as a key. The parameter metadata is not checked, thus the caller must ensure the sensitivities are compatible with the same metadata and parameter count. To combine taking the metadata into account, use mergedWith(CurrencyParameterSensitivities).

        Parameters:
        other - the other parameter sensitivities
        Returns:
        an instance based on this one, with the other instance added
      • mergedWith

        public CurrencyParameterSensitivities mergedWith​(CurrencyParameterSensitivities other)
        Merges this parameter sensitivities with another instance taking the metadata into account.

        This returns a new sensitivity instance with a combined set of parameter sensitivities. This instance is immutable and unaffected by this method.

        The sensitivities are merged using market data name and currency as a key. Each sensitivity is then merged taking into account the metadata, such as the tenor. As such, this method can only be used if the parameter metadata instances are not be empty.

        Parameters:
        other - the other parameter sensitivities
        Returns:
        an instance based on this one, with the other instance added
        Throws:
        IllegalArgumentException - if any metadata instance is empty
      • withMarketDataNames

        public CurrencyParameterSensitivities withMarketDataNames​(Function<MarketDataName<?>,​MarketDataName<?>> nameFn)
        Checks and adjusts the market data names.

        The supplied function is invoked for each market data name in this sensitivities. If the function returns the same name for two different inputs, the sensitivity values will be summed. A typical use case would be to convert index names to curve names valid for an underlying system.

        Parameters:
        nameFn - the function for checking and adjusting the name
        Returns:
        the adjusted sensitivity
        Throws:
        RuntimeException - if the function throws an exception
      • withParameterMetadatas

        public CurrencyParameterSensitivities withParameterMetadatas​(UnaryOperator<ParameterMetadata> mdFn)
        Checks and adjusts the parameter metadata.

        The supplied function is invoked for each parameter metadata in this sensitivities. If the function returns the same metadata for two different inputs, the sensitivity values will be summed. A typical use case would be to normalize parameter metadata tenors to be valid for an underlying system.

        Parameters:
        mdFn - the function for checking and adjusting the metadata
        Returns:
        the adjusted sensitivity
        Throws:
        IllegalArgumentException - if any metadata instance is empty
        RuntimeException - if the function throws an exception
      • split

        public CurrencyParameterSensitivities split()
        Splits this sensitivity instance.

        This examines each individual sensitivity to see if it can be split. If any can be split, the result will contain the combination of the split sensitivities.

        Returns:
        this sensitivity, with any combined sensitivities split
      • total

        public CurrencyAmount total​(Currency resultCurrency,
                                    FxRateProvider rateProvider)
        Returns the total of the sensitivity values.

        The result is the total of all values, as converted to the specified currency. Any FX conversion that is required will use rates from the provider.

        Parameters:
        resultCurrency - the currency of the result
        rateProvider - the provider of FX rates
        Returns:
        the total sensitivity
        Throws:
        RuntimeException - if no FX rate could be found
      • total

        public MultiCurrencyAmount total()
        Returns the total of the sensitivity values.

        The result is the total of all values, in whatever currency they are defined.

        Returns:
        the total sensitivity
      • multipliedBy

        public CurrencyParameterSensitivities multipliedBy​(double factor)
        Returns an instance with the sensitivity values multiplied by the specified factor.

        The result will consist of the same entries, but with each sensitivity value multiplied. This instance is immutable and unaffected by this method.

        Parameters:
        factor - the multiplicative factor
        Returns:
        an instance based on this one, with each sensitivity multiplied by the factor
      • mapSensitivities

        public CurrencyParameterSensitivities mapSensitivities​(DoubleUnaryOperator operator)
        Returns an instance with the specified operation applied to the sensitivity values.

        The result will consist of the same entries, but with the operator applied to each sensitivity value. This instance is immutable and unaffected by this method.

        This is used to apply a mathematical operation to the sensitivity values. For example, the operator could multiply the sensitivities by a constant, or take the inverse.

           inverse = base.mapSensitivities(value -> 1 / value);
         
        Parameters:
        operator - the operator to be applied to the sensitivities
        Returns:
        an instance based on this one, with the operator applied to the sensitivity values
      • equalWithTolerance

        public boolean equalWithTolerance​(CurrencyParameterSensitivities other,
                                          double tolerance)
        Checks if this sensitivity equals another within the specified tolerance.

        This returns true if the two instances have the same keys, with arrays of the same length, where the double values are equal within the specified tolerance.

        Parameters:
        other - the other sensitivity
        tolerance - the tolerance
        Returns:
        true if equal up to the tolerance
      • toBuilder

        public CurrencyParameterSensitivitiesBuilder toBuilder()
        Returns a builder populated with the set of sensitivities from this instance.

        The builder takes into account the parameter metadata when creating the sensitivity map. As such, the parameter metadata added to the builder must not be empty.

        Returns:
        the builder
        Throws:
        IllegalArgumentException - if any metadata instance is empty
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object