book
Checkout our new book! Hands on AI Trading with Python, QuantConnect, and AWS Learn More arrow

Portfolio

Key Concepts

Introduction

The portfolio object provides information about the investment state and history of all of the securities that have been in the algorithm during its lifetime.

The portfolio property of the QCAlgorithm class is a dictionary where the keys are Symbol objects and the values are SecurityHolding objects. The SecurityHolding object provides information about the investment state and history of a security.

Investment Status

To get the investment status of your strategy, access the invested property of a portfolio object.

Select Language:
# Get the investment status and return True if the portfolio is invested.
invested = self.portfolio.invested

Holdings Status

You can identify a position as long- or short-biased based on the sign of the holding quantity. Long positions have a positive quantity and short positions have a negative quantity. The SecurityHolding object has the following properties to describe the holding status.

Select Language:
# Create a SecurityHolding object.
holdings = self.portfolio[self._symbol]
# Check the holding quantity of the security.
quantity = holdings.quantity
# Check the investing status of the security.
invested = holdings.invested
# Check if the strategy is long or short the security.
is_long = holdings.is_long
is_short = holdings.is_short

The quantity can be lower than the minimum order size. If the quantity is less than the lot size of the asset, the invested property is False.

Buying Power

To get the maximum buying power in your account currency you can use for a given Symbol and order direction, call the get_buying_power method.

Select Language:
# Check the total amount of buying power available. Margin available varies by order direction and current holdings.
available_buying_power = self.portfolio.get_buying_power(self._symbol, OrderDirection.BUY)

For more information about buying power, see Buying Power.

Cost Averaging Accounting

LEAN uses the cost averaging accounting method, which determines the cost of your holdings by taking a weighted average of all your purchase prices. For example, say you place the following buy orders:

  1. Buy 10 ABC @ $10
  2. Buy 5 ABC @ $11
  3. Buy 20 ABC @ $14
  4. Buy 3 ABC @ $9

In the preceding example, the average cost of your ABC position is (10*10 + 5*11 + 20*14 + 3*9) / (10 + 5 + 20 + 3) = 12.1579/share. In contrast, if you use the first-in, first-out (FIFO) accounting method, the cost of the first 10 shares is 10/share, not 12.1579/share.

To get the cost of your security holdings, use the holdings_cost property of the SecurityHolding object. If you fill buy and sell orders, the holdings cost is the product of the holding quantity and the average price. For example, the following table shows how the average price and holdings cost changes with each buy and sell order order in a long position:

Order QuantityFill Price ($)Holding QuantityAverage Price ($)Holdings Cost ($)
2102(2 * 10) / 2 = 102 * 10 = 20
-1111(1 * 10) / 1 = 101 * 10 = 10
1122(1 * 10 + 1 * 12) / 2 = 11
2 * 11 = 22
-21300
0 * 0 = 0

The following table shows how the average price and holdings cost changes with each buy and sell order order in a short position:

Order QuantityFill Price ($)Holding QuantityAverage Price ($)Holdings Cost ($)
-210-2(-2 * 10) / -2 = 10-2 * 10 = -20
111-1(-1 * 10) / -1 = 10-1 * 10 = -10
-112-2(-1 * 10 + (-1) * 12) / -2 = 11
-2 * 11 = -22
213000 * 0 = 0

Note that when you decrease the position size without closing the trade, the average price doesn't change because the denominator and the coefficients in the numerator of its formula are scaled by the quotient of the current holding quantity and the previous holding quantity. For instance, if the last row in the preceding table had an order quantity 1, the holding quantity would be -1 and the average price would be

(1q)10+(1q)122q =(112)10+(112)12212 =1210+12121 =561=11

Performance Statistics

The portfolio object has a collection of properties that provide the combined state of holdings and the cashbook.

Select Language:
# Access key statistics of the portfolio using the properties of the portfolio object.
value = self.portfolio.total_portfolio_value
total_margin_used = self.portfolio.total_margin_used
margin_remaining = self.portfolio.margin_remaining
total_net_profit = self.portfolio.total_net_profit
total_unrealised_profit = self.portfolio.total_unrealised_profit
total_fees = self.portfolio.total_fees
cash = self.portfolio.cash

Properties

The portfolio object has the following properties:

Examples

The following examples demonstrate common practices for handling the portfolio.

Example 1: Martingale

The following algorithm trades a Martingale strategy on AAPL. The trend indicated by an EMA indicator follows the trend with a 1persharestoplossanda2 take-profit level. Yet, if the last trade is lost, it will double the next trading size to recover the last loss.

Select Language:
class PortfolioExampleAlgorithm(QCAlgorithm):
    def initialize(self) -> None:
        self.set_start_date(2024, 1, 1)
        self.set_end_date(2024, 1, 31)
        
        # Request AAPL's data to trade.
        self.aapl = self.add_equity("AAPL").symbol

        # Create an EMA indicator to generate trading data.
        self._ema = self.ema(self.aapl, 20, Resolution.DAILY)
        # Warm up the indicator to provide an immediate trade signal.
        self.warm_up_indicator(self.aapl, self._ema, Resolution.DAILY)

        self.next_quantity = 1

    def on_data(self, slice: Slice) -> None:
        # Ride on the AAPL trend indicated by the EMA indicator.
        if not self.portfolio.invested:
            if self.securities[self.aapl].price >= self._ema.current.value:
                self.market_order(self.aapl, self.next_quantity)
            else:
                self.market_order(self.aapl, -self.next_quantity)
        else:
            holding = self.portfolio[self.aapl]
            # Stop loss at $1 per share.
            if holding.unrealized_profit <= -1 * self.next_quantity:
                self.liquidate(self.aapl)
                # Double the next quantity to recover this loss.
                self.next_quantity *= 2
            # Take profit at $2 per share.
            elif holding.unrealized_profit >= 2:
                self.liquidate(self.aapl)
                self.next_quantity = 1

You can also see our Videos. You can also get in touch with us via Discord.

Did you find this page helpful?

Contribute to the documentation: