Portfolio Finder API Reference¶

Portfolio Finder¶

Provides several classes and methods to identify an optimal portfolio allocation through back-testing.

class portfoliofinder.Allocations(step: float, funds: List[str])[source]¶

Bases: portfoliofinder.util.self_pickling.SelfPickling

A range of portfolio allocations.

This is the primary starting point when using Portfolio Finder. All other features can be reached from here through method chaining, starting with with_returns.

Example:

>>> Allocations(0.25, ['A','B'])
      A     B
0.00  1.00
0.25  0.75
0.50  0.50
0.75  0.25
1.00  0.00

Parameters

step – step amount between each allocation percent (i.e., 0.25 would produce allocations of 0, 0.25, 0.5, 0.75, 1)
funds – fund symbols for allocations

as_dataframe() → pandas.core.frame.DataFrame [source]¶

Gets this as a pandas DataFrame.

Note that changes to the returned DataFrame will modify this object.

filter(expression: Union[Callable[[pandas.core.frame.DataFrame], pandas.core.series.Series], str])[source]¶

Filters the range of allocations.

Examples:

>>> abc = Allocations(0.25, ['A','B','C'])
>>> abc.filter(lambda a: (a.A<=0.25) & (a.B>=0.75))
      A     B     C
3  0.00  0.75  0.25
4  0.00  1.00  0.00
8  0.25  0.75  0.00

>>> xyz = Allocations(0.25, ['X','Y','Z'])
>>> xyz.filter('X>=0.5 & Z==0')
       X     Y    Z
11  0.50  0.50  0.0
13  0.75  0.25  0.0
14  1.00  0.00  0.0

Parameters: expression – expression to filter by
Returns: a new instance of Allocations

classmethod load(filename_wo_ext: str)¶

Loads an object from a file.

Parameters: filename_wo_ext – filename without extension
Returns: instance of class read from file

save(filename_wo_ext: str)¶

Saves the object to a file.

Parameters: filename_wo_ext – filename without extension

with_returns(fund_returns: Union[pandas.core.frame.DataFrame, str], risk_free: Optional[str] = None, use_progressbar: bool = False) → portfoliofinder.portfolio.returns.Returns[source]¶

Adds a collection of fund returns, by year, to these portfolio allocations to calculate a set of portfolio returns, by year.

Parameters

fund_returns – a pandas DataFrame or path to CSV file with fund symbols as column headers
risk_free – fund symbol representing the risk free rate from fund_returns
use_progressbar – whether are not to display a progressbar to provide the status of large calculations

Returns

class portfoliofinder.BacktestedStatistics(data_by_allocation: Dict[tuple, pandas.core.series.Series], statistics: List[Union[str, Callable[[pandas.core.series.Series], float]]], use_progressbar: bool)[source]¶

Bases: portfoliofinder.util.self_pickling.SelfPickling

Statistical results for backtested portfolio data.

as_dataframe() → pandas.core.frame.DataFrame [source]¶

Gets this as a pandas DataFrame.

Note that changes to the returned DataFrame will modify this object.

filter(dataframe_filter_function) → portfoliofinder.portfolio.backtested_statistics.BacktestedStatistics[source]¶

Filters these statistical results with the specified function.

Parameters: dataframe_filter_function – function to filter results with
Returns: a new set of statistical results

filter_by_gte_percentile_of(percentile: int, statistic_label) → portfoliofinder.portfolio.backtested_statistics.BacktestedStatistics[source]¶

Filters these statistical results to only include data which are greater than or equal to the specified percential for the specified statistic.

Parameters

percentile – percentile as int from 0 to 100
statistic_label – label of the statistic

Returns

a new set of statistical results

filter_by_lte_percentile_of(percentile, statistic_label) → portfoliofinder.portfolio.backtested_statistics.BacktestedStatistics[source]¶

Filters these statistical results to only include data which are less than or equal to the specified percential for the specified statistic.

Parameters

percentile – percentile as int from 0 to 100
statistic_label – label of the statistic

Returns

a new set of statistical results

filter_by_max_of(statistic_label) → portfoliofinder.portfolio.backtested_statistics.BacktestedStatistics[source]¶

Filters these statistical results to only include data which maximizes the specified statistic.

Parameters: statistic_label – label of the statistic
Returns: a new set of statistical results

filter_by_min_of(statistic_label) → portfoliofinder.portfolio.backtested_statistics.BacktestedStatistics[source]¶

Filters these statistical results to only include data which minimizes the specified statistic.

Parameters: statistic_label – label of the statistic
Returns: a new set of statistical results

get_allocation_which_max_statistic(statistic) → pandas.core.series.Series [source]¶

Gets allocation which maximizes the specified statistic.

Parameters: statistic – statistic label (e.g., ‘mean’)
Returns: allocation which maximizes the statistic

get_allocation_which_min_statistic(statistic) → pandas.core.series.Series [source]¶

Gets allocation which minimizes the specified statistic.

Parameters: statistic – statistic label (e.g., ‘mean’)
Returns: allocation which minimizes the statistic

get_allocations_which_max_each_statistic() → pandas.core.frame.DataFrame [source]¶: Gets allocations which maximize each statistic.

get_allocations_which_min_each_statistic() → pandas.core.frame.DataFrame [source]¶: Gets allocation which minimize each statistic.

graph(x_axis, y_axis)[source]¶

Creates a scattergraph to visualize the data.

Parameters

x_axis – statistic label for the x axis (e.g., ‘mean’)
y_axis – statistic label for the y axis (e.g., ‘std’)

classmethod load(filename_wo_ext: str)¶

Loads an object from a file.

Parameters: filename_wo_ext – filename without extension
Returns: instance of class read from file

save(filename_wo_ext: str)¶

Saves the object to a file.

Parameters: filename_wo_ext – filename without extension

class portfoliofinder.BacktestedTimeframes(portfolio_returns_by_allocation: dict, target_value: float, use_progressbar: bool, contributions: portfoliofinder.contributions.contributions.Contributions)[source]¶

Bases: portfoliofinder.portfolio._backtested_data._BacktestedData

Backtested portfolio timeframes, by start year, required to achieve a target value.

get_series(allocation) → pandas.core.series.Series ¶

Gets the portfolio returns as a pandas Series for a given allocation.

Parameters: allocation – allocation to get returns for

get_statistics(statistics: List[Union[str, Callable[[pandas.core.series.Series], float]]] = ['min', <function percentile_for.<locals>.percentile_>, <function percentile_for.<locals>.percentile_>, <function percentile_for.<locals>.percentile_>, <function percentile_for.<locals>.percentile_>, <function percentile_for.<locals>.percentile_>, <function percentile_for.<locals>.percentile_>, <function percentile_for.<locals>.percentile_>, <function percentile_for.<locals>.percentile_>, <function percentile_for.<locals>.percentile_>, 'max', 'mean', <function gmean>, 'std', <function sharpe_ratio>], use_progressbar: bool = False) → portfoliofinder.portfolio.backtested_statistics.BacktestedStatistics¶

Gets statistical results for backtested portfolio data, by allocation mix.

Parameters

statistics – array of statistic functions for pandas Series
use_progressbar – whether are not to display a progressbar to provide the status of large calculations

Returns

A pandas Series containing values for each statistic

classmethod load(filename_wo_ext: str)¶

Loads an object from a file.

Parameters: filename_wo_ext – filename without extension
Returns: instance of class read from file

save(filename_wo_ext: str)¶

Saves the object to a file.

Parameters: filename_wo_ext – filename without extension

to_dataframe() → pandas.core.frame.DataFrame ¶: Converts this to a pandas DataFrame.

class portfoliofinder.BacktestedValues(portfolio_returns_by_allocation: dict, timeframe: int, use_progressbar: bool, contributions: portfoliofinder.contributions.contributions.Contributions)[source]¶

Bases: portfoliofinder.portfolio._backtested_data._BacktestedData

Backtested portfolio values, by start year, after a fixed timeframe.

get_series(allocation) → pandas.core.series.Series ¶

Gets the portfolio returns as a pandas Series for a given allocation.

Parameters: allocation – allocation to get returns for

get_statistics(statistics: List[Union[str, Callable[[pandas.core.series.Series], float]]] = ['min', <function percentile_for.<locals>.percentile_>, <function percentile_for.<locals>.percentile_>, <function percentile_for.<locals>.percentile_>, <function percentile_for.<locals>.percentile_>, <function percentile_for.<locals>.percentile_>, <function percentile_for.<locals>.percentile_>, <function percentile_for.<locals>.percentile_>, <function percentile_for.<locals>.percentile_>, <function percentile_for.<locals>.percentile_>, 'max', 'mean', <function gmean>, 'std', <function sharpe_ratio>], use_progressbar: bool = False) → portfoliofinder.portfolio.backtested_statistics.BacktestedStatistics¶

Gets statistical results for backtested portfolio data, by allocation mix.

Parameters

statistics – array of statistic functions for pandas Series
use_progressbar – whether are not to display a progressbar to provide the status of large calculations

Returns

A pandas Series containing values for each statistic

classmethod load(filename_wo_ext: str)¶

Loads an object from a file.

Parameters: filename_wo_ext – filename without extension
Returns: instance of class read from file

save(filename_wo_ext: str)¶

Saves the object to a file.

Parameters: filename_wo_ext – filename without extension

to_dataframe() → pandas.core.frame.DataFrame ¶: Converts this to a pandas DataFrame.

class portfoliofinder.Contributions[source]¶

Bases: abc.ABC

The contributions made to a portfolio for each year.

abstract get_contribution_for_year(year: int)[source]¶

Gets the contribution for the specified year.

Parameters: year – year relative to inception of portfolio (i.e., first year is 0)
Returns: contribution for the specified year

class portfoliofinder.InitialContribution(starting_value: float)[source]¶

Bases: portfoliofinder.contributions.contributions.Contributions

A single contribution that is made to a portfolio at its inception.

Parameters: starting_value – initial contribution at inception of portfolio

get_contribution_for_year(year)[source]¶

Gets the contribution for the specified year.

Parameters: year – year relative to inception of portfolio (i.e., first year is 0)
Returns: contribution for the specified year

class portfoliofinder.RegularContributions(starting_value: float, annual_contribution: float)[source]¶

Bases: portfoliofinder.contributions.contributions.Contributions

An annual contributions are made to a portfolio.

Parameters

starting_value – initial contribution made at portfolio inception
annual_contribution – subsequent annual contributions

get_contribution_for_year(year: int)[source]¶

Gets the contribution for the specified year.

Parameters: year – year relative to inception of portfolio (i.e., first year is 0)
Returns: contribution for the specified year

class portfoliofinder.Returns(returns_by_symbol: pandas.core.frame.DataFrame, allocations: pandas.core.frame.DataFrame, use_progressbar: bool = False)[source]¶

Bases: portfoliofinder.util.self_pickling.SelfPickling

Portfolio returns by year for a set of allocation mixes.

get_series(allocation) → pandas.core.series.Series [source]¶

Gets the portfolio returns as a pandas Series for a given allocation.

Parameters: allocation – allocation to get returns for

classmethod load(filename_wo_ext: str)¶

Loads an object from a file.

Parameters: filename_wo_ext – filename without extension
Returns: instance of class read from file

save(filename_wo_ext: str)¶

Saves the object to a file.

Parameters: filename_wo_ext – filename without extension

to_dataframe() → pandas.core.frame.DataFrame [source]¶: Converts this to a pandas DataFrame.

with_contributions(contributions: portfoliofinder.contributions.contributions.Contributions = <portfoliofinder.contributions.initial_contribution.InitialContribution object>)[source]¶

Add contributions to these portfolio returns.

Parameters: contributions – contribution schedule
Returns: portfolio returns with contributions

with_initial_contribution(starting_value: float)[source]¶

Add an initial contribution to these portfolio returns.

Parameters: starting_value – initial contribution at inception of portfolio

with_regular_contributions(starting_value: float, annual_contribution: float)[source]¶

Add regular contributions to these portfolio returns.

Parameters

starting_value – initial contribution made at portfolio inception
annual_contribution – subsequent annual contributions

with_scheduled_contributions(scheduled_contributions: Dict[int, float])[source]¶

Add scheduled contributions to these portfolio returns.

Parameters: scheduled_contributions – contributions by year relative to inception of portfolio

class portfoliofinder.ScheduledContributions(scheduled_contributions: Dict[int, float])[source]¶

Bases: portfoliofinder.contributions.contributions.Contributions

Contributions which occur at specific years in the life of the portfolio.

Parameters: scheduled_contributions – contributions by year relative to inception of portfolio

get_contribution_for_year(year)[source]¶

Gets the contribution for the specified year.

Parameters: year – year relative to inception of portfolio (i.e., first year is 0)
Returns: contribution for the specified year

Portfolio Finder API Reference¶

Portfolio Finder¶

Subpackages¶