docs: update docstrings

Author: chilango74

main_notebook.ipynb

@@ -7,8 +7,8 @@
      "is_executing": true
     },
     "ExecuteTime": {
-     "end_time": "2025-06-24T10:47:59.358922Z",
-     "start_time": "2025-06-24T10:47:56.923050Z"
+     "end_time": "2025-06-24T13:40:48.620923Z",
+     "start_time": "2025-06-24T13:40:46.884104Z"
     }
    },
    "source": [
@@ -35,7 +35,7 @@
     "%autoreload 2"
    ],
    "outputs": [],
-   "execution_count": 3
+   "execution_count": 1
   },
   {
    "cell_type": "code",
@@ -45,8 +45,8 @@
      "outputs_hidden": false
     },
     "ExecuteTime": {
-     "end_time": "2025-06-20T05:36:19.175809Z",
-     "start_time": "2025-06-20T05:36:19.105040Z"
+     "end_time": "2025-06-24T13:40:51.143568Z",
+     "start_time": "2025-06-24T13:40:50.317414Z"
     }
    },
    "source": [
@@ -59,12 +59,12 @@
        "'1.4.4'"
       ]
      },
-     "execution_count": 3,
+     "execution_count": 2,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
-   "execution_count": 3
+   "execution_count": 2
   },
   {
    "metadata": {},
@@ -1776,8 +1776,8 @@
   {
    "metadata": {
     "ExecuteTime": {
-     "end_time": "2025-06-19T04:37:29.958Z",
-     "start_time": "2025-06-19T04:37:29.892941Z"
+     "end_time": "2025-06-24T13:40:59.950652Z",
+     "start_time": "2025-06-24T13:40:59.904179Z"
     }
    },
    "cell_type": "code",
@@ -1787,13 +1787,13 @@
     "assets2 = ['SPY.US', 'AGG.US', 'GC.COMM']"
    ],
    "outputs": [],
-   "execution_count": 6
+   "execution_count": 3
   },
   {
    "metadata": {
     "ExecuteTime": {
-     "end_time": "2025-06-19T04:37:30.844845Z",
-     "start_time": "2025-06-19T04:37:30.773261Z"
+     "end_time": "2025-06-24T13:41:02.307322Z",
+     "start_time": "2025-06-24T13:41:02.265496Z"
     }
    },
    "cell_type": "code",
@@ -1805,12 +1805,12 @@
        "['SPY.US', 'AGG.US', 'GC.COMM']"
       ]
      },
-     "execution_count": 7,
+     "execution_count": 4,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
-   "execution_count": 7
+   "execution_count": 4
   },
   {
    "cell_type": "code",
@@ -1820,8 +1820,8 @@
      "outputs_hidden": false
     },
     "ExecuteTime": {
-     "end_time": "2025-06-19T04:38:08.998330Z",
-     "start_time": "2025-06-19T04:38:06.774005Z"
+     "end_time": "2025-06-24T13:41:16.286421Z",
+     "start_time": "2025-06-24T13:41:14.199455Z"
     }
    },
    "source": [
@@ -1832,7 +1832,7 @@
     "    ccy=\"USD\",\n",
     "    weights=weights,\n",
     "    inflation=True,\n",
-    "    symbol=\"retirement_pf.PF\",\n",
+    "    # symbol=\"retirement_pf.PF\",\n",
     "    rebalancing_strategy=ok.Rebalance(period=\"year\"),\n",
     ")\n",
     "print(pf)"
@@ -1842,7 +1842,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "symbol                                retirement_pf.PF\n",
+      "symbol                               portfolio_7354.PF\n",
       "assets                       [SPY.US, AGG.US, GC.COMM]\n",
       "weights                              [0.3, 0.55, 0.15]\n",
       "rebalancing_period                                year\n",
@@ -1857,7 +1857,7 @@
      ]
     }
    ],
-   "execution_count": 9
+   "execution_count": 6
   },
   {
    "metadata": {

okama/common/helpers/rebalancing.py

@@ -39,18 +39,22 @@ class Rebalance:
     Attributes
     ----------
     period : {'none', 'month', 'quarter', 'half-year', 'year'}
-        The rebalancing period for the investment portfolio.
+        rebalancing period (rebalancing frequency) is predetermined time intervals when
+        the investor rebalances the portfolio.
+        If 'none' assets weights are not rebalanced.
 
     abs_deviation : float, optional
         The absolute deviation allowed for the assets weights in the portfolio.
         It is defined for an asset weight as an absolut value of: actual_weight - target_weight.
         It must be more than 0 (0%).
         Max value is 1 (100%).
+        if None the parameter is ignored.
 
     rel_deviation : float, optional
         The relative deviation allowed for the assets weights in the portfolio.
         It is defined for an asset weight as an absolut value of: actual_weight / target_weight - 1.
         it must be positive.
+        if None the parameter is ignored.
     """
 
     def __init__(

okama/frontier/multi_period.py

@@ -56,10 +56,12 @@ class EfficientFrontierReb(asset_list.AssetList):
         Including inflation could limit available data (last_date, first_date)
         as the inflation data is usually published with a one-month delay.
 
-    rebalancing_period : {'year', 'none'}, default 'year'
-        Rebalancing period of the portfolios in the multi-period Efficient Frontier.
-        Portfolio is rebalanced every year if rebalancing_period='year'.
-        Portfolio is not rebalanced if rebalancing_period='none'
+    rebalancing_strategy : Rebalance, default Rebalance(period='year', abs_deviation=None, rel_deviation=None)
+        Rebalancing strategy for an investment portfolio. The rebalancing strategy si defined by:
+        -period (rebalancing frequency): predetermined time intervals when the investor rebalances the portfolio.
+        If 'none' assets weights are not rebalanced.
+        -abs_deviation: the absolute deviation allowed for the assets weights in the portfolio.
+        -rel_deviation: the relative deviation allowed for the assets weights in the portfolio.
 
     n_points : int, default 20
         Number of points in the Efficient Frontier.
@@ -977,9 +979,14 @@ def get_monte_carlo(self, n: int = 100) -> pd.DataFrame:
         """
         weights_df = helpers.Float.get_random_weights(n, self.assets_ror.shape[1], self.bounds)
 
+        args = dict(
+            period=self.rebalancing_strategy.period,
+            abs_deviation=self.rebalancing_strategy.abs_deviation,
+            rel_deviation=self.rebalancing_strategy.rel_deviation
+        )
         # Portfolio risk and cagr for each set of weights
         portfolios_ror = weights_df.aggregate(
-            Rebalance(period=self.rebalancing_period).return_ror_ts,
+            Rebalance(**args).return_ror_ts,
             ror=self.assets_ror,
         )
         random_portfolios = pd.DataFrame()

okama/portfolio.py

@@ -60,14 +60,17 @@ class Portfolio(make_asset_list.ListMaker):
         The weight of an asset is the percent of an investment portfolio that corresponds to the asset.
         If weights = None an equally weighted portfolio is created (all weights are equal).
 
-    rebalancing_strategy : {'none', 'month', 'quarter', 'half-year', 'year'}, default 'month'
-        Rebalancing period (rebalancing frequency) is predetermined time intervals when
-        the investor rebalances the portfolio. If 'none' assets weights are not rebalanced.
-
-    symbol : str, default None
+    rebalancing_strategy : Rebalance, default Rebalance(period='year', abs_deviation=None, rel_deviation=None)
+        Rebalancing strategy for an investment portfolio. The rebalancing strategy si defined by:
+        -period (rebalancing frequency): predetermined time intervals when the investor rebalances the portfolio.
+        If 'none' assets weights are not rebalanced.
+        -abs_deviation: the absolute deviation allowed for the assets weights in the portfolio.
+        -rel_deviation: the relative deviation allowed for the assets weights in the portfolio.
+
+    symbol : str
         Text symbol of portfolio. It is similar to tickers but have a namespace information.
         Portfolio symbol must end with .PF (all_weather_portfolio.PF).
-        If None a random symbol is generated (portfolio_7802.PF).
+        If not defined a random symbol is generated (portfolio_7802.PF).
     """
 
     def __init__(
@@ -80,7 +83,7 @@ def __init__(
         inflation: bool = True,
         weights: Optional[List[float]] = None,
         rebalancing_strategy: Rebalance = Rebalance(period="month"),
-        symbol: str = None,
+        symbol: str,
     ):
         super().__init__(
             assets,
@@ -3088,7 +3091,6 @@ def find_the_largest_withdrawals_size(
         ...    target_survival_period=25
         ...)
         >>> res
-        # TODO: update example results
         success                True
         withdrawal_abs   -917.96875
         withdrawal_rel     0.091797