<a id="skfolio-population-population"></a>

# skfolio.population.Population

<a id="skfolio.population.Population"></a>

### *class* skfolio.population.Population(iterable)

Population Class.

A `Population` is a list of [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) or
[`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio) or both.

* **Parameters:**
  **iterable** *list[BasePortfolio]*
  : The list of portfolios. Each item can be of type
    [`Portfolio`](https://skfolio.org/generated/skfolio.portfolio.Portfolio.html.md#skfolio.portfolio.Portfolio) and/or
    [`MultiPeriodPortfolio`](https://skfolio.org/generated/skfolio.portfolio.MultiPeriodPortfolio.html.md#skfolio.portfolio.MultiPeriodPortfolio).
    Empty list are accepted.

### Methods

| [`append`](#skfolio.population.Population.append)(item)                                     | Append portfolio to the end of the population list.                                                              |
|---------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| [`boxplot_measure`](#skfolio.population.Population.boxplot_measure)(measure[, tag_list, points])     | Plot a box plot of a measure's distribution, optionally split by tags.                                           |
| [`clear`](#skfolio.population.Population.clear)(/)                                         | Remove all items from list.                                                                                      |
| [`composition`](#skfolio.population.Population.composition)([display_sub_ptf_name])              | Composition of each portfolio in the population.                                                                 |
| [`contribution`](#skfolio.population.Population.contribution)(measure[, spacing, ...])            | Contribution of each asset to a given measure of each portfolio in the population.                               |
| [`copy`](#skfolio.population.Population.copy)(/)                                          | Return a shallow copy of the list.                                                                               |
| [`count`](#skfolio.population.Population.count)(value, /)                                  | Return number of occurrences of value.                                                                           |
| [`cumulative_returns_df`](#skfolio.population.Population.cumulative_returns_df)([use_tag_in_column_name])  | DataFrame of cumulative returns for each portfolio in the population.                                            |
| [`drawdowns_df`](#skfolio.population.Population.drawdowns_df)([use_tag_in_column_name])           | DataFrame of drawdowns for each portfolio in the population.                                                     |
| [`extend`](#skfolio.population.Population.extend)(other)                                    | Extend population list by appending elements from the iterable.                                                  |
| [`filter`](#skfolio.population.Population.filter)([names, tags])                            | Filter the Population of portfolios by names and tags.                                                           |
| [`index`](#skfolio.population.Population.index)(value[, start, stop])                      | Return first index of value.                                                                                     |
| [`insert`](#skfolio.population.Population.insert)(index, item)                              | Insert portfolio before index.                                                                                   |
| [`max_measure`](#skfolio.population.Population.max_measure)(measure)                             | Return the portfolio with the maximum measure.                                                                   |
| [`measures`](#skfolio.population.Population.measures)(measure)                                | Vector of portfolios measures for each portfolio from the population.                                            |
| [`measures_mean`](#skfolio.population.Population.measures_mean)(measure)                           | Mean of portfolios measures for each portfolio from the population.                                              |
| [`measures_std`](#skfolio.population.Population.measures_std)(measure)                            | Standard-deviation of portfolios measures for each portfolio from the population.                                |
| [`min_measure`](#skfolio.population.Population.min_measure)(measure)                             | Return the portfolio with the minimum measure.                                                                   |
| [`non_denominated_sort`](#skfolio.population.Population.non_denominated_sort)([first_front_only])         | Alias of [`non_dominated_sort`](#skfolio.population.Population.non_dominated_sort).                                    |
| [`non_dominated_sort`](#skfolio.population.Population.non_dominated_sort)([first_front_only])           | Fast non-dominated sorting.                                                                                      |
| [`plot_composition`](#skfolio.population.Population.plot_composition)([display_sub_ptf_name])         | Plot the compositions of the portfolios in the population.                                                       |
| [`plot_contribution`](#skfolio.population.Population.plot_contribution)(measure[, spacing, ...])       | Plot the contribution of each asset to a given measure of the portfolios in the population.                      |
| [`plot_cumulative_returns`](#skfolio.population.Population.plot_cumulative_returns)([log_scale, idx, ...])   | Plot the cumulative returns of the population's portfolios.                                                      |
| [`plot_distribution`](#skfolio.population.Population.plot_distribution)(measure_list[, tag_list, ...]) | Plot the population's distribution for each measure provided in the measure list.                                |
| [`plot_drawdowns`](#skfolio.population.Population.plot_drawdowns)([idx, use_tag_in_legend])         | Plot the drawdowns of the population's portfolios.                                                               |
| [`plot_measures`](#skfolio.population.Population.plot_measures)(x, y[, z, to_surface, ...])        | Plot the 2D (or 3D) scatter points (or surface) of a given set of measures for each portfolio in the population. |
| [`plot_returns_distribution`](#skfolio.population.Population.plot_returns_distribution)([percentile_cutoff])   | Plot the Portfolios returns distribution using Gaussian KDE.                                                     |
| [`plot_rolling_measure`](#skfolio.population.Population.plot_rolling_measure)([measure, window])          | Plot the measure over a rolling window for each portfolio in the population.                                     |
| [`pop`](#skfolio.population.Population.pop)([index])                                     | Remove and return item at index (default last).                                                                  |
| [`quantile`](#skfolio.population.Population.quantile)(measure, q)                             | Return the portfolio corresponding to the `q` quantile for a given portfolio measure.                            |
| [`remove`](#skfolio.population.Population.remove)(value, /)                                 | Remove first occurrence of value.                                                                                |
| [`returns_df`](#skfolio.population.Population.returns_df)([use_tag_in_column_name])             | DataFrame of returns for each portfolio in the population.                                                       |
| [`reverse`](#skfolio.population.Population.reverse)(/)                                       | Reverse *IN PLACE*.                                                                                              |
| [`rolling_measure`](#skfolio.population.Population.rolling_measure)([measure, window])               | Compute the measure over a rolling window for each portfolio in the                                              |
| [`set_portfolio_params`](#skfolio.population.Population.set_portfolio_params)(\*\*params)                 | Set the parameters of all the portfolios.                                                                        |
| [`sort`](#skfolio.population.Population.sort)(\*[, key, reverse])                         | Sort the list in ascending order and return None.                                                                |
| [`sort_measure`](#skfolio.population.Population.sort_measure)(measure[, reverse])                 | Sort the population by a given portfolio measure.                                                                |
| [`summary`](#skfolio.population.Population.summary)([formatted])                             | Summary of the portfolios in the population.                                                                     |

<a id="skfolio.population.Population.append"></a>

#### append(item)

Append portfolio to the end of the population list.

<a id="skfolio.population.Population.boxplot_measure"></a>

#### boxplot_measure(measure, tag_list=None, points='all')

Plot a box plot of a measure’s distribution, optionally split by tags.

If no tags are provided, the function draws a single box showing the
population distribution of `measure`. If `tag_list` is provided, it draws
one box per tag using values from the portfolio filtered by each tag.

* **Parameters:**
  **measure** *Measure*
  : The measure to plot.

  **tag_list** *list[str], optional*
  : For each tag in this list, filter the portfolio by that tag and plot a
    separate box. If None or empty, plot a single overall distribution.

  **points** *{‘all’, ‘outliers’, ‘suspectedoutliers’, False}, default ‘all’*
  : Passed to `plotly.express.box(..., points=...)` to control which points
    are shown.
* **Returns:**
  go.Figure
  : The Plotly figure.

### Examples

```pycon
>>> import numpy as np
>>> from skfolio import Population, Portfolio, RatioMeasure, RiskMeasure
>>> rng = np.random.default_rng(0)
>>> # Daily returns for two assets.
>>> X = rng.normal(0.0005, [0.02, 0.01], size=(252, 2))
>>> population = Population(
...     [
...         Portfolio(X, weights=[0.6, 0.4], tag="Asset 1 tilt"),
...         Portfolio(X, weights=[0.7, 0.3], tag="Asset 1 tilt"),
...         Portfolio(X, weights=[0.8, 0.2], tag="Asset 1 tilt"),
...         Portfolio(X, weights=[0.4, 0.6], tag="Asset 2 tilt"),
...         Portfolio(X, weights=[0.3, 0.7], tag="Asset 2 tilt"),
...         Portfolio(X, weights=[0.2, 0.8], tag="Asset 2 tilt"),
...     ]
... )
```

Plot all portfolios in one box:

```pycon
>>> fig = population.boxplot_measure(measure=RiskMeasure.STANDARD_DEVIATION)
```

Plot one box per tag:

```pycon
>>> fig = population.boxplot_measure(
...     measure=RatioMeasure.SHARPE_RATIO,
...     tag_list=["Asset 1 tilt", "Asset 2 tilt"],
... )
```

<a id="skfolio.population.Population.clear"></a>

#### clear(/)

Remove all items from list.

<a id="skfolio.population.Population.composition"></a>

#### composition(display_sub_ptf_name=True)

Composition of each portfolio in the population.

* **Parameters:**
  **display_sub_ptf_name** *bool, default=True*
  : If this is set to True, each sub-portfolio name composing a multi-period
    portfolio is displayed.
* **Returns:**
  **df** *DataFrame*
  : Composition of the portfolios in the population.

<a id="skfolio.population.Population.contribution"></a>

#### contribution(measure, spacing=None, display_sub_ptf_name=True)

Contribution of each asset to a given measure of each portfolio in the
population.

* **Parameters:**
  **measure** *Measure*
  : The measure used for the contribution computation.

  **spacing** *float, optional*
  : Spacing “h” of the finite difference:
    $contribution(wi)= \frac{measure(wi-h) - measure(wi+h)}{2h}$.

  **display_sub_ptf_name** *bool, default=True*
  : If this is set to True, each sub-portfolio name composing a multi-period
    portfolio is displayed.
* **Returns:**
  **df** *DataFrame*
  : Contribution of each asset to a given measure of each portfolio in the
    population.

<a id="skfolio.population.Population.copy"></a>

#### copy(/)

Return a shallow copy of the list.

<a id="skfolio.population.Population.count"></a>

#### count(value, /)

Return number of occurrences of value.

<a id="skfolio.population.Population.cumulative_returns_df"></a>

#### cumulative_returns_df(use_tag_in_column_name=True)

DataFrame of cumulative returns for each portfolio in the population.
Non-compounded (arithmetic) cumulative returns start at 0.
Compounded (geometric) cumulative returns are expressed as a wealth index,
starting at 1.0 (i.e., the value of $1 invested).

* **Parameters:**
  **use_tag_in_column_name** *bool, default=True*
  : Whether to include the portfolio tag in the DataFrame column names.
    If True, each column name will use the portfolio name followed by its tag;
    if False, only the portfolio name will be used.
* **Returns:**
  **cumulative_returns** *DataFrame*
  : Cumulative returns DataFrame.

<a id="skfolio.population.Population.drawdowns_df"></a>

#### drawdowns_df(use_tag_in_column_name=True)

DataFrame of drawdowns for each portfolio in the population.

* **Parameters:**
  **use_tag_in_column_name** *bool, default=True*
  : Whether to include the portfolio tag in the DataFrame column names.
    If True, each column name will use the portfolio name followed by its tag;
    if False, only the portfolio name will be used.
* **Returns:**
  **drawdowns** *DataFrame*
  : Drawdowns DataFrame.

<a id="skfolio.population.Population.extend"></a>

#### extend(other)

Extend population list by appending elements from the iterable.

<a id="skfolio.population.Population.filter"></a>

#### filter(names=None, tags=None)

Filter the Population of portfolios by names and tags.
If both names and tags are provided, the intersection is returned.

* **Parameters:**
  **names** *str | list[str], optional*
  : If provided, the population is filtered by portfolio names.

  **tags** *str | list[str], optional*
  : If provided, the population is filtered by portfolio tags.
* **Returns:**
  **population** *Population*
  : A new population of portfolios filtered by names and tags.

<a id="skfolio.population.Population.index"></a>

#### index(value, start=0, stop=sys.maxsize, /)

Return first index of value.

Raises ValueError if the value is not present.

<a id="skfolio.population.Population.insert"></a>

#### insert(index, item)

Insert portfolio before index.

<a id="skfolio.population.Population.max_measure"></a>

#### max_measure(measure)

Return the portfolio with the maximum measure.

* **Parameters:**
  **measure: Measure**
  : The portfolio measure.
* **Returns:**
  **values** *BasePortfolio*
  : The portfolio with maximum measure.

<a id="skfolio.population.Population.measures"></a>

#### measures(measure)

Vector of portfolios measures for each portfolio from the
population.

* **Parameters:**
  **measure** *Measure*
  : The portfolio measure.
* **Returns:**
  **values** *ndarray*
  : The vector of portfolios measures.

<a id="skfolio.population.Population.measures_mean"></a>

#### measures_mean(measure)

Mean of portfolios measures for each portfolio from the
population.

* **Parameters:**
  **measure** *Measure*
  : The portfolio measure.
* **Returns:**
  **value** *float*
  : The mean of portfolios measures.

<a id="skfolio.population.Population.measures_std"></a>

#### measures_std(measure)

Standard-deviation of portfolios measures for each portfolio from the
population.

* **Parameters:**
  **measure** *Measure*
  : The portfolio measure.
* **Returns:**
  **value** *float*
  : The standard-deviation of portfolios measures.

<a id="skfolio.population.Population.min_measure"></a>

#### min_measure(measure)

Return the portfolio with the minimum measure.

* **Parameters:**
  **measure** *Measure*
  : The portfolio measure.
* **Returns:**
  **values** *BasePortfolio*
  : The portfolio with minimum measure.

<a id="skfolio.population.Population.non_denominated_sort"></a>

#### non_denominated_sort(first_front_only=False)

Alias of [`non_dominated_sort`](#skfolio.population.Population.non_dominated_sort).

#### Deprecated
Deprecated since version \`non_denominated_sort\`: is deprecated and will be removed in version 2.0.
Use [`non_dominated_sort`](#skfolio.population.Population.non_dominated_sort) instead.

<a id="skfolio.population.Population.non_dominated_sort"></a>

#### non_dominated_sort(first_front_only=False)

Fast non-dominated sorting.
Sort the portfolios into different non-domination levels.
Complexity O(MN^2) where M is the number of objectives and N the number of
portfolios.

* **Parameters:**
  **first_front_only** *bool, default=False*
  : If this is set to True, only the first front is sorted and returned.
    The default is `False`.
* **Returns:**
  **fronts** *list[list[int]]*
  : A list of Pareto fronts (lists), the first list includes
    non-dominated portfolios.

<a id="skfolio.population.Population.plot_composition"></a>

#### plot_composition(display_sub_ptf_name=True)

Plot the compositions of the portfolios in the population.

* **Parameters:**
  **display_sub_ptf_name** *bool, default=True*
  : If this is set to True, each sub-portfolio name composing a multi-period
    portfolio is displayed.
* **Returns:**
  **plot** *Figure*
  : Returns the plotly Figure object.

<a id="skfolio.population.Population.plot_contribution"></a>

#### plot_contribution(measure, spacing=None, display_sub_ptf_name=True)

Plot the contribution of each asset to a given measure of the portfolios
in the population.

* **Parameters:**
  **measure** *Measure*
  : The measure used for the contribution computation.

  **spacing** *float, optional*
  : Spacing “h” of the finite difference:
    $contribution(wi)= \frac{measure(wi-h) - measure(wi+h)}{2h}$

  **display_sub_ptf_name** *bool, default=True*
  : If this is set to True, each sub-portfolio name composing a multi-period
    portfolio is displayed.
* **Returns:**
  **plot** *Figure*
  : Returns the plotly Figure object.

<a id="skfolio.population.Population.plot_cumulative_returns"></a>

#### plot_cumulative_returns(log_scale=False, idx=None, use_tag_in_legend=True)

Plot the cumulative returns of the population’s portfolios.
Non-compounded (arithmetic) cumulative returns start at 0.
Compounded (geometric) cumulative returns are expressed as a wealth index,
starting at 1.0 (i.e., the value of $1 invested).

* **Parameters:**
  **log_scale** *bool, default=False*
  : If set to True, the cumulative returns are displayed with a
    logarithm scale on the y-axis. The cumulative returns must be compounded
    otherwise an exception is raise.

  **idx** *slice | array, optional*
  : Indexes or slice of the observations to plot.
    The default (`None`) is to take all observations.

  **use_tag_in_legend** *bool, default=True*
  : Whether to include the portfolio tag in legend entries.
    If True, each legend label will show the portfolio name followed by its tag;
    if False, only the portfolio name will be displayed.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object.

<a id="skfolio.population.Population.plot_distribution"></a>

#### plot_distribution(measure_list, tag_list=None, n_bins=None, \*\*kwargs)

Plot the population’s distribution for each measure provided in the
measure list.

* **Parameters:**
  **measure_list** *list[Measure]*
  : The list of portfolio measures. A different distribution is plotted per
    measure.

  **tag_list** *list[str], optional*
  : If this is provided, an additional distribution is plotted per measure
    for each tag provided.

  **n_bins** *int, optional*
  : Sets the number of bins.
* **Returns:**
  **plot** *Figure*
  : Returns the plotly Figure object.

<a id="skfolio.population.Population.plot_drawdowns"></a>

#### plot_drawdowns(idx=None, use_tag_in_legend=True)

Plot the drawdowns of the population’s portfolios.

* **Parameters:**
  **idx** *slice | array, optional*
  : Indexes or slice of the observations to plot.
    The default (`None`) is to take all observations.

  **use_tag_in_legend** *bool, default=True*
  : Whether to include the portfolio tag in legend entries.
    If True, each legend label will show the portfolio name followed by its tag;
    if False, only the portfolio name will be displayed.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object.

<a id="skfolio.population.Population.plot_measures"></a>

#### plot_measures(x, y, z=None, to_surface=False, hover_measures=None, show_fronts=False, color_scale=None, title='Portfolios')

Plot the 2D (or 3D) scatter points (or surface) of a given set of
measures for each portfolio in the population.

* **Parameters:**
  **x** *Measure*
  : The x-axis measure.

  **y** *Measure*
  : The y-axis measure.

  **z** *Measure, optional*
  : The z-axis measure.

  **to_surface** *bool, default=False*
  : If this is set to True, a surface is estimated.

  **hover_measures** *list[Measure], optional*
  : The list of measure to show on point hover.

  **show_fronts** *bool, default=False*
  : If this is set to True, the Pareto fronts are highlighted.
    The default is `False`.

  **color_scale** *Measure | str, optional*
  : If this is provided, a color scale is displayed.

  **title** *str, default=”Portfolios”*
  : The graph title. The default value is “Portfolios”.
* **Returns:**
  **plot** *Figure*
  : Returns the plotly Figure object.

<a id="skfolio.population.Population.plot_returns_distribution"></a>

#### plot_returns_distribution(percentile_cutoff=None)

Plot the Portfolios returns distribution using Gaussian KDE.

* **Parameters:**
  **percentile_cutoff** *float, default=None*
  : Percentile cutoff for tail truncation (percentile), in percent.
    If a float p is provided, the distribution support is truncated at the p-th
    and (100 - p)-th percentiles.
    If None, no truncation is applied (uses full min/max of returns).
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object

<a id="skfolio.population.Population.plot_rolling_measure"></a>

#### plot_rolling_measure(measure=Sharpe Ratio, window=30)

Plot the measure over a rolling window for each portfolio in the population.

* **Parameters:**
  **measure** *Measure, default = RatioMeasure.SHARPE_RATIO*
  : The measure.

  **window** *int, default=30*
  : The window size.
* **Returns:**
  **plot** *Figure*
  : Returns the plot Figure object

<a id="skfolio.population.Population.pop"></a>

#### pop(index=-1, /)

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

<a id="skfolio.population.Population.quantile"></a>

#### quantile(measure, q)

Return the portfolio corresponding to the `q` quantile for a given portfolio
measure.

* **Parameters:**
  **measure** *Measure*
  : The portfolio measure.

  **q** *float*
  : The quantile value.
* **Returns:**
  **values** *BasePortfolio*
  : Portfolio corresponding to the `q` quantile for the measure.

<a id="skfolio.population.Population.remove"></a>

#### remove(value, /)

Remove first occurrence of value.

Raises ValueError if the value is not present.

<a id="skfolio.population.Population.returns_df"></a>

#### returns_df(use_tag_in_column_name=True)

DataFrame of returns for each portfolio in the population.

* **Parameters:**
  **use_tag_in_column_name** *bool, default=True*
  : Whether to include the portfolio tag in the DataFrame column names.
    If True, each column name will use the portfolio name followed by its tag;
    if False, only the portfolio name will be used.
* **Returns:**
  **returns** *DataFrame*
  : Returns DataFrame where each column represents a portfolio’s returns
    time series.

<a id="skfolio.population.Population.reverse"></a>

#### reverse(/)

Reverse *IN PLACE*.

<a id="skfolio.population.Population.rolling_measure"></a>

#### rolling_measure(measure=Sharpe Ratio, window=30)

Compute the measure over a rolling window for each portfolio in the
: population.

* **Parameters:**
  **measure** *Measure, default=RatioMeasure.SHARPE_RATIO*
  : The measure. The default measure is the Sharpe Ratio.

  **window** *int, default=30*
  : The window size. The default value is `30` observations.
* **Returns:**
  **dataframe** *pandas DataFrame*
  : The rolling measures.

<a id="skfolio.population.Population.set_portfolio_params"></a>

#### set_portfolio_params(\*\*params)

Set the parameters of all the portfolios.

* **Parameters:**
  **\*\*params** *Any*
  : Portfolio parameters.
* **Returns:**
  **self** *Population*
  : The Population instance.

<a id="skfolio.population.Population.sort"></a>

#### sort(\*, key=None, reverse=False)

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable
(i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort
them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

<a id="skfolio.population.Population.sort_measure"></a>

#### sort_measure(measure, reverse=False)

Sort the population by a given portfolio measure.

* **Parameters:**
  **measure** *Measure*
  : The portfolio measure.

  **reverse** *bool, default=False*
  : If this is set to True, the order is reversed.
* **Returns:**
  **values** *Populations*
  : The sorted population.

<a id="skfolio.population.Population.summary"></a>

#### summary(formatted=True)

Summary of the portfolios in the population.

* **Parameters:**
  **formatted** *bool, default=True*
  : If this is set to True, the measures are formatted into rounded string with
    units.
    The default is `True`.
* **Returns:**
  **summary** *pandas DataFrame*
  : The population’s portfolios summary

### Notes

This method returns a static pandas DataFrame. For interactive exploration
(e.g., sortable/filterable/clickable tables or visual summaries), you may want
to use libraries such as `ipydatagrid`, `D-Tale`, or `Lux` in a Jupyter
environment, or `dash_table` / `streamlit.dataframe` when building dashboards.
For example, you can explore the summary with D-Tale:
`dtale.show(population.summary().T)`