numerblox offers Numerai specific functionality, so you can worry less about software/data engineering and focus more on building great Numerai models!
Most of the components in this library are designed for solid weekly inference pipelines, but tools like NumerFrame, preprocessors and evaluators also greatly simplify the training process.
This document has been generated by NBDev. Please edit nbs/index.ipynb instead of this README.md. Read CONTRIBUTING.MD for more information on the contribution process and how to change files. Thank you!
1.1 Installation
Install numerblox from PyPi by running:
pip install numerblox
Alternatively you can clone this repository and install it in development mode running the following from the root of the repository:
pip install -e .
1.2 Running Notebooks
Start by spinning up your favorite Jupyter Notebook environment. Here we’ll use:
jupyter notebook
Test your installation using one of the education notebooks in nbs/edu_nbs. A good example is numerframe_tutorial. Run it in your Notebook environment to quickly test if your installation has succeeded
2.1. Contents
2.1.1. Core functionality
numerblox features the following functionality:
Downloading data
A custom data structure extending Pandas DataFrame (NumerFrame)
A suite of preprocessors for Numerai Classic and Signals (feature selection, engineering and manipulation)
Model objects for easy inference.
A suite of postprocessors for Numerai Classic and Signals (standardization, ensembling, neutralization and penalization)
Example notebooks can be found in the nbs/edu_nbs directory.
nbs/edu_nbs currently contains the following examples: - numerframe_tutorial.ipynb: A deep dive into what NumerFrame has to offer. - submitting.ipynb: How to use Submitters for safe and easy Numerai submissions. - google_cloud_storage.ipynb: How to use Downloaders and Submitters to interact with Google Cloud Storage (GCS). - load_model_from_wandb.ipynb: For Weights & Biases users. Easily pull a model from W&B for inference. - numerbay_integration.ipynb: How to use NumerBlox to download and upload predictions listed on NumerBay. - synthetic_data_generation.ipynb: Tutorial for generating synthetic data for training Numerai models.
Development notebooks are also in the nbs directory. These notebooks are also used to generate the documentation.
Below we will illustrate a common use case for inference pipelines. To learn more in-depth about the features of this library, check out notebooks in nbs/edu_nbs.
2.2.1. Numerai Classic
# --- 0. Numerblox dependencies ---from numerblox.download import NumeraiClassicDownloaderfrom numerblox.numerframe import create_numerframefrom numerblox.postprocessing import FeatureNeutralizerfrom numerblox.model import SingleModelfrom numerblox.model_pipeline import ModelPipelinefrom numerblox.key import load_key_from_jsonfrom numerblox.submission import NumeraiClassicSubmitter# --- 1. Download version 4 data ---downloader = NumeraiClassicDownloader("data")downloader.download_inference_data("current_round")# --- 2. Initialize NumerFrame ---dataf = create_numerframe(file_path="data/current_round/live.parquet")# --- 3. Define and run pipeline ---models = [SingleModel("test_assets/joblib_v2_example_model.joblib", model_name="test")]# No preprocessing and 0.5 feature neutralizationpostprocessors = [FeatureNeutralizer(pred_name=f"prediction_test", proportion=0.5)]pipeline = ModelPipeline(preprocessors=[], models=models, postprocessors=postprocessors)dataf = pipeline(dataf)# --- 4. Submit ---# Load credentials from .json (random credentials in this example)key = load_key_from_json("test_assets/test_credentials.json")submitter = NumeraiClassicSubmitter(directory_path="sub_current_round", key=key)# full_submission checks contents, saves as csv and submits.submitter.full_submission(dataf=dataf, cols=f"prediction_test_neutralized_0.5", model_name="test")# --- 5. Clean up environment (optional) ---downloader.remove_base_directory()submitter.remove_base_directory()
💻 Directory structure after submitting
┣━━ 📁 data
┃ ┗━━ 📄 full_data.parquet
┗━━ 📁 sub_current_round
┗━━ 📄 submission.csv
3. Contributing
Be sure to read CONTRIBUTING.md for detailed instructions on contributing.
If you have questions or want to discuss new ideas for numerblox, please create a Github issue first.
4. Branch structure
Every new feature should be implemented in a branch that branches from dev and has the naming convention feature/{FEATURE_DESCRIPTION}. Explicit bugfixes should be named bugfix/{FIX_DESCRIPTION}. An example structure is given below.
Some of the components in this library may be based on forum posts, notebooks or ideas made public by the Numerai community. We have done our best to ask all parties who posted a specific piece of code for their permission and credit their work in the documentation. If your code is used in this library without credits, please let us know, so we can add a link to your article/code.
If you are contributing to numerblox and are using ideas posted earlier by someone else, make sure to credit them by posting a link to their article/code in documentation.