Python bindings for the ClearMacro API
Project description
ClearMacro
The ClearMacro Python library provides convenient access to the ClearMacro API from applications written in the Python language. It includes a pre-defined set of methods that make it simple to start interacting with the API.
Installation
To use the package, run:
pip install --upgrade cmqd
Examples
Selection of examples; a reference point of getting started.
// Instantiate a client
>>> from clearmacro import Client
>>> config = {'url': '<HOST HERE>', 'username': '<EMAIL HERE>', 'password': '<PASSWORD HERE>'}
>>> client = Client(**config)
// Get the catalogue
>>> catalogue = client.get_signals_catalogue()
// Consume it as a DataFrame
>>> client.json_to_df(catalogue)
signalId name description universe category
0 8 Crossborder Flow Crossborder Flow Economics Credit
1 9 Crossborder Private Liquidity Crossborder Private Liquidity Economics Credit
2 10 Crossborder Policy Sector Crossborder Policy Sector Economics Credit
3 11 Crossborder Monetized Savings Crossborder Monetized Savings Economics Inflation
...
// Get the markets for which a certain signal is available.
>>> markets_for_my_signal = client.get_markets_for_signal('Bond Valuation Score IHS')
// Consume as DataFrame
>>> client.json_to_df(markets_for_my_signal)
classId name marketCategory
0 86 Australia Country
1 87 Austria Country
2 88 Belgium Country
3 89 Brazil Country
4 90 Canada Country
...
// Request a certain signal series
>>> series = client.get_signal_series(signal='Crossborder Flow', market='US', research_type='Back-test Level', last_date_only=False, start_date='2016-1-1', end_date='2020-10-16')
// Consume it as a DataFrame
>>> client.json_to_df(series)
dateTimes values
0 2016-01-29T23:59:59.99 5.485577
1 2016-02-29T23:59:59.99 5.974441
2 2016-03-31T23:59:59.99 6.388535
3 2016-04-29T23:59:59.99 6.714286
4 2016-05-31T23:59:59.99 6.340190
5 2016-06-30T23:59:59.99 5.599369
6 2016-07-29T23:59:59.99 4.792453
7 2016-08-31T23:59:59.99 3.793103
8 2016-09-30T23:59:59.99 3.207812
9 2016-10-31T23:59:59.99 3.046729
10 2016-11-30T23:59:59.99 3.375776
11 2016-12-30T23:59:59.99 3.981424
...
// If there is no such series, get an exception which can be handled:
>>> client.get_signal_series('Random signal', 'Random market', 'Random research type')
ValueError: Invalid input.
// Request data with a certain frequency e.g. weekly data on Wednesdays.
>>> wedDataSeries = client.get_signal_series('Country Valuation Score TR', 'Germany', 'Back-test Momentum', frequency_key = 'W-WED')
// Consume it as a DataFrame
>>> client.json_to_df(wedDataSeries)
dateTimes values
0 1995-02-15T23:59:59.99 4.449885
1 1995-02-22T23:59:59.99 5.507832
2 1995-03-01T23:59:59.99 5.042825
3 1995-03-08T23:59:59.99 6.214902
4 1995-03-15T23:59:59.99 6.647544
...
Full Python Docstrings
Documentation for each method of the Client class:
get_signals_catalogue()
"""
Function to retrieve the list of all signals.
Returns:
JSON list of signal objects.
"""
get_all_markets()
"""
Function to retrieve the list of all markets.
Returns:
JSON list of market objects.
"""
get_signal_universes()
"""
Function to retrieve the signal universes.
Returns:
JSON list of universe objects.
"""
get_categories_for_universe(universe: str)
"""
Function to retrieve the list of categories corresponding to the passed universe.
Args:
universe (str): One of the signal universes. Available options are the "name" fields from the list of universe objects obtained by calling the get_signal_universes method.
Returns:
JSON list of category objects.
"""
get_categories_for_universe_id(universe_id: int)
"""
Function to retrieve the list of categories corresponding to the passed universe id.
Args:
universe_id (int): One of the signal universes. Available options are the "universeId" fields from the list of universe objects obtained by calling the get_signal_universes method.
Returns:
JSON list of category objects.
"""
get_signals_for_universe_cat_pair(universe: str, category: str)
"""
Function to retrieve all signals belonging to the given universe, category pair.
Args:
universe (str): One of the signal universes. Available options are the "name" fields from the list of universe objects obtained by calling the get_signal_universes method.
category (str): One of the categories of the above universe. Available options are the "name" fields from the list of category objects obtained by calling get_categories_for_universe(universe).
Returns:
JSON list of signal objects.
"""
get_signals_for_universe_cat_pair_id(universe_id: int, category_id: int)
"""
Function to retrieve all signals belonging to the given universe, category pair by id.
Args:
universe_id (int): One of the signal universes. Available options are the "universeId" fields from the list of universe objects obtained by calling the get_signal_universes method.
category_id (int): One of the categories of the above universe. Available options are the "categoryId" fields from the list of category objects obtained by calling get_categories_for_universe_id(universe_id).
Returns:
JSON list of signal objects.
"""
get_market_categories()
"""
Function to retrieve the list of all market categories.
Returns:
JSON list of market category objects.
"""
get_markets_for_market_cat(market_category: str)
"""
Function to retrieve the list of markets corresponding to the passed market category.
Args:
market_category (str): One of the market categories. Available options are the "name" fields from the list of market category objects obtained by calling the get_market_categories method.
Returns:
JSON list of market objects.
"""
get_markets_for_market_cat_id(market_category_id: int)
"""
Function to retrieve the list of markets corresponding to the passed market category id.
Args:
market_category_id (int): One of the market categories. Available options are the "marketCategoryId" fields from the list of market category objects obtained by calling the get_market_categories method.
Returns:
JSON list of market objects.
"""
get_markets_for_signal(signal: str)
"""
Function to retrieve the list of markets corresponding to the passed signal.
Args:
signal (str): One of the signals. Available options are the "name" fields from the list of signals objects obtained by calling the get_signals_catalogue method.
Returns:
JSON list of market objects.
"""
get_markets_for_signal_id(signal_id: int)
"""
Function to retrieve the list of markets corresponding to the passed signal id.
Args:
signal_id (int): One of the signals. Available options are the "signalId" fields from the list of signals objects obtained by calling the get_signals_catalogue method.
Returns:
JSON list of market objects.
"""
get_signals_for_market(market: str)
"""
Function to retrieve the list of signals available for the given market.
Args:
market (str): One of the valid markets. Available options are the "name" fields from the list of market objects obtained by calling the get_all_markets method.
Returns:
JSON list of signal objects.
"""
get_signals_for_market_id(class_id: int)
"""
Function to retrieve the list of signals available for the given market.
Args:
class_id (int): One of the valid markets. Available options are the "classId" fields from the list of market objects obtained by calling the get_all_markets method.
Returns:
JSON list of signal objects.
"""
get_research_types_for_signal_market_pair(signal: str, market: str)
"""
Function to retrieve the list of research types corresponding to the passed signal and market.
Args:
signal (str): One of the signals. Available options are the "name" fields from the list of signal objects obtained by calling the get_signals_catalogue method.
market (str): One of the valid markets for the above signal. Available options are the "name" fields from the list of market objects obtained by calling the get_markets_for_signal(signal) method.
Returns:
JSON list of research type objects.
"""
get_research_types_for_signal_market_pair_id(signal_id: int, market_id: int)
"""
Function to retrieve the list of research types corresponding to the passed signal id and market id.
Args:
signal_id (int): One of the signals. Available options are the "signalId" fields from the list of signal objects obtained by calling the get_signals_catalogue method.
market_id (int): One of the valid markets for the above signal. Available options are the "classId" fields from the list of market objects obtained by calling the get_markets_for_signal_id(signal_id) method.
Returns:
JSON list of research type objects.
"""
get_signal_series(
signal: str,
market: str,
research_type: str,
last_date_only=False,
start_date=None,
end_date=None,
frequency_key=None,
)
"""
Function to retrieve a signal time series.
Args:
signal (str): Options are "name" fields from list of signal objects returned by get_signals_catalogue.
market (str): Options are "name" fields from list of market objects returned by get_markets_for_signal(signal).
research_type (str): Options are "name" fields from list of research type objects returned by get_research_types_for_signal_market_pair(signal, market).
last_date_only (bool, optional): Flag indicating if only the last date of the time series is desired.
start_date (str, optional): Start date of the series in ISO format YYYY-MM-DD.
end_date (str, optional): End date of the series in ISO format YYYY-MM-DD.
frequency_key (str): One of the desired frequencies (None is for all values available, undetermined frequency):
D, (Daily - all days)
WD, (Weekdays)
W_MON, (Weekly data on Mondays)
W_TUE, (Weekly data on Tuesdays)
W_WED, (Weekly data on Wednesdays)
W_THU, (Weekly data on Thursdays)
W_FRI, (Weekly data on Fridays)
W_SAT, (Weekly data on Saturdays)
W_SUN, (Weekly data on Sundays)
M, (Monthly data - end of month)
MS, (Monthly data - start of month)
Q, (Quarterly data - end of quarter)
QS (Quarterly data - start of quarter)
Examples:
>>> client.get_signal_series('Crossborder Flow', 'US', 'Back-test Level', last_date_only=False, start_date='2016-1-1', end_date='2020-10-16')
Returns:
Time series object.
"""
get_signal_series_id(
signal_id: int,
market_id: int,
research_type_id: int,
last_date_only=False,
start_date=None,
end_date=None,
frequency_key=None
)
"""
Function to retrieve a signal time series by ids.
Args:
signal_id (int): Options are "signalId" fields from list of signal objects returned by get_signals_catalogue.
market_id (int): Options are "classId" fields from list of market objects returned by get_markets_for_signal_id(signal_id).
research_type_id (int): Options are "researchTypeId" fields from list of research type objects returned by get_research_types_for_signal_market_pair_id(signal_id, market_id).
last_date_only (bool): Flag indicating if only the last date of the time series is desired.
start_date (str): Start date of the series in ISO format YYYY-MM-DD.
end_date (str): End date of the series in ISO format YYYY-MM-DD.
frequency_key (str): One of the desired frequencies (None is for all values available, undetermined frequency):
D, (Daily - all days)
WD, (Weekdays)
W_MON, (Weekly data on Mondays)
W_TUE, (Weekly data on Tuesdays)
W_WED, (Weekly data on Wednesdays)
W_THU, (Weekly data on Thursdays)
W_FRI, (Weekly data on Fridays)
W_SAT, (Weekly data on Saturdays)
W_SUN, (Weekly data on Sundays)
M, (Monthly data - end of month)
MS, (Monthly data - start of month)
Q, (Quarterly data - end of quarter)
QS (Quarterly data - start of quarter)
Examples:
>>> client.get_signal_series_id(8, 137, 94, last_date_only=False, start_date='2016-1-1', end_date='2020-10-16')
Returns:
Time series object.
"""
json_to_df(json)
"""
Function to convert JSON/JSON list to a pandas.DataFrame object.
Args:
json: The JSON to be converted - this is the format all methods return.
Returns:
The data contained in the JSON cast as a DataFrame.
If the data is a time series, the dataframe will be indexed by datetimes and there
will be a 'values' column containing the value corresponding to each DateTimeIndex.
"""
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
cmqd-1.0.4.tar.gz
(14.4 kB
view hashes)
Built Distribution
cmqd-1.0.4-py2.py3-none-any.whl
(20.7 kB
view hashes)
