python client to the braincube web services
Project description
braincube_connector: a python client for Braincube
Description
The python package braincube_connector
provides a tool for datascientists to access their data on Braincube directly from python.
Installation
Install with pip:
pip install braincube_connector
Usage
Client
A client can be inialized manually from a custom configuration file.
from braincube_connector import client
client.get_instance(config_file="pathto/config.json")
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.
Braincube
To obtain a list of all the available Braincube
entities with a client:
from braincube_connector import braincube
braincube.get_braincube_list()
Or to select a specific Braincube
entity from its name:
bc = braincube.get_braincube("demo")
MemoryBase
The list of all the memory bases available within a Braincube
is obtained with
mb_list = bc.get_memory_base_list()
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)
To select a unique memory base, go with its bcId:
mb_list = bc.get_memory_base(20)
VariableDescriptions
The variable description are linked to a memory base.
var_desc = mb.get_variable(bcid="2000034")
For multiple variable descriptions:
mb.get_variable_list(page=0)
Note: Similarly to memory bases, providing no argument to get_variable_list
retrieves all the descriptions available in the memory base.
The type of variable is obtained with the function get_type
var_desc.get_type()
DataGroup
DataGroup are obtained from a memory base:
datagroup = mb.get_datagroup(bcid="10")
The list of the available datagroups can also be obtained with mb.get_datagroup_list()
.
A datagroup is a container that includes multiple variables. They are accessed with
datagroup.get_variable_ids() # Gets the variable bcIds
datagroup.get_variable_list() # Gets the list of VariableDescription objects.
Event
An event is a predifined set of conditions in braincube. It is accessed as follows:
event = mb.get_event(bcid="10")
event_list = mb.get_event_list()
The interest of events is that you can access the conditions they contain in order create new filters for a get_data
function:
event.get_conditions()
JobDescription
The 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:
job_desc = mb.get_job(bcid="573")
job_list = mb.get_job_list(page=0)
The properties are acced with the following methods:
-
get_conditions:
Gets a list of the conditions used to select the job variables.job_desc.get_conditions() job_desc.get_conditions(combine=True) # Merge the conditions into one job_desc.get_conditions(include_events=True) # Includes the conditions from # the job's events
-
get_variable_ids:
Gets a list of the variables involved in the job, including the target variables and the influence variables.job_desc.get_variable_ids()
-
get_events:
Gets a list of the event objects used by the job.job_desc.get_events()
-
get_categories:
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.job_desc.get_categories()
-
get_data:
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 theget_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.Similarly to other object
get_data
, afilters
parameter is available to add additional filters to the job's conditions.job_desc.get_data()
Job rules
The 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.
rule = job.get_rule(bcid="200")
rule_list = job.get_rule_list()
To access a RuleDescription
object's metadata, you can calle the get_metadata
function
rule.get_metadata()
Get variable data
A memory base can also request the data for a custom set of variable ids. Adding filters restricts the returned data to a desired subset of the data. The method is called as follows:
data = mb.get_data(["2000001", "2000034"], filters=my_filters)
The 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:
import pandas as pd
df = pd.DataFrame(data)
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:
from braincube_connector import parameters
parameters.set_parameter({"parse_date": True})
Data filters
The 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):
object.get_data(filters=[{"BETWEEN",["mb20/d2000002",0,10]},{"BETWEEN",["mb20/d2000003", -1, 1]}])
Here is a selection of the most common types of filters:
-
Equals to
Selects data when a variable is equal to{ "EQUALS": [ "mb20/d2000002", 2.0] }
-
Between
Selects the data when a variable belongs to a range.{ "BETWEEN": [ "mb20/d2000003", -1, 1] }
-
Lower than
Selects the data when a variable is lower than a certain value.{ "LESS": [ "mb20/d2000003", 10] }
Note: The
LESS_EQUALS
filter also exists. -
Greater than
Selects the data when a variable is greater than a certain value.{ "GREAT": [ "mb20/d2000003", 10] }
Note: The
GREAT_EQUALS
filter also exists. -
Not:
TheNOT
condition creates the opposite of an existing condition.{ "Not": [{"filter":...}] }
-
And gate
It is possible to combine filters using a and gate.{ "AND": [{"filter1":...}, {"filter2":...}] }
Notes:
- A
AND
filter can only host two conditions. In order to join more than two filters multipleAND
conditions should be nested one into another. - When multiple filters are provided in the
get_data
'sfilters
parmeters, they are joined together within the function usingAND
gates.
- A
-
Or gate:
Similar toAND
but uses aOR
gate.{ "OR": [{"filter1":...}, {"filter2":...}] }
Library parameters
The library parameters can be set to custom values:
from braincube_connector import parameters
# Change the request pagination size to 10
parameters.set_parameter({"page_size": 10})
# Parse dates to datetime objects
parameters.set_parameter({"parse_date": True})
Configuration
In 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 to get the token and to setup the configuration file as follows:
config.json
{
"client_id": "app id",
"client_secret": "app key",
"domain": "mybraincube.com",
"verify": true,
"oauth2_token": "token value"
}
The token-getter
script saves the configuration in the ~/.braincube/config.json
file by default.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for braincube-connector-2.0.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9609dc58ad0c19d6a8fc3782d3799b60aacc234cbba6e79cc4207bef17534816 |
|
MD5 | 387d4e2917829f8e53f53d4b36b2791c |
|
BLAKE2b-256 | da40c1122ad2aa589675e87bc257810d4c693cac8ed2533557de391b7cbdce56 |
Hashes for braincube_connector-2.0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0a27e5b973c73aff1976b175f1be847f99f8f3146f15fca4535fc0a71dfff9ae |
|
MD5 | d7eb2d5ab31e8c5d40e76381c601eef6 |
|
BLAKE2b-256 | 6f0cf0739ae0a29f2ff4775b2a4b9a33ce17c112b6e47e575a60119251accb77 |