Metadata-Version: 2.1
Name: cmqd
Version: 1.0.2
Summary: Python bindings for the ClearMacro API
Home-page: https://github.com/cmqd/cm-api-python-sdk
Author: ClearMacro
Author-email: support@clearmacro.com
License: MIT
Project-URL: Bug Tracker, https://github.com/cmqd/cm-api-python-sdk/issues
Project-URL: Documentation, https://github.com/cmqd/cm-api-python-sdk
Project-URL: Source Code, https://github.com/cmqd/cm-api-python-sdk
Description: # ClearMacro <!-- omit in toc -->
        
        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](#installation)
        - [Examples](#examples)
        - [Full Docstrings](#full-python-docstrings)
        ## Installation
        To use the package, run:
        ```sh
        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.
        """
        ```
Keywords: cmqd clearmacro python api sdk
Platform: UNKNOWN
Description-Content-Type: text/markdown
