Source code for skfolio.descriptor._value._cash_flow_to_price

"""Cash-flow-to-price ratio descriptor."""

# Copyright (c) 2023-2026
# Author: Hugo Delatte <hugo.delatte@skfoliolabs.com>
# SPDX-License-Identifier: BSD-3-Clause

from __future__ import annotations

import numpy as np

from skfolio.containers import AssetPanel
from skfolio.descriptor._base import BaseDescriptor
from skfolio.typing import FloatArray
from skfolio.utils.stats import safe_divide
from skfolio.utils.validation import validate_asset_panel




class CashFlowToPrice(BaseDescriptor, stateless=True):
    r"""Cash-flow-to-price ratio descriptor.

    Computes the ratio of trailing twelve-month operating cash flow to market
    capitalization:

    .. math::

        \text{cash\_flow\_to\_price}(t) =
        \frac{\text{operating\_cash\_flow\_ttm}(t)}{\text{market\_cap}(t)}

    Operating cash flow measures cash generated by a firm's core business after
    working-capital adjustments. A high ratio identifies firms generating substantial
    cash relative to their market capitalization, providing a value signal that is less
    directly affected by accrual accounting choices than earnings-based measures [1]_.

    Parameters
    ----------
    None

    Attributes
    ----------
    n_assets_ : int
        Number of assets seen during fitting.

    asset_names_ : ndarray of shape (n_assets,)
        Asset names seen during fitting.

    Notes
    -----
    Non-missing `market_cap` values must be finite and strictly positive. Operating
    cash flow can be negative, so this descriptor can take negative values.

    This descriptor uses aggregate quantities (total operating cash flow divided by
    total market capitalization) rather than per-share quantities (cash flow per share
    divided by price). The two are mathematically equivalent:

    .. math::

        \frac{\text{operating\_cash\_flow\_ttm}}{\text{market\_cap}}
        = \frac{\text{cash\_flow\_per\_share}}{\text{price}}

    The aggregate form is preferred because it avoids subtle split-adjustment mismatches
    between numerator and denominator. Aggregate fundamentals are the primary form from
    data providers; per-share quantities are derived from them.

    See Also
    --------
    CashFlowToAssets : Operating cash flow normalized by total assets.
    BookToPrice : Common equity normalized by market capitalization.

    References
    ----------
    .. [1] "Contrarian investment, extrapolation, and risk"
        The Journal of Finance. Lakonishok, J., Shleifer, A., & Vishny, R. W. (1994).

    Examples
    --------
    >>> from skfolio.datasets import make_synthetic_characteristics
    >>> from skfolio.descriptor import CashFlowToPrice
    >>>
    >>> X = make_synthetic_characteristics()
    >>>
    >>> descriptor = CashFlowToPrice()
    >>> cash_flow_to_price = descriptor.fit_transform(X)
    """



    def fit_transform(self, X: AssetPanel, y=None, **fit_params) -> FloatArray:
        """Compute cash flow to price.

        Parameters
        ----------
        X : AssetPanel
            Input panel containing `operating_cash_flow_ttm` and `market_cap`.

        y : None
            Ignored. Present for compatibility with scikit-learn's API.

        **fit_params : dict
            Additional fit parameters. Ignored.

        Returns
        -------
        cash_flow_to_price : ndarray of shape (n_observations, n_assets)
            Cash-flow-to-price ratio for each observation and asset.
        """
        validate_asset_panel(
            self,
            X,
            required_fields=["operating_cash_flow_ttm", "market_cap"],
            finite_or_nan=["operating_cash_flow_ttm"],
            strictly_positive_or_nan=["market_cap"],
        )
        return safe_divide(
            X["operating_cash_flow_ttm"], X["market_cap"], fill_value=np.nan
        )