Numerai Example Scripts

You can use Numerai's open-source agent skills to architect AI scientists for tournaments. To get started, clone the example scripts repository, install the Model Context Protocol (MCP) via the provided shell script, and use the codex CLI to execute high-level research tasks.

Note: The codex exec --yolo command allows the agent to perform autonomous actions to achieve the requested goal.

git clone git@github.com:numerai/example-scripts
cd example-scripts && curl -sL http://numer.ai/install-mcp.sh | bash
codex exec --yolo "find the best neural network architecture to predict target ender"

Eras

An era represents a specific date (typically one week apart). Rows within the same era represent the investable universe on that date.

Target

The target is a measure of stock-specific returns over the next 20 business days. Values are binned into 5 unequal bins: 0, 0.25, 0.5, 0.75, 1.0.

Features

Features are quantitative attributes (fundamentals, technical signals, etc.). Values are binned into 5 equal integer bins: 0, 1, 2, 3, 4. A value of 2 often indicates missing data for a particular feature in a given era.

Numerai provides pre-defined feature sets to manage complexity and memory usage:

• small: A minimal subset of features with high importance.
• medium: All "basic" features (e.g., P/E ratios vs analyst ratings).
• quantum: 807 new features released in v5.3.
• all: Includes medium and all its variants.

When loading data with pandas.read_parquet, use the columns parameter to load only the specific feature set you intend to use to save RAM.

# Example: Loading only the 'small' feature set from a parquet file
import pandas as pd

feature_set = feature_metadata["feature_sets"]["small"]
napi.download_dataset(f"{DATA_VERSION}/train.parquet")

train = pd.read_parquet(
    f"{DATA_VERSION}/train.parquet",
    columns=["era", "target"] + feature_set
)

Feature exposure measures a model's sensitivity to specific features. It is calculated as the Pearson correlation between a model's predictions and each feature in the dataset. High exposure to a specific feature means the model's performance is heavily dependent on that feature's stability.

# Compute the Pearson correlation of the predictions with each feature
feature_exposures = validation.groupby("era").apply(
    lambda d: d[feature_list].corrwith(d["prediction"])
)

Numerai datasets contain multiple auxiliary targets in addition to the main target. These targets are fundamentally related to the main target but have different correlations, making them useful for building ensembles.

Key naming conventions:

• Target Name: Represents the type of stock market return (e.g., residual to market/country/sector).
• Suffix (_20 or _60): Denotes the time horizon in market days.

Target values are floats ranging from 0 to 1. While the primary target is never NaN, auxiliary targets may contain NaN values.

Feature risk can be quantified by evaluating how individual features perform over time. Key metrics include:

• mean: Average correlation with the target.
• std: Volatility of the feature's correlation.
• sharpe: The ratio of mean correlation to std.
• max_drawdown: The largest peak-to-trough decline in cumulative correlation.
• delta: The absolute difference in mean correlation between the first and second half of the analysis period.

You can use numerai_tools.scoring.numerai_corr to compute per-era correlations.

from numerai_tools.scoring import numerai_corr

# Compute the per-era correlation of features to the target
per_era_corr = train.groupby("era").apply(
    lambda d: numerai_corr(d[feature_list], d["target"])
)

To run the feature neutralization examples, install the following required packages. Note that specific versions of pandas and cloudpickle are used in the example to ensure compatibility.

!pip install -q --upgrade numerapi pandas==2.3.1 pyarrow matplotlib lightgbm scikit-learn scipy cloudpickle==3.1.1
!pip install -q --no-deps numerai-tools

Datasets can be downloaded using napi.download_dataset(). The features.json file is a critical metadata file that contains feature statistics, helpful feature sets, and available targets.

import json

# download the feature metadata file
napi.download_dataset(f"{DATA_VERSION}/features.json")

# read the metadata and display
feature_metadata = json.load(open(f"{DATA_VERSION}/features.json"))
for metadata in feature_metadata:
  print(metadata, len(feature_metadata[metadata]))

To follow the Numerai example scripts, install the required Python packages including numerapi, pandas, pyarrow, matplotlib, lightgbm, scikit-learn, scipy, and cloudpickle.

!pip install -q --upgrade numerapi pandas==2.3.1 pyarrow matplotlib lightgbm scikit-learn scipy cloudpickle==3.1.1

To automate live predictions, you can define a prediction pipeline as a function, serialize it using cloudpickle, and upload the resulting .pkl file to Numerai. Numerai will then run your model daily against new live features.

Your function must accept a pd.DataFrame of live features and return a pd.DataFrame with a single column named prediction.

import cloudpickle

# 1. Define the pipeline function
def predict(live_features: pd.DataFrame) -> pd.DataFrame:
    live_predictions = model.predict(live_features[feature_set])
    submission = pd.Series(live_predictions, index=live_features.index)
    return submission.to_frame("prediction")

# 2. Serialize the function
p = cloudpickle.dumps(predict)
with open("hello_numerai.pkl", "wb") as f:
    f.write(p)

To evaluate how well your models predict the main target, use the numerai-tools library. Specifically, numerai_corr calculates the correlation of predictions with the target per era.

pip install -q --no-deps numerai-tools

from numerai_tools.scoring import numerai_corr

# correlations = validation.groupby("era").apply(lambda d: numerai_corr(d[prediction_cols], d["target"]))