Package: compass-investor
Leading investors to theirs targets.CompassCompass is a command-line interface that is designed for managing investiment portfolios. More specifically, Compass helps investors doing the following tasks:Portfolio spreadsheet setupDepositWithdrawRebalancing(with cash flows, sells/buys and tracking error)Grouping assetsInstallationRequirements:Python3.8 or greaterWith Python installed, run the command as follows:pipinstall--upgradecompass-investorBasic usagePortfolio spreadsheet setupSuppose you want to start a 60/40 portfolio, you would type the command as follows:compassinitObserve the outputs generated by the command above:portfolio.xlsx: The porfolio spreadsheet with fictitious tickers. Please, replace its content with you own portfolio. The column layout is as follows:Name: str, description of the ticker, e.g., iShares Core S&P 500 ETF.Ticker: str, ticker name, e.g., IVV.Target: float, target percentage for the ticker, e.g., 40%.Actual: int, number of owned units of the ticker, e.g., 500.Price: float, current price of the ticker, e.g., $100.Group: str, optional, group of the ticker, e.g., Stocks.Additional columns in the spreadsheet are ignored.compass.ini: The configuration with an disabled example. Please, replace its content with your own configuration, and remove the character '#' to activate it.DepositNow, suppose you want to deposit $1000, you wouldupdate the column Priceof the portfolio spreadsheet with current prices, close the spreadsheet, and type the command as follows:compasschange1000Observe the output generated by the command above:Console output: The transaction values (deposit/withdraw and expenses); and the portfolio added with the columns Change, Before and After.Change corresponds to the amount of units you should buy of each ticker to match the deposit value, $1000.Before corresponds to the portfolio allocation before the deposit.After corresponds to the portfolio allocation after the deposit.output.xlsx: A spreadsheet with the same table showed in the console output.After buying the units of the tickers, you should open the portfolio spreadsheet,update the column Actualwith the final amount of units of each ticker, and close the spreadsheet.WithdrawNow, suppose you want to withdraw $1000, you would do the same steps done for a deposit, but with negative values. With that said, the command should be as follows:compasschange-1000And the output generated by the command above are expected to shownegativevalues in the column Change, corresponding to the amount of units you shouldsellof each ticker to match thewithdrawvalue, $1000.Advanced usageRebalancingCompass always uses deposits/withdraws (cash flows) to move the portfolio allocation towards the target. However, when the portfolio is relatively big, the cash flow might not be enough to keep the portfolio allocation close to the target. In that case, the investor might deliberately buy and sell assets to rebalance the portfolio.Suppose you want to deposit $1000 while rebalancing your portfolio, you would type the command as follows:compasschange1000--rebalance=TrueIn the output, the column Change is expected to show positive and negative values, corresponding to, respectively, buys and sells to move the portfolio allocation towards the target.Now, suppose you want to do the same deposit and rebalancing with no tracking error, you would type the command as follows:compasschange1000--rebalance=True--absolute-distance=0--relative-distance=0Getting prices automaticallyIf you prefer to get prices automatically instead of typing, you might manage your portfolio on an online spreadsheet app that provides asset prices. The additional complexity is that you will have to download a copy of the porfolio spreasheet to your local disk right before running Compass. The steps are as follows:Just once:Import the portfolio spreasheet to the online spreadsheet app of your choice;Replace the values in column Price with formulas to get the asset prices automatically.Right before running Compass:Download the spreadsheet to the local directory in which you have done the portfolio setup;Run Compass in the same directory.Google SheetsGoogle Sheets offers the functionGoogleFinance. Please visit Googhe Sheetsdocumentationto get more information.Grouping assetsGrouping is a handy feature of Compass, but it is hard to understand it without real examples. So, let's appreciate two common use cases that could get value from grouping assets.Risk managementSuppose you want to invest on two ETFs, one for US stocks and another for international stocks, your spreadsheet portfolio would be as follows:NameTickerPriceActualTargetGroupTotal market USTUS100.005050%InternacionalINT100.005050%At some point in time, you decide to overweight US value stocks by adding a new asset to your portfolio. In addition, due to risk management, you want the overall US allocation be limited to 50%. The changes required in the spreadsheet portfolio are as follows:Add a line for VUS;Fill the columns Name, Ticker, Price and Actual;In the column Target, set both VUS and TUS' allocations to 25%;In the column Group, add both VUS and TUS to the group US.NameTickerPriceActualTargetGroupValue USVUS100.00025%USTotal market USTUS100.002525%USInternacionalINT100.005050%Deprecated assetSuppose that company A offers the ETFs AUS and AIN, on which you invest paying an expense ratio of 0.03%, your spreadsheet portfolio would be as follows:NameTickerPriceActualTargetGroupA USAUS100.001010%A InternacionalAIN100.009090%At some point in time, the competitor B launches the ETF BUS, with the same characteristics, but with an expense ratio of 0.02%. Would you sell all units you have from AUS to buy from BUS? Maybe that will not be necessary, since company A might lower the expense ratio of AUS to 0.02% in response to the launch of BUS. The best option seems to be start buying BUS, and keeping AUS for a while. The changes required in the spreadsheet portfolio are as follows:Add a line for BUS;Fill the columns Name, Ticker, Price and Actual;In the column Target, move the allocation of 10% from AUS to BUS;In the column Group, add both BUS and AUS to the group US.NameTickerPriceActualTargetGroupB USBUS100.00010%USA USAUS100.00100%USA InternacionalAIN100.009090%With that setting, Compass will handle AUS as a deprecated asset. That means that its actual allocation is considered as part of the group allocation when depositing or withdrawing from the portfolio. However, its target allocation is not considered when rebalancing inside the group, since all units would be selled to match the target allocation of 0%. It is up to the investor to decide whether and when to replace the deprecated asset based on changes in the expense ratios of the alternatives.ContributingCompass is free to use, and maintained by volunteers. If you wish to contribute, these are the main options::star:Startheproject repositoryto show people that it is useful;:eyes:Watchtheproject repositoryto be informed about new releases;:monocle_face: Share theproject home pagewith someone that could benefit from it;:handshake: Help and get help onQ&A discussions;:bulb: Share ideas and give feedback onIdeas discussions;:lady_beetle: Report bugs onIssues;:technologist: Fix issues following theDeveloper Guide.