<a id="skfolio-descriptor-shareholderyield"></a>

# skfolio.descriptor.ShareholderYield

<a id="skfolio.descriptor.ShareholderYield"></a>

### *class* skfolio.descriptor.ShareholderYield

Shareholder yield descriptor.

Computes net cash returned to common shareholders through dividends and share
repurchases as a fraction of market capitalization:

$$
\text{shareholder\_yield}(t) =
\frac{\text{dividends\_ttm}(t) + \text{net\_buybacks\_ttm}(t)}
     {\text{market\_cap}(t)}
$$

Dividend yield alone misses a large share of corporate payout. Since the 1990s,
share repurchases have overtaken dividends as the dominant mechanism for returning
cash to shareholders. Shareholder yield captures the total payout: a company
paying 0% dividends but buying back 5% of its equity annually has a positive payout
yield that pure dividend yield scores as zero [[1]](#r6ab09b0564bd-1).

High shareholder yield identifies firms that return substantial capital.
Empirically, shareholder yield subsumes much of the stand-alone dividend yield
premium and provides a stronger value/payout signal [[2]](#r6ab09b0564bd-2).

* **Parameters:**
  **None**
* **Attributes:**
  **n_assets_** *int*
  : Number of assets seen during fitting.

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

### Methods

| [`fit_transform`](#skfolio.descriptor.ShareholderYield.fit_transform)(X[, y])         | Compute shareholder yield ratios.              |
|--------------------------------------------------------------------------------|------------------------------------------------|
| [`get_metadata_routing`](#skfolio.descriptor.ShareholderYield.get_metadata_routing)()        | Get metadata routing of this object.           |
| [`get_params`](#skfolio.descriptor.ShareholderYield.get_params)([deep])            | Get parameters for this estimator.             |
| [`partial_fit_transform`](#skfolio.descriptor.ShareholderYield.partial_fit_transform)(X[, y]) | Stateless class delegation to `fit_transform`. |
| [`set_params`](#skfolio.descriptor.ShareholderYield.set_params)(\*\*params)        | Set the parameters of this estimator.          |

#### SEE ALSO
[`DividendToPrice`](https://skfolio.org/generated/skfolio.descriptor.DividendToPrice.html.md#skfolio.descriptor.DividendToPrice)
: Dividend-only yield (trailing).

### Notes

`dividends_ttm` should contain positive cash dividends paid on common shares only,
excluding preferred dividends.

`net_buybacks_ttm` should equal net share repurchases, defined as repurchases minus
issuances, over the trailing twelve months. Positive values increase shareholder
yield and negative values represent net issuance. Some data vendors provide net
equity issuance from the cash flow statement instead, with the opposite sign
convention. In that case, `net_buybacks_ttm = -net_equity_issuance_ttm`.

This descriptor uses aggregate quantities divided by `market_cap`, consistent with
`DividendToPrice` and other value descriptors.

### References

* <a id='r6ab09b0564bd-1'>**[1]**</a> “On the importance of measuring payout yield: implications for empirical asset pricing” The Journal of Finance. Boudoukh, Michaely, Richardson & Roberts (2007).
* <a id='r6ab09b0564bd-2'>**[2]**</a> “Dividends, share repurchases, and the substitution hypothesis” The Journal of Finance. Grullon & Michaely (2002).

### Examples

```pycon
>>> from skfolio.datasets import make_synthetic_characteristics
>>> from skfolio.descriptor import ShareholderYield
>>>
>>> X = make_synthetic_characteristics()
>>>
>>> descriptor = ShareholderYield()
>>> shareholder_yield = descriptor.fit_transform(X)
```

<a id="skfolio.descriptor.ShareholderYield.fit_transform"></a>

#### fit_transform(X, y=None, \*\*fit_params)

Compute shareholder yield ratios.

* **Parameters:**
  **X** *AssetPanel*
  : Input panel containing `dividends_ttm`, `net_buybacks_ttm` and
    `market_cap`.

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

  **\*\*fit_params** *dict*
  : Additional fit parameters. Ignored.
* **Returns:**
  **shareholder_yield** *ndarray of shape (n_observations, n_assets)*
  : Shareholder yield ratio for each observation and asset.

<a id="skfolio.descriptor.ShareholderYield.get_metadata_routing"></a>

#### get_metadata_routing()

Get metadata routing of this object.

Please check [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

* **Returns:**
  **routing** *MetadataRequest*
  : A `MetadataRequest` encapsulating
    routing information.

<a id="skfolio.descriptor.ShareholderYield.get_params"></a>

#### get_params(deep=True)

Get parameters for this estimator.

* **Parameters:**
  **deep** *bool, default=True*
  : If True, will return the parameters for this estimator and
    contained subobjects that are estimators.
* **Returns:**
  **params** *dict*
  : Parameter names mapped to their values.

<a id="skfolio.descriptor.ShareholderYield.partial_fit_transform"></a>

#### partial_fit_transform(X, y=None, \*\*fit_params)

Stateless class delegation to `fit_transform`.

<a id="skfolio.descriptor.ShareholderYield.set_params"></a>

#### set_params(\*\*params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects
(such as `Pipeline`). The latter have
parameters of the form `<component>__<parameter>` so that it’s
possible to update each component of a nested object.

* **Parameters:**
  **\*\*params** *dict*
  : Estimator parameters.
* **Returns:**
  **self** *estimator instance*
  : Estimator instance.