International Factor Research - Alphalens Example¶

def evaluate_factor(factor, 
                    domain, 
                    start_date, 
                    end_date,
                    factor_screen=None,
                    quantiles=5,
                    returns_lengths=(1, 5, 10),
                    session = 'Overnight',
                    chunksize = None
                   ):
    """Analyze a Pipeline Factor using Alphalens.
    
    Parameters
    ----------
    factor : quantopian.pipeline.factors.Factor
        Factor producing scores to be evaluated.
    domain : quantopian.pipeline.domain.Domain
        Domain on which the factor should be evaluated.
    start_date : str or pd.Timestamp
        Start date for evaluation period.
    end_date : str or pd.Timestamp
        End date for evaluation period.
    standardize : 
    factor_screen : quantopian.pipeline.filters.Filter, optional
        Filter defining which assets ``factor`` should be evaluated on.
        Default is ``factor.notnull()``.
    quantiles : int, optional
        Number of buckets to use for quantile groups. Default is 5
    returns_lengths : sequence[int]
        Forward-returns horizons to use when evaluating ``factor``. 
        Default is 1-day, 5-day, and 10-day returns.
    session: str
        "Overnight", "Intraday", "Daily"
        
    Returns
    -------
    factor_data : pd.DataFrame
        A (date, asset)-indexed DataFrame with the following columns:
            'factor': float64
                Values produced by ``factor``.
            'factor_quantiles': int64
                Daily quantile label for each
    """
    calendar = domain.calendar

    # Roll input dates to the next trading session.
    start_date = calendar.minute_to_session_label(pd.Timestamp(start_date, tz='UTC'))
    end_date = calendar.minute_to_session_label(pd.Timestamp(end_date, tz='UTC'))
    
    if factor_screen is None:
        factor_screen = factor.notnull()
        
        
    # Run pipeline to get factor values and quantiles.
    factor_pipe = Pipeline(
        {'factor': factor, 
         'factor_quantile': factor.quantiles(quantiles, mask=factor_screen)},
        screen=factor_screen,
        domain=domain,
    )
    # Put chunksize ~252-504 if you run into memory problems 
    factor_results = run_pipeline(factor_pipe, start_date, end_date, chunksize=chunksize)
    
    class Daily(CustomFactor):  
        inputs = [EquityPricing.close]  

        def compute(self, today, assets, out, close):  
            out[:] = close[-1] / close[0] - 1
            
    class Overnight(CustomFactor):  
        inputs = [EquityPricing.close, EquityPricing.open]  

        def compute(self, today, assets, out, close, open):  
            out[:] = np.cumprod(open[1:] / close[:-1], axis=0)[-1] - 1
            
    class Intraday(CustomFactor):  
        inputs = [EquityPricing.close, EquityPricing.open]  

        def compute(self, today, assets, out, close, open):  
            out[:] = np.cumprod(close / open, axis=0)[-1] - 1
    
    column_order = []
    returns_cols = {}
    for length in returns_lengths:
        colname = '{}D'.format(length)
        column_order.append(colname)
        
        # Add 1 because "1-day" returns needs 2 price observations.
        # Not relevant for Intraday.
        # Winsorize returns to handle data gliches
        # Example: get_pricing("BRK_A", start_date='2014-11-03', end_date='2014-11-08')
        # 0.002 * ~500 (companies per day) = 1 (from each side)
        if session == 'Overnight':
            returns_cols[colname] = Overnight(window_length=length + 1).winsorize(.002, .998)
        elif session == "Intraday":
            returns_cols[colname] = Intraday(window_length=length).winsorize(.002, .998)
        elif session == "Daily":
            returns_cols[colname] = Daily(window_length=length + 1).winsorize(.002, .998)
        else:
            raise SystemExit("session should be one of 'Overnight', 'Intraday', 'Daily'")
        

    returns_pipe = Pipeline(returns_cols, domain=domain)
    
    # Compute returns for the period after the factor pipeline, then 
    # shift the results back to align with our factor values.
    returns_start_date = start_date
    returns_end_date = end_date + domain.calendar.day * max(returns_lengths)
    raw_returns = run_pipeline(returns_pipe, returns_start_date, returns_end_date, chunksize=252)
    
    shifted_returns = {}
    for name, length in zip(column_order, returns_lengths):
        # Shift 1-day returns back by a day, 5-day returns back by 5 days, etc.
        raw = raw_returns[name]
        shifted_returns[name] = backshift_returns_series(raw, length)
        
    # Merge backshifted returns into a single frame indexed like our desired output.
    merged_returns = pd.DataFrame(
        data=shifted_returns, 
        index=factor_results.index, 
        columns=column_order,
    )
    
    # Concat factor results and forward returns column-wise.
    merged = pd.concat([factor_results, merged_returns], axis=1)
    merged.index.set_names(['date', 'asset'], inplace=True)

    return merged.dropna(how='any')


def backshift_returns_series(series, N):
    """Shift a multi-indexed series backwards by N observations in the first level.
    
    This can be used to convert backward-looking returns into a forward-returns series.
    """
    ix = series.index
    dates, sids = ix.levels
    date_labels, sid_labels = map(np.array, ix.labels)

    # Output date labels will contain all but the last N dates.
    new_dates = dates[:-N]

    # Output data will remove the first M rows, where M is the index of the
    # last record with one of the first N dates.
    cutoff = date_labels.searchsorted(N)
    new_date_labels = date_labels[cutoff:] - N
    new_sid_labels = sid_labels[cutoff:]
    new_values = series.values[cutoff:]

    assert new_date_labels[0] == 0

    new_index = pd.MultiIndex(
        levels=[new_dates, sids],
        labels=[new_date_labels, new_sid_labels],
        sortorder=1,
        names=ix.names,
    )

    return pd.Series(data=new_values, index=new_index)