MAINT: redesign buyback auth datasets and factor

zipline/pipeline/common.py

@@ -8,6 +8,7 @@ CASH_FIELD_NAME = 'cash'
 CASH_AMOUNT_FIELD_NAME = 'cash_amount'
 COUNT_FIELD_NAME = 'count'
 BUYBACK_ANNOUNCEMENT_FIELD_NAME = 'buyback_date'
+BUYBACK_TYPE_FIELD_NAME = 'buyback_type'
 DAYS_SINCE_PREV = 'days_since_prev'
 DAYS_SINCE_PREV_DISCLOSURE = 'days_since_prev_disclosure'
 DAYS_SINCE_PREV_DIVIDEND_ANNOUNCEMENT = 'days_since_prev_dividend_announcement'
@@ -44,6 +45,9 @@ PREVIOUS_BUYBACK_CASH = 'previous_buyback_cash'
 PREVIOUS_BUYBACK_SHARE_COUNT = 'previous_buyback_share_count'
 PREVIOUS_DISCLOSURE_DATE = 'previous_disclosure_date'
 PREVIOUS_COUNT = 'previous_count'
+PREVIOUS_BUYBACK_TYPE = 'previous_buyback_type'
+PREVIOUS_VALUE = 'previous_value'
+PREVIOUS_VALUE_TYPE = 'previous_value_type'
 PREVIOUS_EX_DATE = 'previous_ex_date'
 PREVIOUS_NUM_SHARES = 'previous_number_shares'
 PREVIOUS_FISCAL_QUARTER = 'previous_fiscal_quarter'
@@ -60,3 +64,5 @@ SHARE_COUNT_FIELD_NAME = 'share_count'
 SID_FIELD_NAME = 'sid'
 STANDARD_DEVIATION_FIELD_NAME = 'standard_deviation'
 TS_FIELD_NAME = 'timestamp'
+VALUE_FIELD_NAME = 'value'
+VALUE_TYPE_FIELD_NAME = 'value_type'

zipline/pipeline/data/__init__.py

@@ -1,5 +1,5 @@
 from ._13d_filings import _13DFilings
-from .buyback_auth import CashBuybackAuthorizations, ShareBuybackAuthorizations
+from .buyback_auth import BuybackAuthorizations
 from .dividends import (
     DividendsByAnnouncementDate,
     DividendsByExDate,
@@ -13,14 +13,13 @@ from .dataset import DataSet, Column, BoundColumn
 __all__ = [
     '_13DFilings',
     'BoundColumn',
-    'CashBuybackAuthorizations',
+    'BuybackAuthorizations',
     'Column',
     'DataSet',
     'DividendsByAnnouncementDate',
     'DividendsByExDate',
     'DividendsByPayDate',
     'EarningsCalendar',
-    'ConsensusEstimates',
-    'ShareBuybackAuthorizations',
+	'ConsensusEstimates',
     'USEquityPricing',
 ]

zipline/pipeline/data/buyback_auth.py

@@ -6,19 +6,12 @@ from zipline.utils.numpy_utils import datetime64ns_dtype, float64_dtype
 from .dataset import Column, DataSet
 
 
-class CashBuybackAuthorizations(DataSet):
+class BuybackAuthorizations(DataSet):
     """
     Dataset representing dates of recently announced cash buyback
     authorizations.
     """
-    cash_amount = Column(float64_dtype)
-    announcement_date = Column(datetime64ns_dtype)
-
-
-class ShareBuybackAuthorizations(DataSet):
-    """
-    Dataset representing dates of recently announced share buyback
-    authorizations.
-    """
-    share_count = Column(float64_dtype)
-    announcement_date = Column(datetime64ns_dtype)
+    previous_value = Column(float64_dtype)
+    previous_date = Column(datetime64ns_dtype)
+    previous_value_type = Column(float64_dtype) # TODO: should be string
+    previous_buyback_type = Column(float64_dtype) # TODO: should be string

zipline/pipeline/factors/events.py

@@ -5,8 +5,7 @@ announcements, acquisitions, dividends, etc.).
 from numpy import newaxis
 from ..data import (
     _13DFilings,
-    CashBuybackAuthorizations,
-    ShareBuybackAuthorizations,
+    BuybackAuthorizations,
     DividendsByAnnouncementDate,
     DividendsByExDate,
     EarningsCalendar
@@ -132,7 +131,7 @@ class BusinessDaysSincePreviousEarnings(BusinessDaysSincePreviousEvents):
     inputs = [EarningsCalendar.previous_announcement]
 
 
-class BusinessDaysSinceCashBuybackAuth(
+class BusinessDaysSinceBuybackAuth(
     BusinessDaysSincePreviousEvents
 ):
     """
@@ -143,22 +142,7 @@ class BusinessDaysSinceCashBuybackAuth(
     --------
     zipline.pipeline.factors.BusinessDaysSinceCashBuybackAuth
     """
-    inputs = [CashBuybackAuthorizations.announcement_date]
-
-
-class BusinessDaysSinceShareBuybackAuth(
-    BusinessDaysSincePreviousEvents
-):
-    """
-    Factor returning the number of **business days** (not trading days!) since
-    the most recent share buyback authorization for each asset.
-
-
-    See Also
-    --------
-    zipline.pipeline.factors.BusinessDaysSinceShareBuybackAuth
-    """
-    inputs = [ShareBuybackAuthorizations.announcement_date]
+    inputs = [BuybackAuthorizations.previous_date]
 
 
 class BusinessDaysSinceDividendAnnouncement(

zipline/pipeline/loaders/__init__.py

@@ -1,10 +1,7 @@
 from ._13d_filings import _13DFilingsLoader
-from .earnings import EarningsCalendarLoader
 from .consensus_estimates import ConsensusEstimatesLoader
-from .buyback_auth import (
-    CashBuybackAuthorizationsLoader,
-    ShareBuybackAuthorizationsLoader
-)
+from .earnings import EarningsCalendarLoader
+from .buyback_auth import BuybackAuthorizationsLoader
 from .dividends import (
     DividendsByAnnouncementDateLoader,
     DividendsByExDateLoader,
@@ -14,12 +11,11 @@ from .equity_pricing_loader import USEquityPricingLoader
 
 __all__ = [
     '_13DFilingsLoader',
-    'CashBuybackAuthorizationsLoader',
+    'BuybackAuthorizationsLoader',
     'DividendsByAnnouncementDateLoader',
     'DividendsByExDateLoader',
     'DividendsByPayDateLoader',
     'EarningsCalendarLoader',
     'ConsensusEstimatesLoader',
-    'ShareBuybackAuthorizationsLoader',
     'USEquityPricingLoader',
 ]

zipline/pipeline/loaders/blaze/__init__.py

@@ -1,8 +1,6 @@
 from ._13d_filings import Blaze_13DFilingsLoader
-from .buyback_auth import (
-    BlazeCashBuybackAuthorizationsLoader,
-    BlazeShareBuybackAuthorizationsLoader
-)
+
+from .buyback_auth import BlazeBuybackAuthorizationsLoader
 from .core import (
     BlazeLoader,
     NoDeltasWarning,
@@ -21,14 +19,13 @@ from .consensus_estimates import BlazeConsensusEstimatesLoader
 
 __all__ = (
     'Blaze_13DFilingsLoader',
-    'BlazeCashBuybackAuthorizationsLoader',
+    'BlazeBuybackAuthorizationsLoader',
     'BlazeDividendsByAnnouncementDateLoader',
     'BlazeConsensusEstimatesLoader',
     'BlazeDividendsByExDateLoader',
     'BlazeDividendsByPayDateLoader',
     'BlazeEarningsCalendarLoader',
     'BlazeLoader',
-    'BlazeShareBuybackAuthorizationsLoader',
     'from_blaze',
     'global_loader',
     'NoDeltasWarning',

zipline/pipeline/loaders/blaze/buyback_auth.py

@@ -4,22 +4,14 @@ from .core import (
 )
 from zipline.pipeline.common import (
     BUYBACK_ANNOUNCEMENT_FIELD_NAME,
-    CASH_FIELD_NAME,
-    SHARE_COUNT_FIELD_NAME
-)
-from zipline.pipeline.data import (
-    CashBuybackAuthorizations,
-    ShareBuybackAuthorizations
-)
-from zipline.pipeline.loaders import (
-    CashBuybackAuthorizationsLoader,
-    ShareBuybackAuthorizationsLoader,
-)
+    VALUE_FIELD_NAME, VALUE_TYPE_FIELD_NAME, BUYBACK_TYPE_FIELD_NAME)
+from zipline.pipeline.data import BuybackAuthorizations
+from zipline.pipeline.loaders import BuybackAuthorizationsLoader
 from .events import BlazeEventsLoader
 
 
-class BlazeCashBuybackAuthorizationsLoader(BlazeEventsLoader):
-    """A pipeline loader for the ``CashBuybackAuthorizations`` dataset that
+class BlazeBuybackAuthorizationsLoader(BlazeEventsLoader):
+    """A pipeline loader for the ``BuybackAuthorizations`` dataset that
     loads data from a blaze expression.
 
     Parameters
@@ -45,12 +37,15 @@ class BlazeCashBuybackAuthorizationsLoader(BlazeEventsLoader):
            {SID_FIELD_NAME}: int64,
            {TS_FIELD_NAME}: datetime,
            {BUYBACK_ANNOUNCEMENT_FIELD_NAME}: ?datetime,
-           {CASH_FIELD_NAME}: ?float64
+           {VALUE_FIELD_NAME}: ?float64,
+           {VALUE_TYPE_FIELD_NAME}: ?float64,
+           {BUYBACK_TYPE_FIELD_NAME}: ?float64,
        }}
 
     Where each row of the table is a record including the sid to identify the
     company, the timestamp where we learned about the announcement, the
-    date when the buyback was announced, the share count, and the cash amount.
+    date when the buyback was announced, the buyback value, the value type
+    (in cash or in shares), and the buyback type.
 
     If the '{TS_FIELD_NAME}' field is not included it is assumed that we
     start the backtest with knowledge of all announcements.
@@ -59,70 +54,19 @@ class BlazeCashBuybackAuthorizationsLoader(BlazeEventsLoader):
         TS_FIELD_NAME=TS_FIELD_NAME,
         SID_FIELD_NAME=SID_FIELD_NAME,
         BUYBACK_ANNOUNCEMENT_FIELD_NAME=BUYBACK_ANNOUNCEMENT_FIELD_NAME,
-        CASH_FIELD_NAME=CASH_FIELD_NAME
+        VALUE_FIELD_NAME=VALUE_FIELD_NAME,
+        VALUE_TYPE_FIELD_NAME=VALUE_TYPE_FIELD_NAME,
+        BUYBACK_TYPE_FIELD_NAME=BUYBACK_TYPE_FIELD_NAME
     )
 
     _expected_fields = frozenset({
         TS_FIELD_NAME,
         SID_FIELD_NAME,
         BUYBACK_ANNOUNCEMENT_FIELD_NAME,
-        CASH_FIELD_NAME
+        VALUE_FIELD_NAME,
+        VALUE_TYPE_FIELD_NAME,
+        BUYBACK_TYPE_FIELD_NAME
     })
 
-    concrete_loader = CashBuybackAuthorizationsLoader
-    default_dataset = CashBuybackAuthorizations
-
-
-class BlazeShareBuybackAuthorizationsLoader(BlazeEventsLoader):
-    """A pipeline loader for the ``ShareBuybackAuthorizations`` dataset that
-    loads data from a blaze expression.
-
-    Parameters
-    ----------
-    expr : Expr
-        The expression representing the data to load.
-    resources : dict, optional
-        Mapping from the loadable terms of ``expr`` to actual data resources.
-    odo_kwargs : dict, optional
-        Extra keyword arguments to pass to odo when executing the expression.
-    data_query_time : time, optional
-        The time to use for the data query cutoff.
-    data_query_tz : tzinfo or str
-        The timezeone to use for the data query cutoff.
-    dataset: DataSet
-        The DataSet object for which this loader loads data.
-
-    Notes
-    -----
-    The expression should have a tabular dshape of::
-
-       Dim * {{
-           {SID_FIELD_NAME}: int64,
-           {TS_FIELD_NAME}: datetime,
-           {BUYBACK_ANNOUNCEMENT_FIELD_NAME}: ?datetime,
-           {SHARE_COUNT_FIELD_NAME}: ?float64,
-       }}
-
-    Where each row of the table is a record including the sid to identify the
-    company, the timestamp where we learned about the announcement, the
-    date when the buyback was announced, the share count, and the value.
-
-    If the '{TS_FIELD_NAME}' field is not included it is assumed that we
-    start the backtest with knowledge of all announcements.
-    """
-    __doc__ = __doc__.format(
-        TS_FIELD_NAME=TS_FIELD_NAME,
-        SID_FIELD_NAME=SID_FIELD_NAME,
-        BUYBACK_ANNOUNCEMENT_FIELD_NAME=BUYBACK_ANNOUNCEMENT_FIELD_NAME,
-        SHARE_COUNT_FIELD_NAME=SHARE_COUNT_FIELD_NAME,
-    )
-
-    _expected_fields = frozenset({
-        TS_FIELD_NAME,
-        SID_FIELD_NAME,
-        BUYBACK_ANNOUNCEMENT_FIELD_NAME,
-        SHARE_COUNT_FIELD_NAME,
-    })
-
-    concrete_loader = ShareBuybackAuthorizationsLoader
-    default_dataset = ShareBuybackAuthorizations
+    concrete_loader = BuybackAuthorizationsLoader
+    default_dataset = BuybackAuthorizations

zipline/pipeline/loaders/buyback_auth.py

@@ -2,30 +2,30 @@
 Reference implementation for buyback auth loaders.
 """
 
-from ..data import (
-    CashBuybackAuthorizations,
-    ShareBuybackAuthorizations
-)
+from ..data import BuybackAuthorizations
 from .events import EventsLoader
 from zipline.pipeline.common import (
     BUYBACK_ANNOUNCEMENT_FIELD_NAME,
-    CASH_FIELD_NAME,
-    SHARE_COUNT_FIELD_NAME
+    BUYBACK_TYPE_FIELD_NAME,
+    VALUE_FIELD_NAME,
+    VALUE_TYPE_FIELD_NAME
 )
 from zipline.utils.memoize import lazyval
 
 
-class CashBuybackAuthorizationsLoader(EventsLoader):
+class BuybackAuthorizationsLoader(EventsLoader):
     """
     Reference loader for
-    :class:`zipline.pipeline.data.CashBuybackAuthorizations`.
+    :class:`zipline.pipeline.data.BuybackAuthorizations`.
 
     events_by_sid: dict[sid -> pd.DataFrame(knowledge date,
-    event date, cash value)]
+    event date, value, value type, buyback type)]
 
     """
     expected_cols = frozenset([BUYBACK_ANNOUNCEMENT_FIELD_NAME,
-                               CASH_FIELD_NAME])
+                               VALUE_FIELD_NAME,
+                               VALUE_TYPE_FIELD_NAME,
+                               BUYBACK_TYPE_FIELD_NAME])
 
     event_date_col = BUYBACK_ANNOUNCEMENT_FIELD_NAME
 
@@ -33,8 +33,8 @@ class CashBuybackAuthorizationsLoader(EventsLoader):
                  all_dates,
                  events_by_sid,
                  infer_timestamps=False,
-                 dataset=CashBuybackAuthorizations):
-        super(CashBuybackAuthorizationsLoader, self).__init__(
+                 dataset=BuybackAuthorizations):
+        super(BuybackAuthorizationsLoader, self).__init__(
             all_dates,
             events_by_sid,
             infer_timestamps=infer_timestamps,
@@ -42,57 +42,28 @@ class CashBuybackAuthorizationsLoader(EventsLoader):
         )
 
     @lazyval
-    def cash_amount_loader(self):
+    def previous_value_loader(self):
         return self._previous_event_value_loader(
             self.dataset.cash_amount,
-            CASH_FIELD_NAME
+            VALUE_FIELD_NAME
         )
 
     @lazyval
-    def announcement_date_loader(self):
+    def previous_date_loader(self):
         return self._previous_event_date_loader(
             self.dataset.announcement_date,
         )
 
-
-class ShareBuybackAuthorizationsLoader(EventsLoader):
-    """
-    Reference loader for
-    :class:`zipline.pipeline.data.ShareBuybackAuthorizations`.
-
-    Does not currently support adjustments to the dates of known buyback
-    authorizations.
-
-    events_by_sid: dict[sid -> pd.DataFrame(knowledge date,
-     event date, share value)]
-
-    """
-    expected_cols = frozenset([BUYBACK_ANNOUNCEMENT_FIELD_NAME,
-                               SHARE_COUNT_FIELD_NAME])
-
-    event_date_col = BUYBACK_ANNOUNCEMENT_FIELD_NAME
-
-    def __init__(self,
-                 all_dates,
-                 events_by_sid,
-                 infer_timestamps=False,
-                 dataset=ShareBuybackAuthorizations):
-        super(ShareBuybackAuthorizationsLoader, self).__init__(
-            all_dates,
-            events_by_sid,
-            infer_timestamps=infer_timestamps,
-            dataset=dataset,
-        )
-
     @lazyval
-    def share_count_loader(self):
-        return self._previous_event_value_loader(
-            self.dataset.share_count,
-            SHARE_COUNT_FIELD_NAME
-        )
-
-    @lazyval
-    def announcement_date_loader(self):
+    def previous_buyback_type_loader(self):
         return self._previous_event_date_loader(
             self.dataset.announcement_date,
+            BUYBACK_TYPE_FIELD_NAME,
+        )
+
+    @lazyval
+    def previous_value_type_loader(self):
+        return self._previous_event_date_loader(
+            self.dataset.announcement_date,
+            VALUE_TYPE_FIELD_NAME,
         )