numerapi.numerapi module¶

API for Numerai Classic

class numerapi.numerapi.NumerAPI(*args, **kwargs)[source]¶

Bases: Api

Wrapper around the Numerai API

Automatically download and upload data for the Numerai machine learning competition.

This library is a Python client to the Numerai API. The interface is implemented in Python and tournamentallows downloading the training data, uploading predictions, accessing user, submission and competitions information and much more.

daily_model_performances(username: str) → List[Dict][source]¶

Fetch daily performance of a user.

Parameters:

username (str) –

Returns:

list of daily model performance entries

For each entry in the list, there is a dict with the following content:

date (datetime)

corrRep (float or None)

corrRank (int)

mmcRep (float or None)

mmcRank (int)

fncRep (float or None)

fncRank (int)

fncV3Rep (float or None)

fncV3Rank (int)

tcRep (float or None)

tcRank (int)

Return type:

list of dicts

Example

>>> api = NumerAPI()
>>> api.daily_model_performances("uuazed")
[{'corrRank': 485,
 'corrRep': 0.027951873730771848,
 'date': datetime.datetime(2021, 9, 14, 0, 0, tzinfo=tzutc()),
 'fncRank': 1708,
 'fncRep': 0.014548700790462122,
 'tcRank': 1708,
 'tcRep': 0.014548700790462122,
 'fncV3Rank': 1708,
 'fncV3Rep': 0.014548700790462122,
 'mmcRank': 508,
 'mmcRep': 0.005321406467445256},
 ...
]

daily_user_performances(username: str) → List[Dict][source]¶: DEPRECATED

get_competitions(tournament=8)[source]¶

Retrieves information about all competitions

Parameters:

tournament (int, optional) – ID of the tournament, defaults to 8 – DEPRECATED there is only one tournament nowadays

Returns:

list of rounds

Each round’s dict contains the following items:

number (int)

openTime (datetime)

resolveTime (datetime)

resolvedGeneral (bool)

resolvedStaking (bool)

Return type:

list of dicts

Example

>>> NumerAPI().get_competitions()
[
 {'number': 71,
  'openTime': datetime.datetime(2017, 8, 31, 0, 0),
  'resolveTime': datetime.datetime(2017, 9, 27, 21, 0),
  'resolvedGeneral': True,
  'resolvedStaking': True,
 },
  ..
]

get_leaderboard(limit: int = 50, offset: int = 0) → List[Dict][source]¶

Get the current model leaderboard

Parameters:

limit (int) – number of items to return (optional, defaults to 50)
offset (int) – number of items to skip (optional, defaults to 0)

Returns:

list of leaderboard entries

Each dict contains the following items:

username (str)

rank (int)

nmrStaked (decimal.Decimal)

corr20Rep (float)

corj60Rep (float)

fncRep (float)

fncV3Rep (float)

tcRep (float)

mmcRep (float)

bmcRep (float)

team (bool)

return_1_day (float)

return_52_day (float)

return_13_day (float)

Return type:

list of dicts

Example

>>> numerapi.NumerAPI().get_leaderboard(1)
[{'username': 'anton',
  'rank': 143,
  'nmrStaked': Decimal('12'),
  ...
  }]

get_submission_filenames(tournament=None, round_num=None, model_id=None) → List[Dict][source]¶

Get filenames of the submission of the user.

Parameters:

tournament (int) – optionally filter by ID of the tournament – DEPRECATED there is only one tournament nowadays
round_num (int) – optionally filter round number
model_id (str) – Target model UUID (required for accounts with multiple models)

Returns:

list of user filenames (dict)

Each filenames in the list as the following structure:

filename (str)

round_num (int)

tournament (int)

Return type:

list

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> model = api.get_models()['uuazed']
>>> api.get_submission_filenames(3, 111, model)
[{'filename': 'model57-dMpHpYMPIUAF.csv',
  'round_num': 111,
  'tournament': 3}]

get_user(model_id: str | None = None) → Dict[source]¶

Get all information about you! DEPRECATED

Parameters:

model_id (str) – Target model UUID (required for accounts with multiple models)

Returns:

user information including the following fields:

assignedEthAddress (str)

availableNmr (decimal.Decimal)

availableUsd (decimal.Decimal)

banned (bool)

email (str)

id (str)

insertedAt (datetime)

mfaEnabled (bool)

status (str)

username (str)

country (`str)

apiTokens (list) each with the following fields:

name (str)

public_id (str)

scopes (list of str)

v2Stake

status (str)

txHash (str)

Return type:

dict

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> model = api.get_models()['uuazed']
>>> api.get_user(model)
{'apiTokens': [
        {'name': 'tokenname',
         'public_id': 'BLABLA',
         'scopes': ['upload_submission', 'stake', ..]
         }, ..],
 'assignedEthAddress': '0x0000000000000000000000000001',
 'availableNmr': Decimal('99.01'),
 'availableUsd': Decimal('9.47'),
 'banned': False,
 'email': 'username@example.com',
 'country': 'US',
 'id': '1234-ABC..',
 'insertedAt': datetime.datetime(2018, 1, 1, 2, 16, 48),
 'mfaEnabled': False,
 'status': 'VERIFIED',
 'username': 'cool username',
 'v2Stake': None
 }

public_user_profile(username: str) → Dict[source]¶

Fetch the public profile of a user.

Parameters:

username (str) –

Returns:

user profile including the following fields:

username (str)
startDate (datetime)
id (string)
bio (str)
nmrStaked (float)

Return type:

dict

Example

>>> api = NumerAPI()
>>> api.public_user_profile("integration_test")
{'bio': 'The official example model. Submits example predictions.',
 'id': '59de8728-38e5-45bd-a3d5-9d4ad649dd3f',
 'startDate': datetime.datetime(
    2018, 6, 6, 17, 33, 21, tzinfo=tzutc()),
 'nmrStaked': '57.582371875005243780',
 'username': 'integration_test'}

stake_get(modelname: str) → float[source]¶

Get your current stake amount.

Parameters:

modelname (str) –

Returns:

current stake (including projected NMR earnings from open: rounds)

Return type:

float

Example

>>> api = NumerAPI()
>>> api.stake_get("uuazed")
1.1

stake_set(nmr, model_id: str) → Dict[source]¶

Set stake to value by decreasing or increasing your current stake

Parameters:

nmr (float or str) – amount of NMR you want to stake
model_id (str) – model_id for where you want to stake

Returns:

stake information with the following content:

insertedAt (datetime)

status (str)

txHash (str)

value (decimal.Decimal)

source (str)

to (str)

from (str)

posted (bool)

Return type:

dict

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> api.stake_set(10)
{'from': None,
 'insertedAt': None,
 'status': None,
 'txHash': '0x76519...2341ca0',
 'from': '',
 'to': '',
 'posted': True,
 'value': '10'}

submission_status(model_id: str | None = None) → None[source]¶

submission status of the last submission associated with the account

DEPRECATED numerai no longer provides this data. This will be removed in one of the next versions

Parameters:: model_id (str) – Target model UUID (required for accounts with multiple models)

Example

>>> napi = NumerAPI(secret_key="..", public_id="..")
>>> model_id = napi.get_models()['uuazed']
>>> napi.submission_status(model_id)

Upload predictions from file. Will read TRIGGER_ID from the environment if this model is enabled with a Numerai Compute cluster setup by Numerai CLI.

Parameters:

file_path (str) – CSV file with predictions that will get uploaded
tournament (int) – ID of the tournament (optional, defaults to 8) – DEPRECATED there is only one tournament nowadays
model_id (str) – Target model UUID (required for accounts with multiple models)
df (pandas.DataFrame) – pandas DataFrame to upload, if function is given df and file_path, df will be uploaded.
data_datestamp (int) – Data lag, in case submission is done using data from the previous day(s).
timeout (float|tuple(float,float)) – waiting time (connection timeout, read timeout)

Returns:

submission_id

Return type:

str

Example

>>> api = NumerAPI(secret_key="..", public_id="..")
>>> model_id = api.get_models()['uuazed']
>>> api.upload_predictions("prediction.cvs", model_id=model_id)
'93c46857-fed9-4594-981e-82db2b358daf'
>>> # upload from pandas DataFrame directly:
>>> api.upload_predictions(df=predictions_df, model_id=model_id)