# -*- coding: utf-8 -*-
from setuptools import setup

packages = \
['braincube_connector',
 'braincube_connector.bases',
 'braincube_connector.data',
 'braincube_connector.memory_base',
 'braincube_connector.memory_base.nested_resources']

package_data = \
{'': ['*']}

install_requires = \
['requests>=2.23.0,<3.0.0']

setup_kwargs = {
    'name': 'braincube-connector',
    'version': '2.0.2',
    'description': 'python client to the braincube web services',
    'long_description': '# braincube_connector: a python client for Braincube\n\n## Description\n\nThe python package `braincube_connector` provides a tool for datascientists to access their data on Braincube directly from python.\n\n## Installation\n\nInstall with pip:\n\n```bash\npip install braincube_connector\n```\n\n## Usage\n\n### Client\n\nA client can be inialized manually from a custom configuration file.\n\n```python\nfrom braincube_connector import client\n\nclient.get_instance(config_file="pathto/config.json")\n```\n\n**Note:** If the client is not initialized manually, the package creates a client instance from one of these two files `./config.json`  or `~/.braincube/config.json` (in this priority order) if they exist.\n\n\n### Braincube\n\nTo obtain a list of all the available `Braincube` entities with a client:\n```python\nfrom braincube_connector import braincube\n\nbraincube.get_braincube_list()\n```\n\nOr to select a specific `Braincube` entity from its name:\n```python\nbc = braincube.get_braincube("demo")\n```\n\n### MemoryBase\n\nThe list of all the memory bases available within a `Braincube` is obtained with\n\n```python\nmb_list = bc.get_memory_base_list()\n```\n\n**Note:** The number of memory bases in a braincube can be numerous,  hence `get_memory_base_list` allows paginated requests `bc.get_memory_base_list(page=0)`\n\nTo select a unique memory base, go with its bcId:\n\n```python\nmb_list = bc.get_memory_base(20)\n```\n\n\n### VariableDescriptions\n\nThe variable description are linked to a memory base.\n\n```python\nvar_desc = mb.get_variable(bcid="2000034")\n```\n\nFor multiple variable descriptions:\n\n```python\nmb.get_variable_list(page=0)\n```\n\n**Note:** Similarly to memory bases, providing no argument to `get_variable_list` retrieves all the descriptions available in the memory base.\n\nThe type of variable is obtained with the function `get_type`\n\n```python\nvar_desc.get_type()\n```\n\n### DataGroup\nDataGroup are obtained from a memory base:\n```python\ndatagroup = mb.get_datagroup(bcid="10")\n```\nThe list of the available datagroups can also be obtained with `mb.get_datagroup_list()`.\n\nA datagroup is a container that includes multiple variables. They are accessed with\n```python\ndatagroup.get_variable_ids() # Gets the variable bcIds\ndatagroup.get_variable_list() # Gets the list of VariableDescription objects.\n```\n\n### Event\nAn event is a predifined set of conditions in braincube. It is accessed as follows:\n```python\nevent = mb.get_event(bcid="10")\nevent_list = mb.get_event_list()\n```\n\nThe interest of events is that you can access the conditions they contain in order create new [filters](#data-filters) for a `get_data` function:\n\n```python\nevent.get_conditions()\n```\n\n### JobDescription\n\nThe job desciption contains the settings used to build an analysis and gives a proxy to access these parameters easily. A JobDescription is obtained from a memory base as follows:\n\n```python\njob_desc = mb.get_job(bcid="573")\njob_list = mb.get_job_list(page=0)\n```\n\nThe properties are acced with the following methods:  \n\n- **get_conditions:**  \n  Gets a list of the conditions used to select the job variables.\n  ```python\n  job_desc.get_conditions()\n  job_desc.get_conditions(combine=True) # Merge the conditions into one\n  job_desc.get_conditions(include_events=True) # Includes the conditions from\n                                               # the job\'s events\n  ```\n\n- **get_variable_ids:**  \n  Gets a list of the variables involved in the job, including the target variables and the influence variables.\n  ```python\n  job_desc.get_variable_ids()\n  ```\n\n- **get_events:**  \n  Gets a list of the event objects used by the job.\n  ```python\n  job_desc.get_events()\n  ```\n- **get_categories:**  \n  Gets a list of conditions used to categorise a job\'s data as *good* or *bad*. You may have a *middle* category, it\'s an old categorisation which will not be used anymore.\n  ```python\n  job_desc.get_categories()\n  ```\n\n- **get_data:**  \n  When a job is created on braincube, a separate copy of the data is made. As for now this copy is not available from the webservices. However the `get_data` method collects the job\'s data from the memory base using the same filters as when the job was created. Be aware that these data might be different from the job\'s data if the memory base has been updated since the job creation.  \n\n  Similarly to other object `get_data`, a `filters` parameter is available to add additional [filters](#data-filters) to the job\'s conditions.\n\n  ```python\n  job_desc.get_data()\n  ```\n\n### Job rules\nThe job rule descriptions are obtained with the methods `get_rule` or `get_rule_list` either from a job or a memory base. The only difference being that in the case of a memory base `get_rule_list` gets all the rules existing in the memory base whereas for a job, it gets the rules specific to the job under consideration.\n\n```python\nrule = job.get_rule(bcid="200")\nrule_list = job.get_rule_list()\n```\n\nTo access a `RuleDescription` object\'s metadata, you can calle the `get_metadata` function\n```python\nrule.get_metadata()\n```\n\n\n### Get variable data\n\nA memory base can also request the data for a custom set of variable ids. Adding [filters](#data-filters) restricts the returned data to a desired subset of the data. The method is called as follows:\n```python\ndata = mb.get_data(["2000001", "2000034"], filters=my_filters)\n```\n\nThe output format is a dictionary in which the keys are the variable bcIds and the value a list of data. This allows an easy conversion to a pandas dataframe:\n\n```python\nimport pandas as pd\n\ndf = pd.DataFrame(data)\n```\n\n**Note:** By default the dates are not parsed to `datetime` objects in order to speed up the `get_data` function but it is possible to enable the parsing:\n```python\nfrom braincube_connector import parameters\nparameters.set_parameter({"parse_date": True})\n```\n\n### Data filters\nThe `get_data` methods have the option to restrict the data that are collected by using a set of filters. The `filters` parameter must be a list conditions (even for a single condition):\n```python\nobject.get_data(filters=[{"BETWEEN",["mb20/d2000002",0,10]},{"BETWEEN",["mb20/d2000003", -1, 1]}])\n```\n\nHere is a selection of the most common types of filters:\n- **Equals to**  \n  Selects data when a variable is equal to\n  ```json\n  {\n    "EQUALS": [ "mb20/d2000002", 2.0]\n  }\n  ```\n- **Between**  \n  Selects the data when a variable belongs to a range.\n  ```json\n  {\n    "BETWEEN": [ "mb20/d2000003", -1, 1]\n  }\n  ```\n- **Lower than**  \n  Selects the data when a variable is lower than a certain value.\n  ```json\n  {\n    "LESS": [ "mb20/d2000003", 10]\n  }\n  ```\n  **Note:** The `LESS_EQUALS` filter also exists.\n\n\n- **Greater than**  \n  Selects the data when a variable is greater than a certain value.\n  ```json\n  {\n    "GREAT": [ "mb20/d2000003", 10]\n  }\n  ```\n  **Note:** The `GREAT_EQUALS` filter also exists.\n\n- **Not:**  \n  The `NOT` condition creates the opposite of an existing condition.\n  ```json\n  {\n    "Not": [{"filter":...}]\n  }\n  ```\n\n- **And gate**  \n  It is possible to combine filters using a *and* gate.\n  ```json\n  {\n    "AND": [{"filter1":...}, {"filter2":...}]\n  }\n  ```\n  **Notes:**  \n    - A `AND` filter can only host two conditions. In order to join more than two filters multiple `AND` conditions should be nested one into another.\n    - When multiple filters are provided in the `get_data`\'s `filters` parmeters, they are joined together within the function using `AND` gates.  \n\n- **Or gate:**  \n  Similar to `AND` but uses a `OR` gate.\n  ```json\n  {\n    "OR": [{"filter1":...}, {"filter2":...}]\n  }\n  ```\n\n## Library parameters\nThe library parameters can be set to custom values:\n\n```python\nfrom braincube_connector import parameters\n\n# Change the request pagination size to 10\nparameters.set_parameter({"page_size": 10})\n\n# Parse dates to datetime objects\nparameters.set_parameter({"parse_date": True})\n```\n\n\n## Configuration\n\nIn order to connect to the web service, the client needs a Oauth2 token saved in a configuration file. For simplicity it is recommended to use a helper [braincube-token-getter](https://pypi.org/project/braincube-token-getter/) to get the token and to setup the configuration file as follows:\n\n`config.json`\n\n```json\n{\n    "client_id": "app id",\n    "client_secret": "app key",\n    "domain": "mybraincube.com",\n    "verify": true,\n    "oauth2_token": "token value"\n}\n```\nThe `token-getter` script saves the configuration in the `~/.braincube/config.json` file by default.\n',
    'author': 'Braincube',
    'author_email': 'io@braincube.com',
    'maintainer': None,
    'maintainer_email': None,
    'url': None,
    'packages': packages,
    'package_data': package_data,
    'install_requires': install_requires,
    'python_requires': '>=3.6,<4.0',
}


setup(**setup_kwargs)
