finance_risk.covariance
=======================

.. py:module:: finance_risk.covariance


Classes
-------

.. autoapisummary::

   finance_risk.covariance.CovarianceEstimate


Functions
---------

.. autoapisummary::

   finance_risk.covariance.sample_covariance
   finance_risk.covariance.ledoit_wolf_covariance
   finance_risk.covariance.oas_covariance
   finance_risk.covariance.covariance_to_correlation
   finance_risk.covariance.correlation_to_covariance
   finance_risk.covariance.nearest_positive_semidefinite


Module Contents
---------------

.. py:class:: CovarianceEstimate(/, **data: Any)

   Bases: :py:obj:`pydantic.BaseModel`


   !!! abstract "Usage Documentation"
       [Models](../concepts/models.md)

   A base class for creating Pydantic models.

   .. attribute:: __class_vars__

      The names of the class variables defined on the model.

   .. attribute:: __private_attributes__

      Metadata about the private attributes of the model.

   .. attribute:: __signature__

      The synthesized `__init__` [`Signature`][inspect.Signature] of the model.

   .. attribute:: __pydantic_complete__

      Whether model building is completed, or if there are still undefined fields.

   .. attribute:: __pydantic_core_schema__

      The core schema of the model.

   .. attribute:: __pydantic_custom_init__

      Whether the model has a custom `__init__` function.

   .. attribute:: __pydantic_decorators__

      Metadata containing the decorators defined on the model.
      This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1.

   .. attribute:: __pydantic_generic_metadata__

      A dictionary containing metadata about generic Pydantic models.
      The `origin` and `args` items map to the [`__origin__`][genericalias.__origin__]
      and [`__args__`][genericalias.__args__] attributes of [generic aliases][types-genericalias],
      and the `parameter` item maps to the `__parameter__` attribute of generic classes.

   .. attribute:: __pydantic_parent_namespace__

      Parent namespace of the model, used for automatic rebuilding of models.

   .. attribute:: __pydantic_post_init__

      The name of the post-init method for the model, if defined.

   .. attribute:: __pydantic_root_model__

      Whether the model is a [`RootModel`][pydantic.root_model.RootModel].

   .. attribute:: __pydantic_serializer__

      The `pydantic-core` `SchemaSerializer` used to dump instances of the model.

   .. attribute:: __pydantic_validator__

      The `pydantic-core` `SchemaValidator` used to validate instances of the model.

   .. attribute:: __pydantic_fields__

      A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects.

   .. attribute:: __pydantic_computed_fields__

      A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects.

   .. attribute:: __pydantic_extra__

      A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra]
      is set to `'allow'`.

   .. attribute:: __pydantic_fields_set__

      The names of fields explicitly set during instantiation.

   .. attribute:: __pydantic_private__

      Values of private attributes set on the model instance.

   Create a new model by parsing and validating input data from keyword arguments.

   Raises [`ValidationError`][pydantic_core.ValidationError] if the input data cannot be
   validated to form a valid model.

   `self` is explicitly positional-only to allow `self` as a field name.


   .. py:attribute:: model_config

      Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].


   .. py:attribute:: matrix
      :type:  numpy.ndarray


   .. py:attribute:: assets
      :type:  tuple[str, ...]


   .. py:attribute:: method
      :type:  str


   .. py:attribute:: frequency
      :type:  int
      :value: 252



   .. py:attribute:: shrinkage
      :type:  float | None
      :value: None



.. py:function:: sample_covariance(data: Any, *, assets: collections.abc.Sequence[str] | None = None, frequency: int = 252) -> CovarianceEstimate

   Sample covariance of asset returns, annualized by ``frequency``.


.. py:function:: ledoit_wolf_covariance(data: Any, *, assets: collections.abc.Sequence[str] | None = None, frequency: int = 252) -> CovarianceEstimate

   Ledoit-Wolf constant-variance shrinkage covariance estimate.


.. py:function:: oas_covariance(data: Any, *, assets: collections.abc.Sequence[str] | None = None, frequency: int = 252) -> CovarianceEstimate

   Oracle Approximating Shrinkage covariance estimate.


.. py:function:: covariance_to_correlation(covariance: Any) -> numpy.ndarray

.. py:function:: correlation_to_covariance(correlation: Any, volatility: Any) -> numpy.ndarray

.. py:function:: nearest_positive_semidefinite(matrix: Any, *, epsilon: float = 0.0) -> numpy.ndarray

   Project a symmetric matrix onto the positive-semidefinite cone.