Add cumulative and calendar returns

Author: shawnlinxl

pyform/__init__.py

@@ -1,5 +1,9 @@
+# flake8: noqa
+
 # Versioneer
 from ._version import get_versions
 
 __version__ = get_versions()["version"]
 del get_versions
+
+from pyform.returnseries import ReturnSeries, CashSeries

pyform/analysis/__init__.py

@@ -0,0 +1,3 @@
+# flake8: noqa
+
+from pyform.analysis.returns import table_calendar_return

pyform/analysis/returns.py

@@ -0,0 +1,43 @@
+import calendar
+import pandas as pd
+from pyform import ReturnSeries
+
+
+def table_calendar_return(
+    return_series: ReturnSeries, use_month_abbr: bool = True
+) -> pd.DataFrame:
+    """Create calendar like monthly return table
+
+    Args:
+        return_series: A return series. Should be of minimum monthly frequency
+        use_month_abbr: Whether to use 3 letter month abbreviations instead of numerical
+          month. Defaults to True.
+
+    Returns:
+        pd.DataFrame: DataFrame with columns: Year, Jan, Feb, ..., Dec, Total
+    """
+
+    # create monthly and annual returns for output rows
+    monthly = return_series.to_month()
+    annual = return_series.to_year()
+
+    # append necessary information
+    monthly["Year"] = monthly.index.year
+    monthly["Month"] = monthly.index.month
+    monthly["Month"] = monthly["Month"]
+    annual["Year"] = annual.index.year
+
+    # Pivot monthly data
+    monthly = monthly.pivot(index="Year", columns="Month", values=monthly.columns[0])
+
+    # Rename annual column, and merge with monthly
+    annual = annual.rename(columns={annual.columns[0]: "Total"})
+
+    output = monthly.merge(annual, how="left", on="Year")
+
+    if use_month_abbr:
+        months = [*range(1, 13)]
+        month_abbr_map = {month: calendar.month_abbr[month] for month in months}
+        output = output.rename(columns=month_abbr_map)
+
+    return output

pyform/returns/compound.py

@@ -24,7 +24,7 @@ def compound_arithmetic(returns: pd.Series) -> float:
     """Performs arithmatic compounding.
 
     e.g. if there are 3 returns r1, r2, r3,
-    calculate ``r1 + r2`` + r3
+    calculate r1 + r2 + r3
 
     Args:
         returns: pandas series of returns, in decimals.
@@ -41,7 +41,7 @@ def compound_continuous(returns: pd.Series) -> float:
     """Performs continuous compounding.
 
     e.g. if there are 3 returns r1, r2, r3,
-    calculate exp(``r1 + r2`` + r3) - 1
+    calculate exp(r1 + r2 + r3) - 1
 
     Args:
         returns: pandas series of returns, in decimals.
@@ -60,9 +60,9 @@ def compound(method: str) -> Callable:
     Args:
         method: method of compounding in the generated function
 
-                * 'geometric': geometric compounding ``(1+r1) * (1+r2) - 1``
-                * 'arithmetic': arithmetic compounding ``r1 + r2``
-                * 'continuous': continous compounding ``exp(r1+r2) - 1``
+            * 'geometric': geometric compounding ``(1+r1) * (1+r2) - 1``
+            * 'arithmetic': arithmetic compounding ``r1 + r2``
+            * 'continuous': continous compounding ``exp(r1+r2) - 1``
 
     Raises:
         ValueError: when method is not supported.
@@ -86,6 +86,99 @@ def compound(method: str) -> Callable:
     return compound[method]
 
 
+def cumseries_geometric(returns: pd.Series) -> pd.Series:
+    """Performs geometric compounding to create cumulative index series.
+
+    e.g. if there are 3 returns r1, r2, r3,
+    calculate
+        (1+r1) - 1,
+        (1+r1) * (1+r2) - 1,
+        (1+r1) * (1+r2) * (1+r3) - 1
+
+    Args:
+        returns: pandas series of returns, in decimals.
+            i.e. 3% should be expressed as 0.03, not 3.
+
+    Returns:
+        returns: pandas series of cumulative index, in decimals.
+    """
+
+    return (1 + returns).cumprod() - 1
+
+
+def cumseries_arithmetic(returns: pd.Series) -> pd.Series:
+    """Performs arithmatic compounding to create cumulative index series.
+
+    e.g. if there are 3 returns r1, r2, r3,
+    calculate
+        r1
+        r1 + r2
+        r1 + r2 + r3
+
+    Args:
+        returns: pandas series of returns, in decimals.
+            i.e. 3% should be expressed as 0.03, not 3.
+
+    Returns:
+        returns: pandas series of cumulative index, in decimals.
+    """
+
+    return returns.cumsum()
+
+
+def cumseries_continuous(returns: pd.Series) -> float:
+    """Performs continuous compounding to create cumulative index series.
+
+    e.g. if there are 3 returns r1, r2, r3,
+    calculate
+        exp(r1) - 1
+        exp(r1 + r2) - 1
+        exp(r1 + r2 + r3) - 1
+
+    Args:
+        returns: pandas series of returns, in decimals.
+            i.e. 3% should be expressed as 0.03, not 3.
+
+    Returns:
+        returns: pandas series of cumulative index, in decimals.
+    """
+
+    return returns.cumsum().apply(lambda x: math.exp(x) - 1)
+
+
+def cumseries(method: str) -> Callable:
+    """Factory for producing compound functions.
+
+    Args:
+        method: method of compounding in the generated function
+
+            * 'geometric': geometric compounding
+            * 'arithmetic': arithmetic compounding
+            * 'continuous': continous compounding
+
+    Raises:
+        ValueError: when method is not supported.
+
+    Returns:
+        Callable: a function that takes a pandas series as its argument, and
+            compound it to create a cumulative index sereis according to the
+            method specified.
+    """
+
+    if method not in ["arithmetic", "geometric", "continuous"]:
+        raise ValueError(
+            "Method should be one of 'geometric', 'arithmetic' or 'continuous'"
+        )
+
+    cumseries = {
+        "arithmetic": cumseries_arithmetic,
+        "geometric": cumseries_geometric,
+        "continuous": cumseries_continuous,
+    }
+
+    return cumseries[method]
+
+
 def ret_to_period(df: pd.DataFrame, freq: str, method: str):
     """Converts return series to a different (and lower) frequency.
 

pyform/returnseries.py

@@ -6,7 +6,7 @@
 import pandas as pd
 from typing import Optional, Union, Dict
 from pyform.timeseries import TimeSeries
-from pyform.returns.compound import compound, ret_to_period
+from pyform.returns.compound import compound, ret_to_period, cumseries
 from pyform.returns.metrics import calc_ann_vol, calc_ann_ret
 from pyform.util.freq import is_lower_freq, calc_samples_per_year
 
@@ -354,6 +354,41 @@ def get_tot_ret(
 
         return result
 
+    def get_index_series(
+        self,
+        freq: Optional[str] = "M",
+        method: Optional[str] = "geometric",
+        include_bm: Optional[bool] = True,
+    ) -> Dict[str, pd.DataFrame]:
+
+        # Store result in dictionary
+        result = dict()
+
+        run_name, run_data = [self.name], [self]
+
+        if include_bm:
+            run_name += list(self.benchmark.keys())
+            run_data += list(self.benchmark.values())
+
+        for name, series in zip(run_name, run_data):
+
+            # keep record of start and so they can be reset later
+            series_start, series_end = series.start, series.end
+
+            # modify series so it's in the same timerange as the main series
+            self.align_daterange(series)
+
+            # compute rolling annualized volatility
+            ret = series.to_period(freq=freq, method=method)
+
+            # store result in dictionary
+            result[name] = ret.apply(cumseries(method))
+
+            # reset series date range
+            series.set_daterange(series_start, series_end)
+
+        return result
+
     def get_ann_ret(
         self,
         method: Optional[str] = "geometric",

tests/unit/analysis/test_returns.py

@@ -0,0 +1,30 @@
+from pyform.analysis import table_calendar_return
+from pyform import ReturnSeries
+
+returns = ReturnSeries.read_csv("tests/unit/data/twitter_returns.csv")
+
+
+def test_calendar_return():
+
+    calendar_return = table_calendar_return(returns)
+    assert (
+        calendar_return.columns
+        == [
+            "Year",
+            "Jan",
+            "Feb",
+            "Mar",
+            "Apr",
+            "May",
+            "Jun",
+            "Jul",
+            "Aug",
+            "Sep",
+            "Oct",
+            "Nov",
+            "Dec",
+            "Total",
+        ]
+    ).all()
+
+    assert calendar_return.iloc[0, 0] == 2013

tests/unit/returns/test_compound.py

@@ -5,6 +5,10 @@
     compound_arithmetic,
     compound_continuous,
     compound,
+    cumseries_geometric,
+    cumseries_arithmetic,
+    cumseries_continuous,
+    cumseries,
 )
 
 
@@ -27,3 +31,24 @@ def test_compound_methods():
     assert compound_geometric(returns) == 0.055942142480424284
     assert compound_arithmetic(returns) == 0.05658200000000001
     assert compound_continuous(returns) == 0.05821338474015869
+
+
+def test_cumseries():
+
+    assert cumseries("geometric") == cumseries_geometric
+    assert cumseries("arithmetic") == cumseries_arithmetic
+    assert cumseries("continuous") == cumseries_continuous
+
+    with pytest.raises(ValueError):
+        cumseries("contnuuous")  # typo in continuous should cause failure
+
+
+def test_cumseries_methods():
+
+    returns = pd.Series(
+        [0.030011999999999997, -0.02331, 0.016706000000000002, 0.049061, -0.015887]
+    )
+
+    assert cumseries_geometric(returns).iloc[-1] == 0.055942142480424284
+    assert cumseries_arithmetic(returns).iloc[-1] == 0.05658200000000001
+    assert cumseries_continuous(returns).iloc[-1] == 0.05821338474015869

tests/unit/test_returnseries.py

@@ -1,7 +1,7 @@
 import datetime
 import pytest
 import pandas as pd
-from pyform.returnseries import ReturnSeries, CashSeries
+from pyform import ReturnSeries, CashSeries
 
 returns = ReturnSeries.read_csv("tests/unit/data/twitter_returns.csv")
 spy = ReturnSeries.read_csv("tests/unit/data/spy_returns.csv")
@@ -434,6 +434,38 @@ def test_rolling_ann_vol():
     assert roll_spy["SPY"][0] == 0.10810183559733508
 
 
+def test_index_series():
+
+    returns = ReturnSeries.read_csv("tests/unit/data/twitter_returns.csv")
+
+    # No benchmark
+    index_series = returns.get_index_series()
+    index_twitter = index_series["TWTR"]
+    assert index_twitter.index[-1] == datetime.datetime.strptime(
+        "2020-06-30", "%Y-%m-%d"
+    )
+    assert index_twitter["TWTR"][-1] == -0.35300922502128296
+
+    # Daily
+    index_series = returns.get_index_series(freq="D")
+    index_twitter = index_series["TWTR"]
+    assert index_twitter.index[-1] == datetime.datetime.strptime(
+        "2020-06-26", "%Y-%m-%d"
+    )
+    assert index_twitter["TWTR"][-1] == -0.35300922502128473
+
+    returns.add_bm(spy)
+    index_series = returns.get_index_series()
+    index_twitter = index_series["TWTR"]
+    index_spy = index_series["SPY"]
+    assert index_twitter.index[-1] == datetime.datetime.strptime(
+        "2020-06-30", "%Y-%m-%d"
+    )
+    assert index_spy.index[-1] == datetime.datetime.strptime("2020-06-30", "%Y-%m-%d")
+    assert index_twitter["TWTR"][-1] == -0.35300922502128296
+    assert index_spy["SPY"][-1] == 0.6935467657365093
+
+
 def test_rolling_ann_return():
 
     returns = ReturnSeries.read_csv("tests/unit/data/twitter_returns.csv")