PyPortfolioOpt

https://pyportfolioopt.readthedocs.io/en/latest/
Admin
PyPortfolioOpt is a Python library for portfolio optimization, implementing classical methods like...
Tokens:71,762
Snippets:232
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install PyPortfolioOpt from source

Source: https://pyportfolioopt.readthedocs.io/en/latest/index

Installs PyPortfolioOpt directly from its source directory using the setup.py script. This method is typically used when installing from a local clone or downloaded archive.

```Shell
python setup.py install
```

--------------------------------

### Install PyPortfolioOpt via pip

Source: https://pyportfolioopt.readthedocs.io/en/latest/index

Installs the PyPortfolioOpt library using the pip package manager. This is the standard and recommended way to install Python packages for general use.

```Shell
pip install PyPortfolioOpt
```

--------------------------------

### Optimize portfolio for maximal Sharpe ratio from historical data

Source: https://pyportfolioopt.readthedocs.io/en/latest/index

This snippet illustrates a complete workflow for portfolio optimization using PyPortfolioOpt. It shows how to read historical price data, calculate expected returns and a sample covariance matrix, and then use these to optimize a portfolio for the maximal Sharpe ratio, finally printing the portfolio's performance metrics.

```python
import pandas as pd
from pypfopt.efficient_frontier import EfficientFrontier
from pypfopt import risk_models
from pypfopt import expected_returns

# Read in price data
df = pd.read_csv("tests/resources/stock_prices.csv", parse_dates=True, index_col="date")

# Calculate expected returns and sample covariance
mu = expected_returns.mean_historical_return(df)
S = risk_models.sample_cov(df)

# Optimize for maximal Sharpe ratio
ef = EfficientFrontier(mu, S)
weights = ef.max_sharpe()
ef.portfolio_performance(verbose=True)
```

--------------------------------

### Install PyPortfolioOpt in editable mode

Source: https://pyportfolioopt.readthedocs.io/en/latest/index

Installs PyPortfolioOpt directly from its Git repository in editable mode. This allows local modifications to the source code to be immediately reflected in your environment without reinstallation, which is ideal for active development.

```Shell
pip install -e git+https://github.com/robertmartin8/PyPortfolioOpt.git
```

--------------------------------

### Clone PyPortfolioOpt Git repository

Source: https://pyportfolioopt.readthedocs.io/en/latest/index

Clones the PyPortfolioOpt source code repository from GitHub. This action is primarily for developers who intend to modify, contribute to, or deeply inspect the library's source code.

```Shell
git clone https://github.com/robertmartin8/PyPortfolioOpt
```

--------------------------------

### PyPortfolioOpt Initialization Methods

Source: https://pyportfolioopt.readthedocs.io/en/latest/genindex

This entry lists the `__init__` methods for various classes within the PyPortfolioOpt library, indicating their module and class paths. These methods are used for object instantiation and initial setup.

```APIDOC
pypfopt.base_optimizer.BaseConvexOptimizer.__init__()
pypfopt.base_optimizer.BaseOptimizer.__init__()
pypfopt.black_litterman.BlackLittermanModel.__init__()
pypfopt.cla.CLA.__init__()
pypfopt.discrete_allocation.DiscreteAllocation.__init__()
pypfopt.efficient_frontier.EfficientFrontier.__init__()
pypfopt.hierarchical_portfolio.HRPOpt.__init__()
pypfopt.risk_models.CovarianceShrinkage.__init__()
```

--------------------------------

### Add PyPortfolioOpt with Poetry

Source: https://pyportfolioopt.readthedocs.io/en/latest/index

Adds PyPortfolioOpt as a dependency to a new or existing Poetry project. Poetry is a dependency management and packaging tool for Python projects, offering robust environment isolation.

```Shell
poetry add PyPortfolioOpt
```

--------------------------------

### Optimize portfolio for maximal Sharpe ratio with pre-calculated inputs

Source: https://pyportfolioopt.readthedocs.io/en/latest/index

This snippet demonstrates how to use PyPortfolioOpt's `EfficientFrontier` to find the portfolio weights that maximize the Sharpe ratio. It assumes that expected returns (`mu`) and a risk model (`S`) are already computed and available as inputs.

```python
from pypfopt.efficient_frontier import EfficientFrontier

ef = EfficientFrontier(mu, S)
weights = ef.max_sharpe()
```

--------------------------------

### Example Output of Portfolio Performance Metrics

Source: https://pyportfolioopt.readthedocs.io/en/latest/UserGuide

This is an example of the textual output generated by the `portfolio_performance(verbose=True)` method, providing key metrics for the optimized portfolio. It summarizes the expected annual return, volatility, and Sharpe Ratio.

```python
Expected annual return: 33.0%
Annual volatility: 21.7%
Sharpe Ratio: 1.43
```

--------------------------------

### Example Output of Cleaned Portfolio Weights

Source: https://pyportfolioopt.readthedocs.io/en/latest/UserGuide

This is an example of the dictionary output generated by the `clean_weights()` method, illustrating the optimized weights for various assets after cleaning. It demonstrates how `clean_weights()` truncates small weights to zero for practical use.

```python
{'GOOG': 0.01269,
'AAPL': 0.09202,
'FB': 0.19856,
'BABA': 0.09642,
'AMZN': 0.07158,
'GE': 0.0,
'AMD': 0.0,
'WMT': 0.0,
'BAC': 0.0,
'GM': 0.0,
'T': 0.0,
'UAA': 0.0,
'SHLD': 0.0,
'XOM': 0.0,
'RRC': 0.0,
'BBY': 0.06129,
'MA': 0.24562,
'PFE': 0.18413,
'JPM': 0.0,
'SBUX': 0.03769}
```

--------------------------------

### Plotting a Basic Efficient Frontier with Constraints

Source: https://pyportfolioopt.readthedocs.io/en/latest/Plotting

This snippet demonstrates how to instantiate an `EfficientFrontier` object, add custom weight constraints using lambda functions, and then plot the efficient frontier using `plotting.plot_efficient_frontier()`. It shows the basic setup for visualizing the optimal portfolio space with specific asset allocation rules.

```python
ef = EfficientFrontier(mu, S, weight_bounds=(None, None))
ef.add_constraint(lambda w: w[0] >= 0.2)
ef.add_constraint(lambda w: w[2] == 0.15)
ef.add_constraint(lambda w: w[3] + w[4] <= 0.10)

fig, ax = plt.subplots()
plotting.plot_efficient_frontier(ef, ax=ax, show_assets=True)
plt.show()
```

--------------------------------

### Plotting Efficient Frontier with Max Sharpe and Random Portfolios

Source: https://pyportfolioopt.readthedocs.io/en/latest/Plotting

This comprehensive example demonstrates how to plot the efficient frontier, highlight the maximum Sharpe ratio portfolio (tangency portfolio), and overlay a scatter plot of randomly generated portfolios. The random portfolios are colored by their Sharpe ratio, providing a visual comparison of optimal vs. suboptimal allocations and illustrating the concept of diversification.

```python
fig, ax = plt.subplots()
ef_max_sharpe = ef.deepcopy()
plotting.plot_efficient_frontier(ef, ax=ax, show_assets=False)

# Find the tangency portfolio
ef_max_sharpe.max_sharpe()
ret_tangent, std_tangent, _ = ef_max_sharpe.portfolio_performance()
ax.scatter(std_tangent, ret_tangent, marker="*", s=100, c="r", label="Max Sharpe")

# Generate random portfolios
n_samples = 10000
w = np.random.dirichlet(np.ones(ef.n_assets), n_samples)
rets = w.dot(ef.expected_returns)
stds = np.sqrt(np.diag(w @ ef.cov_matrix @ w.T))
sharpes = rets / stds
ax.scatter(stds, rets, marker=".", c=sharpes, cmap="viridis_r")

# Output
ax.set_title("Efficient Frontier with random portfolios")
ax.legend()
plt.tight_layout()
plt.savefig("ef_scatter.png", dpi=200)
plt.show()
```

--------------------------------

### Calculate Portfolio Performance with PyPortfolioOpt

Source: https://pyportfolioopt.readthedocs.io/en/latest/MeanVariance

Demonstrates how to use the `portfolio_performance` function independently for debugging or analysis purposes, providing an example with common parameters like weights, expected returns, and covariance matrix.

```python
from pypfopt import base_optimizer

base_optimizer.portfolio_performance(
    weights, expected_returns, cov_matrix, verbose=True, risk_free_rate=0.02
)
```

--------------------------------

### Optimize Portfolio for Efficient Semivariance in PyPortfolioOpt

Source: https://pyportfolioopt.readthedocs.io/en/latest/GeneralEfficientFrontier

This Python example demonstrates how to use PyPortfolioOpt's `EfficientSemivariance` class to find a portfolio that minimizes semivariance for a specified target annual return. It involves calculating expected returns and historical returns from a price DataFrame, then initializing the optimizer to achieve the desired portfolio characteristics.

```python
from pypfopt import expected_returns, EfficientSemivariance

df = ... # your dataframe of prices
mu = expected_returns.mean_historical_returns(df)
historical_returns = expected_returns.returns_from_prices(df)

es = EfficientSemivariance(mu, historical_returns)
es.efficient_return(0.20)
```

--------------------------------

### Solve CVXPY Optimization Problem in PyPortfolioOpt

Source: https://pyportfolioopt.readthedocs.io/en/latest/_modules/pypfopt/base_optimizer

This helper method solves the underlying cvxpy optimization problem. It initializes the problem if not already done, checks for changes to the objective or constraints after initial setup, and handles the solving process with specified solver options. It raises `exceptions.OptimizationError` if the problem is not solvable or if the solver status is not optimal, and `exceptions.InstantiationError` if objectives or constraints are changed after initial optimization.

```python
    def _solve_cvxpy_opt_problem(self):
        """
        Helper method to solve the cvxpy problem and check output,
        once objectives and constraints have been defined

        :raises exceptions.OptimizationError: if problem is not solvable by cvxpy
        """
        try:
            if self._opt is None:
                self._opt = cp.Problem(cp.Minimize(self._objective), self._constraints)
                self._initial_objective = self._objective.id
                self._initial_constraint_ids = {const.id for const in self._constraints}
            else:
                if not self._objective.id == self._initial_objective:
                    raise exceptions.InstantiationError(
                        "The objective function was changed after the initial optimization. "
                        "Please create a new instance instead."
                    )

                constr_ids = {const.id for const in self._constraints}
                if not constr_ids == self._initial_constraint_ids:
                    raise exceptions.InstantiationError(
                        "The constraints were changed after the initial optimization. "
                        "Please create a new instance instead."
                    )
            self._opt.solve(
                solver=self._solver, verbose=self._verbose, **self._solver_options
            )

        except (TypeError, cp.DCPError) as e:
            raise exceptions.OptimizationError from e

        if self._opt.status not in {"optimal", "optimal_inaccurate"}:
            raise exceptions.OptimizationError(
                "Solver status: {}".format(self._opt.status)
            )
        self.weights = self._w.value.round(16) + 0.0  # +0.0 removes signed zero
        return self._make_output_weights()
```

--------------------------------

### Black-Litterman Model Constructor Core Logic

Source: https://pyportfolioopt.readthedocs.io/en/latest/_modules/pypfopt/black_litterman

Contains the Python implementation for initializing the Black-Litterman model, including handling Python version warnings, storing the covariance matrix, initializing the base optimizer, sanitizing input views, and setting up internal attributes for posterior returns and covariance.

```Python
if sys.version_info[1] == 5:  # pragma: no cover
    warnings.warn(
        "When using python 3.5 you must explicitly construct the Black-Litterman inputs"
    )

# Keep raw dataframes
self._raw_cov_matrix = cov_matrix

#  Initialise base optimizer
if isinstance(cov_matrix, np.ndarray):
    self.cov_matrix = cov_matrix
    super().__init__(len(cov_matrix), list(range(len(cov_matrix))))
else:
    self.cov_matrix = cov_matrix.values
    super().__init__(len(cov_matrix), cov_matrix.columns)

#  Sanitise inputs
if absolute_views is not None:
    self.Q, self.P = self._parse_views(absolute_views)
else:
    self._set_Q_P(Q, P)
self._set_risk_aversion(risk_aversion)
self._set_pi(pi, **kwargs)
self._set_tau(tau)
# Make sure all dimensions work
self._check_attribute_dimensions()

self._set_omega(omega, view_confidences)

# Private intermediaries
self._tau_sigma_P = None
self._A = None

self.posterior_rets = None
self.posterior_cov = None
```

--------------------------------

### Example Covariance Matrix Output from PyPortfolioOpt

Source: https://pyportfolioopt.readthedocs.io/en/latest/UserGuide

This snippet shows a partial example of the estimated covariance matrix `S` returned by PyPortfolioOpt. It is a pandas DataFrame where rows and columns represent assets, and values indicate the covariance between their returns.

```Data
        GOOG      AAPL        FB      BABA      AMZN        GE       AMD  \
GOOG  0.045529  0.022143  0.006389  0.003720  0.026085  0.015815  0.021761
AAPL  0.022143  0.207037  0.004334  0.002954  0.058200  0.038102  0.084053
FB    0.006389  0.004334  0.029233  0.003770  0.007619  0.003008  0.005804
BABA  0.003720  0.002954  0.003770  0.013438  0.004176  0.002011  0.006332
AMZN  0.026085  0.058200  0.007619  0.004176  0.276365  0.038169  0.075657
GE    0.015815  0.038102  0.003008  0.002011  0.038169  0.083405  0.048580
AMD   0.021761  0.084053  0.005804  0.006332  0.075657  0.048580  0.388916
```

--------------------------------

### DiscreteAllocation Class Overview and Initialization

Source: https://pyportfolioopt.readthedocs.io/en/latest/_modules/pypfopt/discrete_allocation

This documentation block describes the `DiscreteAllocation` class, its purpose, instance variables, and public methods. It also details the `__init__` constructor, outlining its parameters, their types, default values, and validation rules for initializing a discrete allocation object.

```APIDOC
DiscreteAllocation Class:
  Description: Generates a discrete portfolio allocation from continuous weights.

  Instance Variables:
    - weights: dict (continuous weights)
    - latest_prices: pd.Series or dict (most recent asset prices)
    - total_portfolio_value: int/float (desired total portfolio value, default 10000)
    - short_ratio: float (short ratio, e.g., 0.3 for 130/30. Defaults to sum of negative weights if None.)
    - allocation: dict (output allocation)

  Public Methods:
    - greedy_portfolio(): Uses a greedy algorithm for allocation.
    - lp_portfolio(): Uses linear programming for allocation.

  __init__(self, weights, latest_prices, total_portfolio_value=10000, short_ratio=None):
    Description: Initializes the DiscreteAllocation object.
    Parameters:
      - weights: dict
        Description: Continuous weights generated from the `efficient_frontier` module.
        Type: dict
        Constraints: Must be a dictionary of {ticker: weight}, no NaNs.
      - latest_prices: pd.Series
        Description: The most recent price for each asset.
        Type: pd.Series
        Constraints: Must be a pd.Series with no NaNs.
      - total_portfolio_value: int/float, optional
        Description: The desired total value of the portfolio.
        Default: 10000
        Constraints: Must be greater than zero.
      - short_ratio: float, optional
        Description: The short ratio (e.g., 0.3 for 130/30). If None, defaults to the sum of negative input weights.
        Default: None
        Constraints: Must be non-negative if provided.
    Raises:
      - TypeError: If `weights` is not a dict.
      - TypeError: If `latest_prices` isn't a series.
      - ValueError: If `short_ratio < 0`.
      - ValueError: If `weights` contains NaNs.
      - ValueError: If `total_portfolio_value` is not greater than zero.
```

--------------------------------

### Example Historical Price Data Format for PyPortfolioOpt

Source: https://pyportfolioopt.readthedocs.io/en/latest/UserGuide

This snippet illustrates the expected format for historical price data used by PyPortfolioOpt. It should be a pandas DataFrame with dates as the index and asset tickers as columns, containing time series of prices.

```Data
                XOM        RRC        BBY         MA        PFE        JPM
date
2010-01-04  54.068794  51.300568  32.524055  22.062426  13.940202  35.175220
2010-01-05  54.279907  51.993038  33.349487  21.997149  13.741367  35.856571
2010-01-06  54.749043  51.690697  33.090542  22.081820  13.697187  36.053574
2010-01-07  54.577045  51.593170  33.616547  21.937523  13.645634  36.767757
2010-01-08  54.358093  52.597733  32.297466  21.945297  13.756095  36.677460
```

--------------------------------

### Calculate Max Sharpe Ratio Portfolio Weights with PyPortfolioOpt

Source: https://pyportfolioopt.readthedocs.io/en/latest/UserGuide

This snippet demonstrates how to initialize the `EfficientFrontier` object with expected returns (`mu`) and covariance matrix (`S`), and then calculate the portfolio weights that maximize the Sharpe ratio using the `max_sharpe()` method from PyPortfolioOpt.

```python
from pypfopt.efficient_frontier import EfficientFrontier

ef = EfficientFrontier(mu, S)
weights = ef.max_sharpe()
```

--------------------------------

### Optimize Custom Convex Objective Function (PyPortfolioOpt)

Source: https://pyportfolioopt.readthedocs.io/en/latest/_modules/pypfopt/base_optimizer

Documents the `convex_objective` method for optimizing a custom convex objective function using cvxpy. It explains parameters like `custom_objective` (a function using cvxpy atoms) and `weights_sum_to_one`, and provides an example of a logarithmic barrier objective.

```APIDOC
def convex_objective(self, custom_objective, weights_sum_to_one=True, **kwargs)
  - custom_objective: An objective function to be MINIMISED, written using cvxpy atoms. Signature: (cp.Variable, `**kwargs`) -> cp.Expression.
  - weights_sum_to_one: bool, optional. Whether to add the default objective (weights sum to one), defaults to True.
  - **kwargs: Additional optimizer arguments.
  - Raises: OptimizationError if the objective is nonconvex or constraints nonlinear.
  - Returns: OrderedDict. Asset weights for the efficient risk portfolio.

Example:
# Could define as a lambda function instead
def logarithmic_barrier(w, cov_matrix, k=0.1):
    # 60 Years of Portfolio Optimization, Kolm et al (2014)
    return cp.quad_form(w, cov_matrix) - k * cp.sum(cp.log(w))

w = ef.convex_objective(logarithmic_barrier, cov_matrix=ef.cov_matrix)
```

--------------------------------

### CovarianceShrinkage Class Initialization

Source: https://pyportfolioopt.readthedocs.io/en/latest/_modules/pypfopt/risk_models

This class provides methods for computing shrinkage estimates of the covariance matrix. The constructor initializes the class with price or return data, calculates the sample covariance matrix, and sets up the frequency for annualization. It requires the scikit-learn library for its functionality.

```python
class CovarianceShrinkage:
    """
    Provide methods for computing shrinkage estimates of the covariance matrix, using the
    sample covariance matrix and choosing the structured estimator to be an identity matrix
    multiplied by the average sample variance. The shrinkage constant can be input manually,
    though there exist methods (notably Ledoit Wolf) to estimate the optimal value.

    Instance variables:

    - ``X`` - pd.DataFrame (returns)
    - ``S`` - np.ndarray (sample covariance matrix)
    - ``delta`` - float (shrinkage constant)
    - ``frequency`` - int
    """
    def __init__(self, prices, returns_data=False, frequency=252, log_returns=False):
        """
        :param prices: adjusted closing prices of the asset, each row is a date and each column is a ticker/id.
        :type prices: pd.DataFrame
        :param returns_data: if true, the first argument is returns instead of prices.
        :type returns_data: bool, defaults to False.
        :param frequency: number of time periods in a year, defaults to 252 (the number of trading days in a year)
        :type frequency: int, optional
        :param log_returns: whether to compute using log returns
        :type log_returns: bool, defaults to False
        """
        # Optional import
        try:
            from sklearn import covariance

            self.covariance = covariance
        except (ModuleNotFoundError, ImportError):  # pragma: no cover
            raise ImportError("Please install scikit-learn via pip or poetry")

        if not isinstance(prices, pd.DataFrame):
            warnings.warn("data is not in a dataframe", RuntimeWarning)
            prices = pd.DataFrame(prices)

        self.frequency = frequency

        if returns_data:
            self.X = prices.dropna(how="all")
        else:
            self.X = returns_from_prices(prices, log_returns).dropna(how="all")

        self.S = self.X.cov().values
        self.delta = None  # shrinkage constant
```

--------------------------------

### Optimize Custom Nonconvex Objective Function (PyPortfolioOpt)

Source: https://pyportfolioopt.readthedocs.io/en/latest/_modules/pypfopt/base_optimizer

Documents the `nonconvex_objective` method for optimizing a custom nonconvex objective function using the scipy backend. It supports nonlinear constraints and allows specifying a solver. An example demonstrates optimizing for maximum return with market-neutral and risk constraints.

```APIDOC
def nonconvex_objective(
    self,
    custom_objective,
    objective_args=None,
    weights_sum_to_one=True,
    constraints=None,
    solver="SLSQP",
    initial_guess=None,
)
  - custom_objective: function with signature (np.ndarray, args) -> float. An objective function to be MINIMISED.
  - objective_args: tuple of np.ndarrays. Arguments for the objective function (excluding weight).
  - weights_sum_to_one: bool, optional. Whether to add the default objective, defaults to True.
  - constraints: dict list. List of constraints in the scipy format (i.e dicts).
  - solver: string. Which SCIPY solver to use, e.g "SLSQP", "COBYLA", "BFGS".
  - initial_guess: np.ndarray, optional. Initial guess for the optimization.

Example:
# Market-neutral efficient risk
constraints = [
    {"type": "eq", "fun": lambda w: np.sum(w)},  # weights sum to zero
    {
        "type": "eq",
        "fun": lambda w: target_risk ** 2 - np.dot(w.T, np.dot(ef.cov_matrix, w)),
    },  # risk = target_risk
]
ef.nonconvex_objective(
    lambda w, mu: -w.T.dot(mu),  # min negative return (i.e maximise return)
    objective_args=(ef.expected_returns,),
    weights_sum_to_one=False,
    constraints=constraints,
)
```

--------------------------------

### Black-Litterman Model Constructor API Reference

Source: https://pyportfolioopt.readthedocs.io/en/latest/_modules/pypfopt/black_litterman

Documents the parameters and their expected types for the `BlackLitterman` class constructor, detailing how different inputs like `pi`, `omega`, and `absolute_views` are handled, along with their constraints and default values.

```APIDOC
__init__(
    cov_matrix,
    pi=None,
    absolute_views=None,
    Q=None,
    P=None,
    omega=None,
    view_confidences=None,
    tau=0.05,
    risk_aversion=1,
    **kwargs
)
  - cov_matrix: NxN covariance matrix of returns
    Type: pd.DataFrame or np.ndarray
  - pi: Nx1 prior estimate of returns, defaults to None.
    If pi="market", calculate a market-implied prior (requires market_caps to be passed).
    If pi="equal", use an equal-weighted prior.
    Type: np.ndarray, pd.Series, optional
  - absolute_views: a collection of K absolute views on a subset of assets, defaults to None.
    If this is provided, we do not need P, Q.
    Type: pd.Series or dict, optional
  - Q: Kx1 views vector, defaults to None
    Type: np.ndarray or pd.DataFrame, optional
  - P: KxN picking matrix, defaults to None
    Type: np.ndarray or pd.DataFrame, optional
  - omega: KxK view uncertainty matrix (diagonal), defaults to None
    Can instead pass "idzorek" to use Idzorek's method (requires you to pass view_confidences).
    If omega="default" or None, we set the uncertainty proportional to the variance.
    Type: np.ndarray or Pd.DataFrame, or string, optional
  - view_confidences: Kx1 vector of percentage view confidences (between 0 and 1),
    required to compute omega via Idzorek's method.
    Type: np.ndarray, pd.Series, list, optional
  - tau: the weight-on-views scalar (default is 0.05)
    Type: float, optional
  - risk_aversion: risk aversion parameter, defaults to 1
    Type: positive float, optional
  - market_caps: (kwarg) market caps for the assets, required if pi="market"
    Type: np.ndarray, pd.Series, optional
  - risk_free_rate: (kwarg) risk_free_rate is needed in some methods
    Type: float, defaults to 0.02
```

--------------------------------

### Minimize Tracking Error with PyPortfolioOpt's BaseConvexOptimizer

Source: https://pyportfolioopt.readthedocs.io/en/latest/GeneralEfficientFrontier

This Python example demonstrates how to set up a custom optimization problem in PyPortfolioOpt to minimize the tracking error between a portfolio and a benchmark index. It utilizes the BaseConvexOptimizer class and the ex_post_tracking_error function, requiring historic asset and benchmark returns as input for the optimization process.

```python
from pypfopt.base_optimizer import BaseConvexOptimizer
from pypfopt.objective_functions import ex_post_tracking_error

historic_rets = ... # dataframe of historic asset returns
benchmark_rets = ... # pd.Series of historic benchmark returns (same index as historic)

opt = BaseConvexOptimizer(
    n_assets=len(historic_returns.columns),
    tickers=historic_returns.columns,
    weight_bounds=(0, 1)
)
opt.convex_objective(
    ex_post_tracking_error,
    historic_returns=historic_rets,
    benchmark_returns=benchmark_rets,
)
weights = opt.clean_weights()
```

--------------------------------

### PyPortfolioOpt DiscreteAllocation Class API Reference

Source: https://pyportfolioopt.readthedocs.io/en/latest/Postprocessing

Comprehensive API documentation for the `DiscreteAllocation` class within the `pypfopt.discrete_allocation` module. This class facilitates the conversion of continuous portfolio weights into discrete share allocations using various algorithms, including greedy and linear programming approaches. It details the constructor, instance variables, public methods, and utility functions.

```APIDOC
class pypfopt.discrete_allocation.DiscreteAllocation(weights, latest_prices, total_portfolio_value=10000, short_ratio=None)
  Description: Generate a discrete portfolio allocation from continuous weights.
  Instance Variables:
    Inputs:
      - weights (dict)
      - latest_prices (pd.Series or dict)
      - total_portfolio_value (int/float)
      - short_ratio (float)
    Output:
      - allocation (dict)
  Public Methods:
    - greedy_portfolio()
    - lp_portfolio()

  __init__(weights, latest_prices, total_portfolio_value=10000, short_ratio=None)
    Description: Initializes the DiscreteAllocation object.
    Parameters:
      - weights (dict): Continuous weights generated from the `efficient_frontier` module.
      - latest_prices (pd.Series): The most recent price for each asset.
      - total_portfolio_value (int/float, optional): The desired total value of the portfolio (default: 10000).
      - short_ratio (float, optional): The short ratio (e.g., 0.3 for 130/30). Defaults to input weights if None.
    Raises:
      - TypeError: If `weights` is not a dict.
      - TypeError: If `latest_prices` is not a pd.Series.
      - ValueError: If `short_ratio` is less than 0.

  _allocation_rmse_error(verbose=True)
    Description: Utility function to calculate and print RMSE error between discretised weights and continuous weights. RMSE was used instead of MAE because we want to penalise large variations.
    Parameters:
      - verbose (bool): If True, prints weight discrepancies.
    Returns:
      - float: RMSE error.

  static _remove_zero_positions(allocation)
    Description: Utility function to remove zero positions (i.e., assets with no shares being bought).

  greedy_portfolio(reinvest=False, verbose=False)
    Description: Converts continuous weights into a discrete portfolio allocation using a greedy iterative approach.
    Parameters:
      - reinvest (bool, defaults to False): Whether or not to reinvest cash gained from shorting.
      - verbose (bool, defaults to False): If True, prints error analysis.
    Returns:
      - (dict, float): A tuple containing the number of shares of each ticker that should be purchased, along with the amount of funds leftover.

  lp_portfolio(reinvest=False, verbose=False, solver='ECOS_BB')
    Description: Converts continuous weights into a discrete portfolio allocation using integer programming.
    Parameters:
      - reinvest (bool, defaults to False): Whether or not to reinvest cash gained from shorting.
      - verbose (bool): If True, prints error analysis.
      - solver (str, defaults to "ECOS_BB"): The CVXPY solver to use (must support mixed-integer programs).
    Returns:
      - (dict, float): A tuple containing the number of shares of each ticker that should be purchased, along with the amount of funds leftover.
```

--------------------------------

### PyPortfolioOpt BaseConvexOptimizer Class and Custom Objective Methods

Source: https://pyportfolioopt.readthedocs.io/en/latest/GeneralEfficientFrontier

This documentation details the `BaseConvexOptimizer` class in PyPortfolioOpt, which serves as the foundation for defining and solving custom portfolio optimization problems. It covers the `convex_objective` method for optimizing convex functions using `cvxpy` and the `nonconvex_objective` method for handling non-convex problems with `scipy.optimize`, including their parameters, return types, and usage examples.

```APIDOC
class pypfopt.base_optimizer.BaseConvexOptimizer

BaseConvexOptimizer.convex_objective(custom_objective, weights_sum_to_one=True, **kwargs)
  Optimize a custom convex objective function. Constraints should be added with ef.add_constraint(). Optimizer arguments must be passed as keyword-args.
  
  Parameters:
    - custom_objective (function with signature (cp.Variable, **kwargs) -> cp.Expression): an objective function to be MINIMISED. This should be written using cvxpy atoms. Should map (w, **kwargs) -> float.
    - weights_sum_to_one (bool, optional): whether to add the default objective, defaults to True.
  Raises:
    - OptimizationError: if the objective is nonconvex or constraints nonlinear.
  Returns:
    - OrderedDict: asset weights for the efficient risk portfolio.
  
  Example:
  # Could define as a lambda function instead
  def logarithmic_barrier(w, cov_matrix, k=0.1):
      # 60 Years of Portfolio Optimization, Kolm et al (2014)
      return cp.quad_form(w, cov_matrix) - k * cp.sum(cp.log(w))

  w = ef.convex_objective(logarithmic_barrier, cov_matrix=ef.cov_matrix)

BaseConvexOptimizer.nonconvex_objective(custom_objective, objective_args=None, weights_sum_to_one=True, constraints=None, solver='SLSQP', initial_guess=None)
  Optimize some objective function using the scipy backend. This can support nonconvex objectives and nonlinear constraints, but may get stuck at local minima.
  
  Parameters:
    - custom_objective: The objective function.
    - objective_args: Arguments to pass to the objective function.
    - weights_sum_to_one (bool): Whether weights should sum to one.
    - constraints: A list of scipy.optimize constraints.
    - solver (str): The scipy.optimize solver to use.
    - initial_guess: Initial guess for the weights.
  
  Example:
  # Market-neutral efficient risk
  constraints = [
      {"type": "eq", "fun": lambda w: np.sum(w)},  # weights sum to zero
      {
          "type": "eq",
          "fun": lambda w: target_risk ** 2 - np.dot(w.T, np.dot(ef.cov_matrix, w)),
      },  # risk = target_risk
  ]
  ef.nonconvex_objective(
      lambda w, mu: -w.T.dot(mu),  # min negative return (i.e maximise return)
      objective_args=(ef.expected_returns,),
      weights_sum_to_one=False,
      constraints=constraints,
  )
```

--------------------------------

### Initialize PyPortfolioOpt for Short Positions

Source: https://pyportfolioopt.readthedocs.io/en/latest/UserGuide

This snippet shows how to initialize the `EfficientFrontier` object to allow for short selling by setting `weight_bounds` to a range that includes negative values (e.g., `(-1, 1)`). This enables the optimizer to assign negative weights to assets.

```python
ef = EfficientFrontier(mu, S, weight_bounds=(-1,1))
```

--------------------------------

### PyPortfolioOpt EfficientFrontier Class API Reference

Source: https://pyportfolioopt.readthedocs.io/en/latest/MeanVariance

Detailed API reference for the `EfficientFrontier` class, including its constructor, instance attributes, and key methods for portfolio optimization such as `min_volatility` and `max_sharpe`.

```APIDOC
class pypfopt.efficient_frontier.EfficientFrontier(expected_returns, cov_matrix, weight_bounds=(0, 1), solver=None, verbose=False, solver_options=None)
  Description: An EfficientFrontier object (inheriting from BaseConvexOptimizer) contains multiple optimization methods that can be called (corresponding to different objective functions) with various parameters. Note: a new EfficientFrontier object should be instantiated if you want to make any change to objectives/constraints/bounds/parameters.

  Instance variables:
    n_assets: int
    tickers: str list
    bounds: float tuple OR (float tuple) list
    cov_matrix: np.ndarray
    expected_returns: np.ndarray
    solver: str
    solver_options: {str: str} dict
    weights: np.ndarray (Output)

  Public methods summary:
    min_volatility(): optimizes for minimum volatility
    max_sharpe(): optimizes for maximal Sharpe ratio (a.k.a the tangency portfolio)
    max_quadratic_utility(): maximises the quadratic utility, given some risk aversion.
    efficient_risk(): maximises return for a given target risk
    efficient_return(): minimises risk for a given target return
    add_objective(): adds a (convex) objective to the optimization problem
    add_constraint(): adds a constraint to the optimization problem
    convex_objective(): solves for a generic convex objective with linear constraints
    portfolio_performance(): calculates the expected return, volatility and Sharpe ratio for the optimized portfolio.
    set_weights(): creates self.weights (np.ndarray) from a weights dict
    clean_weights(): rounds the weights and clips near-zeros.
    save_weights_to_file(): saves the weights to csv, json, or txt.

  __init__(expected_returns, cov_matrix, weight_bounds=(0, 1), solver=None, verbose=False, solver_options=None)
    Parameters:
      expected_returns (pd.Series, list, np.ndarray): expected returns for each asset. Can be None if optimising for volatility only (but not recommended).
      cov_matrix (pd.DataFrame or np.array): covariance of returns for each asset. This must be positive semidefinite, otherwise optimization will fail.
      weight_bounds (tuple OR tuple list, optional): minimum and maximum weight of each asset OR single min/max pair if all identical, defaults to (0, 1). Must be changed to (-1, 1) for portfolios with shorting.
      solver (str): name of solver. list available solvers with: cvxpy.installed_solvers()
      verbose (bool, optional): whether performance and debugging info should be printed, defaults to False
      solver_options (dict, optional): parameters for the given solver
    Raises:
      TypeError: if `expected_returns` is not a series, list or array
      TypeError: if `cov_matrix` is not a dataframe or array
    Note: As of v0.5.0, you can pass a collection (list or tuple) of (min, max) pairs representing different bounds for different assets.
    Tip: If you want to generate short-only portfolios, there is a quick hack. Multiply your expected returns by -1, then optimize a long-only portfolio.

  min_volatility()
    Description: Minimise volatility.
    Returns: asset weights for the volatility-minimising portfolio
    Return type: OrderedDict

  max_sharpe(risk_free_rate=0.02)
    Description: Maximise the Sharpe Ratio. The result is also referred to as the tangency portfolio, as it is the portfolio for which the capital market line is tangent to the efficient frontier. This is a convex optimization problem after making a certain variable substitution. See
```

--------------------------------

### PyPortfolioOpt Optimizer Class API Reference

Source: https://pyportfolioopt.readthedocs.io/en/latest/_modules/pypfopt/base_optimizer

Detailed API documentation for the `Optimizer` class in PyPortfolioOpt, including its constructor, methods for managing portfolio weights, mapping bounds to constraints, and checking parameter definitions. It also outlines helper methods for weight manipulation and saving.

```APIDOC
Optimizer Class Overview:
  - set_weights(): Creates self.weights (np.ndarray) from a weights dict.
  - clean_weights(): Rounds the weights and clips near-zeros.
  - save_weights_to_file(): Saves the weights to csv, json, or txt.

__init__(self, n_assets, tickers=None, weight_bounds=(0, 1), solver=None, verbose=False, solver_options=None):
  - Description: Initializes the Optimizer class with portfolio parameters and solver options.
  - Parameters:
    - n_assets: Number of assets in the portfolio.
    - tickers: List of asset tickers, optional.
    - weight_bounds: Minimum and maximum weight of each asset. Can be a single min/max pair (e.g., (0, 1)) if all identical, or a tuple list for individual asset bounds. Defaults to (0, 1). Must be changed to (-1, 1) for portfolios with shorting.
      - Type: tuple OR tuple list, optional
    - solver: Name of the solver to use. Available solvers can be listed with `cvxpy.installed_solvers()`.
      - Type: str, optional
    - verbose: Whether performance and debugging information should be printed. Defaults to False.
      - Type: bool, optional
    - solver_options: Dictionary of parameters for the chosen solver.
      - Type: dict, optional
  - Internal State:
    - _w: cvxpy.Variable representing asset weights.
    - _objective: Optimization objective.
    - _additional_objectives: List of additional objectives.
    - _constraints: List of optimization constraints.
    - _lower_bounds: Lower bounds for weights.
    - _upper_bounds: Upper bounds for weights.
    - _opt: Optimization problem instance.
    - _solver: Selected solver.
    - _verbose: Verbosity flag.
    - _solver_options: Solver options dictionary.

deepcopy(self):
  - Description: Returns a custom deep copy of the optimizer. This is necessary because cvxpy expressions do not support standard deepcopy, requiring manual copying of mutable arguments to prevent unintended side effects.
  - Returns: A deep copy of the optimizer instance.

_map_bounds_to_constraints(self, test_bounds):
  - Description: Converts input weight bounds into a format acceptable by cvxpy and adds them to the constraints list.
  - Parameters:
    - test_bounds: Minimum and maximum weight of each asset. Can be a single min/max pair, a list/tuple of tuples for individual asset bounds, or a pair of numpy arrays corresponding to lower/upper bounds. Defaults to (0, 1).
      - Type: tuple OR list/tuple of tuples OR pair of np.ndarray
  - Returns: Bounds suitable for cvxpy.
    - Type: tuple pair of np.ndarray
  - Raises:
    - TypeError: If `test_bounds` is not of the right type or format.

is_parameter_defined(self, parameter_name: str) -> bool:
  - Description: Checks if a given parameter name is defined within the optimizer's objectives or constraints.
  - Parameters:
    - parameter_name: The name of the parameter to check.
      - Type: str
  - Returns: True if the parameter is found, False otherwise.
    - Type: bool
```

--------------------------------

### Initialize Black-Litterman Model with Absolute Views in PyPortfolioOpt

Source: https://pyportfolioopt.readthedocs.io/en/latest/BlackLitterman

This snippet demonstrates how to initialize the `BlackLittermanModel` in PyPortfolioOpt by providing absolute views as a dictionary. This helper method simplifies the process for absolute views, allowing users to specify expected returns for individual assets directly. For relative views, the picking matrix must be constructed manually.

```python
from pypfopt.black_litterman import BlackLittermanModel

viewdict = {"AAPL": 0.20, "BBY": -0.30, "BAC": 0, "SBUX": -0.2, "T": 0.15}
bl = BlackLittermanModel(cov_matrix, absolute_views=viewdict)
```

--------------------------------

### PyPortfolioOpt Core Classes

Source: https://pyportfolioopt.readthedocs.io/en/latest/genindex

This entry lists fundamental classes within the PyPortfolioOpt library, including base optimizers and the Black-Litterman model, providing their full module paths for reference.

```APIDOC
pypfopt.base_optimizer.BaseConvexOptimizer (class)
pypfopt.base_optimizer.BaseOptimizer (class)
pypfopt.black_litterman.BlackLittermanModel (class)
```

--------------------------------

### PyPortfolioOpt EfficientCVaR Optimization and Utility Methods

Source: https://pyportfolioopt.readthedocs.io/en/latest/_modules/pypfopt/efficient_frontier/efficient_cvar

Provides documentation for key methods within the `EfficientCVaR` class, including `min_cvar` for minimizing portfolio CVaR, `set_weights` (which is not available), and internal validation for `beta`.

```APIDOC
min_cvar(self, market_neutral=False)
    - Minimises portfolio CVaR (see docs for further explanation).
    - Parameters:
        - market_neutral: whether the portfolio should be market neutral (weights sum to zero),
                          defaults to False. Requires negative lower weight bound.
                          Type: bool, optional
    - Returns: asset weights for the volatility-minimising portfolio
               Type: OrderedDict

set_weights(self, input_weights)
    - Method not available in EfficientCVaR.
    - Raises: NotImplementedError("Method not available in EfficientCVaR.")

_validate_beta(beta) (staticmethod)
    - Validates the beta parameter.
    - Parameters:
        - beta: The confidence level.
    - Raises: ValueError if beta is not between 0 and 1.
    - Warnings: UserWarning if beta <= 0.2, suggesting typical values are 80%, 90%, 95%.

min_volatility(self)
    - Not available, use min_cvar instead.
    - Raises: NotImplementedError("Please use min_cvar instead.")

max_sharpe(self, risk_free_rate=0.02)
    - Not available in EfficientCVaR.
    - Raises: NotImplementedError("Method not available in EfficientCVaR.")

max_quadratic_utility(self, risk_aversion=1, market_neutral=False)
    - Not available in EfficientCVaR.
    - Raises: NotImplementedError("Method not available in EfficientCVaR.")
```

--------------------------------

### PyPortfolioOpt EfficientCDaR Class Methods for Portfolio Optimization

Source: https://pyportfolioopt.readthedocs.io/en/latest/GeneralEfficientFrontier

Comprehensive documentation for the core methods of the `EfficientCDaR` class in PyPortfolioOpt, covering portfolio CDaR minimization, performance calculation, and weight setting utilities.

```APIDOC
min_cdar(market_neutral=False)
  Minimise portfolio CDaR.
  Parameters:
    market_neutral: bool, optional
      Whether the portfolio should be market neutral (weights sum to zero), defaults to False. Requires negative lower weight bound.
  Returns:
    asset weights for the volatility-minimising portfolio (OrderedDict)

portfolio_performance(verbose=False)
  Calculate (and optionally print) the performance of the optimal portfolio: expected return, CDaR.
  Parameters:
    verbose: bool, optional
      Whether performance should be printed, defaults to False.
  Raises:
    ValueError: if weights have not been calculated yet.
  Returns:
    expected return, CDaR (float, float)

set_weights(input_weights)
  Utility function to set weights attribute (np.array) from user input.
  Parameters:
    input_weights: dict
      {ticker: weight} dict.
```
Tokens:
Raw