Participate

Two distinct formats of submission are accepted for the competitions:

• Jupyter Notebook (.ipynb), which is a self-contained version of the code

• Python Script (.py), which allows more flexibility and to split the code into multiple files

Jupyter Notebook

Notebook users can use the Quickstarters provided by CrunchDAO to quickly experiment with a working solution that users can tinker with.

Setup

Before trying to execute any cell, users must set up their environment by copying the command available on the competition page:

Run the commands to set up your environment and download the data to be ready to go:

# Upgrade the Crunch-CLI to the latest version
%pip install crunch-cli --upgrade

# Authenticates yourself, it will downloads your last submission and the data
!crunch setup <competition name> <model name> --notebook --token <token>

Learn more about how setup tokens work and if it is safe to leak them.

Users can now load the data locally:

# Load the notebook, run me once
import crunch
crunch = crunch.load_notebook()

# Load the data, re-run me if you corrupt the dataframes
X_train, y_train, X_test = crunch.load_data()

When users are satisfied with their work, they can easily test their implementation:

# Run a local test
crunch.test()

Submit

After testing the code, users need to have access to the .ipynb file.

• If you are on Google Colab: File > Download > Download .ipynb

• If you are on Kaggle: File > Download Notebook

• If you are on Jupyter Lab: File > Download

Then submit on the Submit a Notebook page:

Some model files can also be uploaded along with the notebook, which will be stored in the resources directory.

The notebook is automatically converted to a Python script, keeping only the functions, imports, and classes. Everything else will be commented out.

Specifying package versions

Since submitting a notebook does not include a requirements.txt, users can instead specify the version of a package using import-level requirement specifiers in a comment on the same line.

# Valid statements
import pandas # == 1.3
import sklearn # >= 1.2, < 2.0
import tqdm # [foo, bar]
import scikit # ~= 1.4.2
from requests import Session # == 1.5

Specifying multiple times will cause the submission to be rejected if they are different.

# Inconsistant versions will be rejected
import pandas # == 1.3
import pandas # == 1.5

Specifying versions on standard libraries does nothing (but they will still be rejected if there is an inconsistent version).

# Will be ignored
import os # == 1.3
import sys # == 1.5

If an optional dependency is required for the code to work properly, an import statement must be added, even if the code does not use it directly.

import castle.algorithms

# Keep me, I am needed by castle
import torch

Python Script

Script users can use the Quickstarters provided by CrunchDAO to know what the structure should be.

A mandatory main.py is required to have both functions (train and infer) in order for your code to run properly.

Setup

Before starting to work, users must setup their environment which will be similar to a git repository.

Run the commands to set up your environment and download the data to be ready to go:

# Upgrade the Crunch-CLI to the latest version
$ pip install crunch-cli --upgrade

# Authenticates yourself, it will downloads your last submission and the data
$ crunch setup <competition name> <model name> --token <token> [directory]

# Change the directory to the configured environment
$ cd <directory>

Learn more about how setup tokens work and if it is safe to leak them.

When users are satisfied with their work, they can easily test their implementation:

# Run a local test using a shell command
$ crunch test

Submit

After the code has been tested, the submission needs to be uploaded to the server.

The message is optional and is just a label for users to know what they did.

$ crunch push --message "hello world"

Remember to include all your dependencies in a requirements.txt file.

Setup Tokens

The site generates new tokens every minute, and each token can only be used once within a 3-minute timeframe.

This prevents any problems if your token is accidentally shared, as it will likely have already been used or expired. Even the team shares their expired tokens in Quickstarters.

This token allows the CLI to download the data and submit your submission on your behalf.