numerai-tools 0.5.0.dev4__tar.gz → 0.5.0.dev6__tar.gz

{numerai_tools-0.5.0.dev4 → numerai_tools-0.5.0.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: numerai-tools
-Version: 0.5.0.dev4
+Version: 0.5.0.dev6
 Summary: A collection of open-source tools to help interact with Numerai, model data, and automate submissions.
 License: MIT
 Author: Numerai Engineering

{numerai_tools-0.5.0.dev4 → numerai_tools-0.5.0.dev6}/numerai_tools/signals.py

@@ -7,7 +7,8 @@ from numerai_tools.scoring import (
     generate_neutralized_weights,
 )
 from numerai_tools.submissions import (
-    validate_and_clean_submission_signals,
+    validate_submission_signals,
+    clean_submission,
     remap_ids,
 )
 
@@ -65,9 +66,6 @@ def turnover(
     Arguments:
         s1: pd.Series - the first series to compare
         s2: pd.Series - the second series to compare
-        top_bottom: Optional[int] - the number of top and bottom predictions to use
-                                    when calculating the correlation. Results in
-                                    2*top_bottom predictions.
 
     Returns:
         float - the turnover between the two series
@@ -106,27 +104,50 @@ def calculate_max_churn_and_turnover(
         prev_week_max_turnover -- the maximum turnover from previous submissions
     """
     universe = universe.reset_index()
-    curr_sub_vector = validate_and_clean_submission_signals(
+    (
+        curr_ticker_col,
+        curr_signal_col,
+        curr_sub,
+        _,
+    ) = validate_submission_signals(
         universe=universe,
         submission=curr_sub,
-        id_col=curr_ticker_col,
-        rename_as=curr_signal_col,
+    )
+    curr_sub_vector = clean_submission(
+        universe=universe,
+        submission=curr_sub,
+        src_id_col=curr_ticker_col,
+        src_signal_col=curr_signal_col,
         rank_and_fill=True,
     )
     churn_stats = []
     turnover_stats = []
     neutralized_weights = generate_neutralized_weights(
-        curr_sub_vector.to_frame(), curr_neutralizer, curr_weight
+        curr_sub_vector.to_frame(),
+        curr_neutralizer,
+        curr_weight,
+        center_and_normalize=True,
     )
     for datestamp in prev_week_subs:
         prev_sub = prev_week_subs[datestamp]
         prev_neutralizer = prev_neutralizers[datestamp]
         prev_weight = prev_sample_weights[datestamp]
-        filtered_prev_sub = validate_and_clean_submission_signals(
+        (
+            prev_ticker_col,
+            prev_signal_col,
+            prev_sub,
+            _,
+        ) = validate_submission_signals(
+            universe=universe,
+            submission=prev_sub,
+        )
+        filtered_prev_sub = clean_submission(
             universe=universe,
             submission=prev_sub,
-            id_col=curr_ticker_col,
-            rename_as=curr_signal_col,
+            src_id_col=prev_ticker_col,
+            src_signal_col=prev_signal_col,
+            dst_id_col=curr_ticker_col,
+            dst_signal_col=curr_signal_col,
             rank_and_fill=True,
         )
         prev_neutralizer = (
@@ -146,7 +167,10 @@ def calculate_max_churn_and_turnover(
             curr_ticker_col,
         ).set_index(curr_ticker_col)[prev_weight.name]
         prev_neutralized_weights = generate_neutralized_weights(
-            filtered_prev_sub.to_frame(), prev_neutralizer, prev_weight
+            filtered_prev_sub.to_frame(),
+            prev_neutralizer,
+            prev_weight,
+            center_and_normalize=True,
         )
         try:
             churn_val = abs(churn(curr_sub_vector, filtered_prev_sub))

{numerai_tools-0.5.0.dev4 → numerai_tools-0.5.0.dev6}/numerai_tools/submissions.py

@@ -28,7 +28,9 @@ logger = logging.getLogger(__name__)
 
 
 def _validate_headers(
-    expected_id_cols: List[str], expected_pred_cols: List[str], submission: pd.DataFrame
+    submission: pd.DataFrame,
+    expected_id_cols: List[str],
+    expected_pred_cols: List[str],
 ) -> Tuple[str, str]:
     """Validate the given submission has the right headers.
     It is recommended to use one of the following functions instead of this one:
@@ -37,6 +39,8 @@ def _validate_headers(
 
     Arguments:
         submission -- pandas DataFrame of the submission
+        expected_id_cols -- list of expected id columns
+        expected_pred_cols -- list of expected prediction columns
 
     Return Tuple[str, str]:
         - string name of the id column
@@ -58,19 +62,43 @@ def _validate_headers(
 
 def validate_headers_numerai(submission: pd.DataFrame) -> Tuple[str, str]:
     return _validate_headers(
-        NUMERAI_ALLOWED_ID_COLS, NUMERAI_ALLOWED_PRED_COLS, submission
+        submission,
+        NUMERAI_ALLOWED_ID_COLS,
+        NUMERAI_ALLOWED_PRED_COLS,
     )
 
 
-def validate_headers_signals(submission: pd.DataFrame) -> Tuple[str, str]:
-    return _validate_headers(
-        SIGNALS_ALLOWED_ID_COLS, SIGNALS_ALLOWED_PRED_COLS, submission
+def validate_headers_signals(
+    submission: pd.DataFrame, assert_date_col: bool = False
+) -> Tuple[str, str, Optional[str]]:
+    # remove date columns if they exist and store them temporarily
+    date_col_name: Optional[str] = None
+    date_col: Optional[pd.Series] = None
+    for col in submission.columns:
+        if col in SIGNALS_ALLOWED_DATE_COLS:
+            date_col_name = col
+            date_col = submission[date_col_name].copy()
+            submission = submission.drop(columns=date_col_name, errors="ignore")
+            break
+    if assert_date_col:
+        assert (
+            date_col_name is not None
+        ), "invalid_submission_headers: submission must contain a date column"
+    ticker_col, signal_col = _validate_headers(
+        submission,
+        SIGNALS_ALLOWED_ID_COLS,
+        SIGNALS_ALLOWED_PRED_COLS,
     )
+    if date_col is not None:
+        submission[date_col_name] = date_col
+    return ticker_col, signal_col, date_col_name
 
 
 def validate_headers_crypto(submission: pd.DataFrame) -> Tuple[str, str]:
     return _validate_headers(
-        CRYPTO_ALLOWED_ID_COLS, CRYPTO_ALLOWED_PRED_COLS, submission
+        submission,
+        CRYPTO_ALLOWED_ID_COLS,
+        CRYPTO_ALLOWED_PRED_COLS,
     )
 
 
@@ -156,12 +184,93 @@ def validate_ids_crypto(
     return _validate_ids(live_ids, submission, id_col, CRYPTO_MIN_TICKERS)
 
 
+def validate_submission_numerai(
+    universe: pd.Series, submission: pd.DataFrame
+) -> Tuple[str, str, pd.DataFrame, List[str]]:
+    """Validate the headers, ids, and values for a submission.
+
+    Arguments:
+        universe: pd.DataFrame - the live universe of ids on which the predictions are based
+        submission: pd.DataFrame - the predictions to validate
+
+    Returns:
+        Tuple[str, str, pd.DataFrame, List[str]] - the validated ticker column, signal column,
+                                                   filtered submission, and list of invalid tickers
+    """
+    ticker_col, signal_col = validate_headers_numerai(submission)
+    filtered_sub, invalid_tickers = validate_ids_numerai(
+        universe, submission, ticker_col
+    )
+    validate_values(filtered_sub, signal_col)
+    return ticker_col, signal_col, filtered_sub, invalid_tickers
+
+
+def validate_submission_signals(
+    universe: pd.DataFrame, submission: pd.DataFrame
+) -> Tuple[str, str, pd.DataFrame, List[str]]:
+    """Validate the headers, ids, and values for a submission.
+
+    Arguments:
+        universe: pd.DataFrame - the live universe of ids on which the predictions are based
+        submission: pd.DataFrame - the predictions to validate
+
+    Returns:
+        Tuple[str, str, pd.DataFrame, List[str]] - the validated ticker column, signal column,
+                                                   filtered submission, and list of invalid tickers
+    """
+    # drop data_type and date columns if they exist
+    if "data_type" in submission.columns:
+        logger.warning(
+            "data_type column found in Signals submission. This is deprecated and support will be removed in the future. "
+            "Please remove the data_type column from your Signals submission."
+        )
+        submission = submission.drop(columns=["data_type"], errors="ignore")
+    ticker_col, signal_col, _ = validate_headers_signals(submission)
+    filtered_sub, invalid_tickers = validate_ids_signals(
+        universe[ticker_col], submission, ticker_col
+    )
+    validate_values(filtered_sub, signal_col)
+    return ticker_col, signal_col, filtered_sub, invalid_tickers
+
+
+def validate_submission_crypto(
+    universe: pd.DataFrame, submission: pd.DataFrame
+) -> Tuple[str, str, pd.DataFrame, List[str]]:
+    """Validate the headers, ids, and values for a submission.
+
+    Arguments:
+        universe: pd.DataFrame - the live universe of ids on which the predictions are based
+        submission: pd.DataFrame - the predictions to validate
+
+    Returns:
+        Tuple[str, str, pd.DataFrame, List[str]] - the validated ticker column, signal column,
+                                                   filtered submission, and list of invalid tickers
+    """
+    ticker_col, signal_col = validate_headers_crypto(submission)
+    filtered_sub, invalid_tickers = validate_ids_crypto(
+        universe[ticker_col], submission, ticker_col
+    )
+    validate_values(filtered_sub, signal_col)
+    return ticker_col, signal_col, filtered_sub, invalid_tickers
+
+
 def remap_ids(
     data: pd.DataFrame,
     ticker_map: pd.Series | pd.DataFrame,
     src_id_col: str,
     dst_id_col: str,
 ) -> pd.DataFrame:
+    """Join the data to the ticker map based on source ids
+    and remap to the destination ids. If the ticker is a Series, it is assumed that
+    src_id_col and dst_id_col are the same, and the ticker map is simply used to
+    ensure the data has all ids in the ticker map.
+
+    Arguments:
+        data: pd.DataFrame - the data to remap
+        ticker_map: pd.Series | pd.DataFrame - the mapping of source ids to destination ids
+        src_id_col: str - the name of the source ids column in the data
+        dst_id_col: str - the name of the destination ids column in the ticker map
+    """
     # first, index the universe and data on the source ids
     indexed_map = ticker_map.reset_index().set_index(src_id_col)
     indexed_data = data.set_index(src_id_col)
@@ -176,134 +285,58 @@ def remap_ids(
 
 
 def clean_submission(
-    live_ids: pd.Series | pd.DataFrame,
-    predictions: pd.DataFrame,
-    ticker_col: str,
-    signal_col: str,
-    rename_as: Optional[str],
-    id_col: str,
-    rank_and_fill: bool,
+    universe: pd.Series | pd.DataFrame,
+    submission: pd.DataFrame,
+    src_id_col: str,
+    src_signal_col: str,
+    dst_id_col: Optional[str] = None,
+    dst_signal_col: Optional[str] = None,
+    rank_and_fill: bool = False,
 ) -> pd.Series:
-    """Prepare predictions for submission to Numerai.
-    Filters out ids not in live data, drops duplicates, sets ids as index,
-    then optionally ranks (keeping ties) and fills NaNs with 0.5.
+    """Prepares your submission for uploading to a Numerai tournament.
+    Joins your submission to the universe, remaps ids as neded, drops
+    duplicates, sets ids as index, renames the series, then optionally
+    tie-kept ranks and fills NaNs with 0.5.
 
     This function is used in Numerai to clean submissions for use in the
-    Meta Model and scoring. We only rank and fill in preparation for scoring
-    Signals and Crypto submissions.
+    Meta Model and scoring. We rank and fill submissions before scoring.
 
     Arguments:
-        live_ids: pd.Series - the ids in the live data
-        predictions: pd.DataFrame - the predictions to clean
-        ticker_col: str - the name of the ids column
-        signal_col: str - the name of the predictions column
-        rename_as: Optional[str] - the string to which the submission should be renamed
-        id_col: str - the column name of the ids
-        rank_and_fill: bool - whether to rank and fill NaNs with 0.5
+        universe: pd.Series - the live universe of ids on which the predictions are based
+        submission: pd.DataFrame - the submission to clean
+        src_id_col: str - the name of the ids column
+        src_signal_col: str - the name of the predictions column
+        dst_id_col: Optional[str] - optional name of the id column to map the ids to
+        dst_signal_col: Optional[str] - optional name of the signal column to rename the submission to
+        rank_and_fill: bool - whether to call tie_kept_rank and then fill NaNs with 0.5
 
     Returns:
-        pd.Series - the cleaned prediction series with ids as index
+        pd.Series - the cleaned, properly indexed submission
     """
-    assert len(live_ids) > 0, "live_ids must not be empty"
-    if isinstance(live_ids, pd.DataFrame):
-        assert live_ids.isna().sum().sum() == 0, "live_ids must not contain NaNs"
+    assert len(universe) > 0, "universe must not be empty"
+    if isinstance(universe, pd.DataFrame):
+        assert universe.isna().sum().sum() == 0, "universe must not contain NaNs"
     else:
-        assert live_ids.isna().sum() == 0, "live_ids must not contain NaNs"
-    assert len(predictions) > 0, "predictions must not be empty"
+        assert universe.isna().sum() == 0, "universe must not contain NaNs"
+    assert len(submission) > 0, "predictions must not be empty"
+
+    if dst_id_col is None:
+        dst_id_col = src_id_col
+    if dst_signal_col is None:
+        dst_signal_col = src_signal_col
 
     clean_preds = (
-        remap_ids(predictions, live_ids, ticker_col, id_col)
+        remap_ids(submission, universe, src_id_col, dst_id_col)
         # drop NaNs and duplicates
-        .dropna(subset=[id_col])
-        .drop_duplicates(subset=id_col, keep="first")
+        .dropna(subset=[dst_id_col])
+        .drop_duplicates(subset=dst_id_col, keep="first")
         # set ids as index and sort
-        .set_index(id_col)
+        .set_index(dst_id_col)
         .sort_index()
         # rename to given name
-        .rename(columns={signal_col: rename_as})
-    )[rename_as]
+        .rename(columns={src_signal_col: dst_signal_col})
+    )[dst_signal_col]
     # rank and fill with 0.5
     if rank_and_fill:
         clean_preds = tie_kept_rank(clean_preds).fillna(0.5)
     return clean_preds
-
-
-def validate_and_clean_submission_numerai(
-    universe: pd.Series,
-    submission: pd.DataFrame,
-    id_col: str = "id",
-    rename_as: Optional[str] = None,
-    rank_and_fill: bool = False,
-) -> pd.Series:
-    ticker_col, signal_col = validate_headers_numerai(submission)
-    filtered_sub, invalid_tickers = validate_ids_numerai(
-        universe, submission, ticker_col
-    )
-    validate_values(filtered_sub, signal_col)
-    return clean_submission(
-        live_ids=universe,
-        predictions=filtered_sub,
-        ticker_col=ticker_col,
-        signal_col=signal_col,
-        rename_as=rename_as,
-        id_col=id_col,
-        rank_and_fill=rank_and_fill,
-    )
-
-
-def validate_and_clean_submission_signals(
-    universe: pd.DataFrame,
-    submission: pd.DataFrame,
-    id_col: str,
-    rename_as: Optional[str] = None,
-    rank_and_fill: bool = True,
-) -> pd.Series:
-    # drop data_type and date columns if they exist
-    if "data_type" in submission.columns:
-        logger.warning(
-            "data_type column found in Signals submission. This is deprecated and support will be removed in the future. "
-            "Please remove the data_type column from your Signals submission."
-        )
-    date_col = [
-        date_col
-        for date_col in SIGNALS_ALLOWED_DATE_COLS
-        if date_col in list(submission.columns)
-    ]
-    submission = submission.drop(columns=["data_type", *date_col], errors="ignore")
-    ticker_col, signal_col = validate_headers_signals(submission)
-    filtered_sub, invalid_tickers = validate_ids_signals(
-        universe[ticker_col], submission, ticker_col
-    )
-    validate_values(filtered_sub, signal_col)
-    return clean_submission(
-        live_ids=universe,
-        predictions=filtered_sub,
-        ticker_col=ticker_col,
-        signal_col=signal_col,
-        rename_as=rename_as,
-        id_col=id_col,
-        rank_and_fill=rank_and_fill,
-    )
-
-
-def validate_and_clean_submission_crypto(
-    universe: pd.DataFrame,
-    submission: pd.DataFrame,
-    id_col: str = "symbol",
-    rename_as: Optional[str] = None,
-    rank_and_fill: bool = True,
-):
-    ticker_col, signal_col = validate_headers_crypto(submission)
-    filtered_sub, invalid_tickers = validate_ids_crypto(
-        universe[ticker_col], submission, ticker_col
-    )
-    validate_values(filtered_sub, signal_col)
-    return clean_submission(
-        live_ids=universe,
-        predictions=filtered_sub,
-        ticker_col=ticker_col,
-        signal_col=signal_col,
-        rename_as=rename_as,
-        id_col=id_col,
-        rank_and_fill=rank_and_fill,
-    )

{numerai_tools-0.5.0.dev4 → numerai_tools-0.5.0.dev6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "numerai-tools"
-version = "0.5.0.dev4"
+version = "0.5.0.dev6"
 description = "A collection of open-source tools to help interact with Numerai, model data, and automate submissions."
 authors = [
     {name = "Numerai Engineering",email = "engineering@numer.ai"}