Metadata-Version: 2.4
Name: data-liberator
Version: 0.1.0
Summary: CloudQuant Liberator Python client
License: MIT
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: pandas
Requires-Dist: pyarrow
Requires-Dist: pyOpenSSL
Requires-Dist: cryptography
Requires-Dist: six
Requires-Dist: pytz
Provides-Extra: fast
Requires-Dist: httpx; extra == "fast"
Provides-Extra: charting
Requires-Dist: plotly; extra == "charting"
Requires-Dist: numpy; extra == "charting"
Requires-Dist: TA-Lib; extra == "charting"

# liberator query examples for python3
## environment setup
- from CloudQuant sale/support rep:
  - obtain `liberator.json` containing your user and token values
  - obtain `liberator.pfx` containing your TLS certificate
- install prerequisites:
  - python 3.6 (3.x may work)
  - and `conda install requests pandas pyarrow`
  - or `pip install requests pandas pyarrow`
  - ...and `pyOpenSSL` module on Windows
  - cloudquant charting requires additonaly dependency `conda install plotly`

## simple usage (liberator.py)
```
import liberator
help(liberator) # check that pfx and auth are pointing to .pfx/.json files
```
```
import json
import liberator
# get dataset list
print(json.dumps(liberator.datasets(),indent=4))
```
```
import liberator
# get record count by symbol
print(liberator.get_dataframe(liberator.query(name='Minute Bars',symbols=['AAPL','GOOGL'],stats='total')))
```
```
import liberator
# get total record count of proposed query
print(liberator.get_dataframe(liberator.query(name='Minute Bars',symbols=['AAPL','GOOGL'],stats='total'))['count'].sum())
```
```
import liberator
# get time-sorted pandas dataframe
print(liberator.get_dataframe(liberator.query(name='Minute Bars',symbols=['AAPL','GOOGL'])))
```
```
import liberator
# process a large result one batch at a time (may be unsorted)
for res in liberator.query(name='Minute Bars',symbols=['AAPL','GOOGL']):
    # res is an Apache Arrow RecordBatch
    print(res.to_pandas())
```
## under the hood example, useful for porting or coding to protocol
.pfx must be in working directory
```
LIBERATOR_USER=your_user \
    LIBERATOR_TOKEN=your_token \
    python under-the-hood.py 
```

# cloudquantcharting - Standard CQ Charting tools

## help(cloudquantcharting)
Prints out the help text for CloudQuantCharting

## Histogram(**kwargs)
The Histogram function will generate a chart distribution/histogram chart
that is branded with CloudQuant logo and colors.

### Required Keyword Arguments

* "df" = the pandas data frame with the data you want to graph
* "col" = (string) dataframe column name you wish to graph

### Optional Keyword Arguments

* "title" = (string) The title at the top of the chart. title can contain some html tags like ``` <b></b><i></i> and <br>.  ```
    * note: not all html tags are supported.
* "xlabel" = (string) the label for the x axis. xlabel can contain some html tags like ```<b></b> and <i></i>```
* "ylabel" = (string) the label for the y axis. ylabel can contain some html tags like ```<b></b> and <i></i>```
* "histnorm" = (string)  One of 'percent', 'probability',  'density', or 'probability density'. 
    If None, the output of histfunc is used as is.
    If 'probability', the output of histfunc for a given bin
    is divided by the sum of the output of histfunc for all bins.
    If 'percent', the output of histfunc for a given bin is divided 
    by the sum of the output of histfunc for all bins and multiplied by 100. 
    If 'density', the output of histfunc for a given bin is divided by the 
    size of the bin. If 'probability density', the output of histfunc 
    for a given bin is normalized such that it corresponds to the 
    probability that a random event whose distribution is described 
    by the output of histfunc will fall into that bin.
* "width" = Horizontal size (in px). Defaults to 800. Cannot be less than 400
* "height" = Vertical size (in px) . Defaults to 800. Cannot be less than 400

**Charting overlays of another series - Optional**
    * note: it is a good idea to rename the overlay_col to a name that looks better visually
* "overlay_df" = the pandas data frame with the data you compare in the graph
* "overlay_col" = (string) dataframe column name you wish to compare in graph

## Candlestick(**kwargs)
The Candlestick function will generate a Candlestick chart
that is branded with CloudQuant logo and colors.

### Required Keyword Arguments 
* "df" = the pandas data frame with the OHLC data you want to graph
    This is typically a liberator query for "Daily Bars" or "Minute Bars"
    * NOTE: the data frame must have at least 20 bars of data

### Optional Keyword Arguments
* "title" = (string) The title at the top of the chart.
    title can contain some html tags like 
    ```<b></b><i></i> and <br>.```
    * note: not all html tags are supported.
* "xlabel" = (string) the label for the x axis.
    xlabel can contain some html tags like 
    ```<b></b> and <i></i>```
    defaults to "Time (EST - New York)"
* "ylabel" = (string) the label for the y axis.
    ylabel can contain some html tags like 
    ```<b></b> and <i></i>```
    defaults to "Price $ - US Dollars"
* "width" = Horizontal size (in px). Defaults to 800. Cannot be less than 700
* "height" = Vertical size (in px) . Defaults to 800. Cannot be less than 400
* "open" = the name of the open column. Defaults to "open"
* "high" = the name of the high column. Defaults to "high"
* "low" = the name of the low column. Defaults to "low"
* "close" = the name of the close column. Defaults to "close"
* "timestamp" = the name of the timestamp or date column. Defaults to "timestamp"

### Showing a trade (must be round turn with both entry and exit values)
* "entry_px" = numeric entry price
* "entry_time" = timestamp of the entry trade
* "close_px" = numeric closing price
* "close_time" = timestsamp of the closing trade
* "entry_side" = The entry action "b" = buy or "s" = sell
        Entry side is used to compute the color for the shown trade.

### Secondary Y Axis - To overlay a signal
* "overlay_df" = the pandas data frame with the data you compare in the graph
* "overlay_col" = (list) or (string) the list of column names or the single
    dataframe column name you wish to compare in graph. These will appear
    as thin solid lines on the graph.
    
    note: line names will use the column names in the legend

    note: all secondary axis values should be in the same numeric 
           range otherwise the secondary axis will be useless.
* "overlay_col2" = (list) or (string) the list of column names or the single
     dataframe column name you wish to compare in graph. These will appear
     as thin dashed lines on the graph.
    
    note: line names will use the column names in the legend

    note: all secondary axis values should be in the same numeric 
      range otherwise the secondary axis will be useless.
### Studies 
**Important Note for Studies.**
If you request Studies you MAY receive more than one figure in your 
return set. Some studies return a second line chart. See the supported
studies section below.

A good example of coding for variable types of output from this function is:
```
       res = Candlestick(df=df, study=MyStudy, study_columns=[ "high", "low", "close", "volume"])
       if isinstance(res, list):
           for f in res:
               f.show(renderer="png")
       else:
           res.show(renderer="png")
```    

* "study" = Name of the study - See list of supported studies
* "study_columns" = column names list from the dataframe specified in "df" 
            to perform the study upon in order. Defaults to ["close"]
      
* "timeperiod" = the number of time periods in the study

                
**Supported Studies That return ONE FIGURE**
``` 
    "BBANDS":"Bollinger Bands",  - Arguments = close
    "DEMA":"2x Exponential MA",  - Arguments = close
    "EMA":"Exponential MA",  - Arguments = close
    "HT_TRENDLINE":"Hilbert Transform",  - Arguments = close
    "KAMA":"Kaufman MA",  - Arguments = close
    "MA":"Moving average",  - Arguments = close
    "MAMA":"MESA Adaptive MA",  - Arguments = close
    "MIDPOINT":"MidPoint",  - Arguments = close
    "MIDPRICE":"Midpoint Price",   - Arguments = high, low
    "SAR":"Parabolic SAR",   - Arguments = high, low
    "SAREXT":"Parabolic SAR Ext",   - Arguments = high, low
    "SMA":"Simple MA",  - Arguments = close
    "T3":"T3 Moving Average",  - Arguments = close
    "TEMA":"T3 Exponential MA",  - Arguments = close
    "TRIMA":"Triangular MA",  - Arguments = close
    "WMA":"Weighted MA",  - Arguments = close
```
**Supported Studies That return AN ARRAY of FIGURES**
```
    "ADX":"Avg Dir Move Index",   - Arguments = high, low, close 
    "ADXR":"AvgDir MoveIdx Rating",   - Arguments = high, low, close 
    "APO":"ABS PX Oscillator",   - Arguments = close
    "AROON":"Aroon",   - Arguments = high, low
    "AROONOSC":"Aroon Oscillator",   - Arguments = high, low
    "BOP":"Balance Of Power",    - Arguments = open, high, low, close 
    "CCI":"Cmdty Channel Idx",   - Arguments = high, low, close 
    "CMO":"Chande Momentum Osc",   - Arguments = close
    "DX":"Directnl Move Idx",   - Arguments = high, low, close 
    "MACD":"MA Convg/Diverg",   - Arguments = close
    "MACDEXT":"MACD EXT",  - Arguments = close
    "MFI":"Money Flow Index",    - Arguments = high, low, close, volume
    "MINUS_DI":"Minus DI",   - Arguments = high, low, close 
    "MINUS_DM":"Minus DM",   - Arguments = high, low
    "MOM":"Momentum",  - Arguments = close
    "PLUS_DI":"Plus DI",   - Arguments = high, low, close 
    "PLUS_DM":"Plus DM",   - Arguments = high, low
    "PPO":"%PX Oscillator",  - Arguments = close
    "ROC":"Rate of change",  - Arguments = close
    "ROCP":"Rate Δ %",  - Arguments = close
    "ROCR":"Rate Δ ratio",  - Arguments = close
    "ROCR100":"Rate Δ ratio 100",  - Arguments = close
    "RSI":"RSI",  - Arguments = close
    "STOCH":"Stochastic",   - Arguments = high, low, close 
    "STOCHF":"Stochastic Fast",   - Arguments = high, low, close 
    "STOCHRSI":"Stochastic RSI",  - Arguments = close
    "TRIX":"1-day ROC",  - Arguments = close
    "ULTOSC":"Ultimate Oscillator",   - Arguments = high, low, close 
    "WILLR":"Williams %R",   - Arguments = high, low, close 
    "ATR":"Avg True Range",   - Arguments = high, low, close 
    "MACDFIX":"MA Convergence/Divergence ",   - Arguments = close
    "NATR":"Normalized Average True Range",   - Arguments = high, low, close 
    "TRANGE": "True Range" ,   - Arguments = high, low, close 
```    

## LineChart(**kwargs)
The LineChart function will generate a line chart
that is branded with CloudQuant logo and colors.

### Required Keyword Arguments: 
* "df" = the pandas data frame with the data you want to graph
* "cols" = List containing (string) names of the dataframe column name you wish to graph as a line. 
        If the cols is an empty list then it will chart any applicable overlays and studies.
* "x_column"  = (string) the name of the dataframe column name you wish to use as the x axis. If
        not supplied then the x_column will default to the index of the dataframe.

### Optional Keyword Arguments: 
* "title" = (string) The title at the top of the chart.
    title can contain some html tags like 
    ```<b></b><i></i> and <br>.```
    * note: not all html tags are supported.
* "xlabel" = (string) the label for the x axis.
    xlabel can contain some html tags like 
    ```<b></b><i></i>.```
* "ylabel" = (string) the label for the y axis.
    ylabel can contain some html tags like 
    ```<b></b><i></i>```
* "width" = Horizontal size (in px). Defaults to 800. Cannot be less than 400
* "height" = Vertical size (in px) . Defaults to 800. Cannot be less than 300


### Secondary Y Axis:
* "y2axis_name" = (string) the name of the secondary axis that will display on 
        the right hand side of the chart. Adding this argument
                indicates that you want to add a second y axis. Without it
                no second axis will be created.
* overlay_df = the data frame that you want to plot. 
**Important Note** this dataframe must have a column with the same name and format as the X axis in your original dataframe (df)
* overlay_cols = [list of strings] this list of strings contains the names of the
            second Y axis data plots. example ["col1", "col2", "col3"]


### Studies:

NOTE **You must specify x_column to chart the studies**, even if the x_column is timestamp
    
   
* "study" = Name of the study - See list of supported studies
* "study_columns" = column names list from the dataframe specified in "df" to perform the study upon in order. If you wish to show a study you must specify the study_column.
* "timeperiod" = the number of time periods in the study
                
**Supported Studies**

```
             "BBANDS": #Bollinger Bands (defaults to 5 time periods)
             "MAMA": #MESA Adaptive Moving Average  (defaults to 5 time periods)
             "DEMA": #Double Exponential Moving Average (defaults to 30 time periods)
             "EMA": #Exponential Moving Average (defaults to 30 time periods)
             "HT_TRENDLINE": #Hilbert Transform - Instantaneous Trendline (no time periods)
             "KAMA": #Kaufman Adaptive Moving Average (defaults to 30 time periods)
             "MA": #Moving average (defaults to 30 time periods)
             "MIDPOINT": #MidPoint over period (defaults to 14 time periods)
             "MIDPRICE": #Midpoint Price over period (defaults to 14 time periods)
             "SAR": #Parabolic SAR  (no time periods)
             "SAREXT": #Parabolic SAR - Extended  (no time periods)
             "SMA": #Simple Moving Average (defaults to 30 time periods)
             "T3": #Triple Exponential Moving Average (T3)  (no time periods)
             "TEMA": #Triple Exponential Moving Average (defaults to 30 time periods)
             "TRIMA": #Triangular Moving Average (defaults to 30 time periods)
             "WMA": #Weighted Moving Average (defaults to 30 time periods)
```

## BarChart(**kwargs)
The BarChart function will generate a bar chart that is branded with CloudQuant logo and colors.

### Required Keyword Arguments: 
* "df" = the pandas data frame with the data you want to graph
* "xcol" = (string) dataframe column name you wish to graph as the X Axis
    * note: of a value appears in the xcol more than once it will cause a stacked bar for that given value.
* "ycol" = (string) dataframe column name you wish to graph as the Y Axis. This 
    should be a numeric column

## Optional Keyword Arguments: 
* "title" = (string) The title at the top of the chart.
    title can contain some html tags like ```<b></b><i></i> and <br>.``` Please note: not all html tags are supported.
* "xlabel" = (string) the label for the x axis. xlabel can contain some html tags like ```<b></b><i></i> ```
* "ylabel" = (string) the label for the y axis. ylabel can contain some html tags like ```<b></b> and <i></i>```
* "width" = Horizontal size (in px). Defaults to 800. Cannot be less than 400
* "height" = Vertical size (in px) . Defaults to 400. Cannot be less than 300
* "singlecolor" = (bool) Should the bar chart be a single color (True or False). defaults to True.
* "orientation" = 'v' or 'h'. Defaults to v as vertical.

## PieChart(**kwargs)
The Pie function will generate a Pie chart that is branded with CloudQuant logo and colors.

### Required Keyword Arguments: 
* "df" = the pandas data frame with the data you want to graph
* "labelcol" = (string) dataframe column name you wish to graph
* "valuecol" = (string) dataframe numeric column use for the pie slice size

### Optional Keyword Arguments: 
* "title" = (string) The title at the top of the chart.
    title can contain some html tags like 
    ```<b></b><i></i> and <br>.```
    note: not all html tags are supported.

* "width" = Horizontal size (in px). Defaults to 800. Cannot be less than 400
* "height" = Vertical size (in px) . Defaults to 400. Cannot be less than 300
* "hole" = size of the donut hole (between 0 and 1). 0.0 equals no donut hole.
* "colors" = Color sequence to use. Defaults to CQ Color palette. Optionally one of ['reds', 'greens', 'blues']


## GroupedBarChart(**kwargs) 
The GroupedBarChart function will generate a gruoped bar chart that is branded with CloudQuant logo and colors.
    
### Required Keyword Arguments:
* "df" = the pandas data frame with the data you want to graph
* "groups" = (string) dataframe column name you wish to graph as the group bar.
* "values" = (list) a list of dataframe column names you wish to graph as the values. This 
        should be a numeric column

### Optional Keyword Arguments:
* "title" = (string) The title at the top of the chart.
        title can contain some html tags like```<b></b><i></i> and <br>.``` Please note: not all html tags are supported.
* "group_label" = (string) the glabel for the x axis. The group_label can contain some html tags like```<b></b><i></i> and <br>.```
* "value_label" = (string) the label for the y axis. The value_label can contain some html tags like ```<b></b><i></i> and <br>.```
* "width" = Horizontal size (in px). Defaults to 800. Cannot be less than 400
* "height" = Vertical size (in px) . Defaults to 400. Cannot be less than 300
* "colors" = A list of colors. Bars' color would iterate the list as a circle. Default set cq_colors list.
* "orientation" = 'v' or 'h'. Defaults to v as vertical.


## ScatterPlot (**kwargs)
The ScatterPlot function will generate a scatter plot chart that is branded with CloudQuant logo and colors.

### Required Keyword Arguments
* "df" = the pandas data frame with the data you want to graph
* "x_column" = (string) dataframe numeric column name you wish to graph on the horizontal axis
* "y_column" = (string) or (list) of strings with the name of the dataframe numeric column name you wish to graph on the vertical axis

### Optional Keyword Arguments
* "title" = (string) The title at the top of the chart. title can contain some html tags like ```<b></b><i></i> and <br>.```  Please note: not all html tags are supported.
* "width" = Horizontal size (in px). Defaults to 800. Cannot be less than 400
* "height" = Vertical size (in px) . Defaults to 400. Cannot be less than 300
* "xlabel" = the text to appear with the horizontal axis
* "ylabel" = the text to appear with the vertical axis
* "size_column" = the numerical column that will indicate the size of the scatter plot bubble.  If the size_column contains negative values then the bubbles will color green and red for positive and negative.
* "size_multiplier" = numeric multiplier to change the size of the bubble.


## treemap(**kwargs)
The treemap function will generate a treemap chart that is branded with CloudQuant logo and colors. A treemap 
is a visual method for displaying hierarchical data that uses nested rectangles to represent the branches of a 
tree diagram. Each rectangles has an area proportional to the amount of data it represents. 

This is sometimes called a heat map or a proportional heat map.

### Required Keyword Arguments    
* "df" = the pandas data frame with the data you want to graph
* "label_cols" = (list of strings) the labels for each branch of the tree. The labels must be column names found in "df". For example, this should be ["symbol"] is you only want to have a single branch under each positive/negative/no change category.
* "color_value_col" = (string) the column that will be used to determine the color. Values less than zero will be negative, values greater than zero will be positive.

### Optional Keyword Arguments
* "size_col" = (string) the column that will be used to determine the size of each cell in the heat map. If not specified, this will be the absolute value of the color_value_col.
* 'boxes' = (list of 3 strings) This is the outermost boxes on the tree map. These default to ["Losers", "No Change", "Gainers"] if not specified. The first string will be for negative numbers, the second for 0, the third for positive numbers.
* "positive_color" = color for positive value cells. Defaults to cq_green
* "negative_color" = color for negative value cells Defaults to cq_red
* "no_change_color" = color for zero value cells. Defaults to cq_gridgrey
* "title" = (string) The title at the top of the chart. title can contain some html tags like <b></b><i></i> and <br>. note: not all html tags are supported.
* "width" = Horizontal size (in px). Defaults to 800. Cannot be less than 400
* "height" = Vertical size (in px) . Defaults to 400. Cannot be less than 300
* "mode" = int (1 or 2) The style of the chart. Mode 1 (default styple) makes positive and negative numbers separated at the top level. This means that you end up with a chart that is all green and all red on each side.
    * mode 1 = negative and positive values separated at the highest node level.
    * mode 2 = each level/node will have negative and positive cells co-mingled.


##  fig_verticalshade(**kwargs)
The fig_verticalshade function will add a vertical shading to a region of a chart (fig).
This works best with a linechart or a candlestick chart. 

### Required Keyword Arguments 
* "fig" = a plotly Figure that you want to add a highlighted vertical shading region to.
* "df" = the pandas data frame with the data you want to graph
* "x_column" = (string) dataframe numeric column name you wish to graph on the horizontal axis
* "y_column" = (string) dataframe numeric column name you wish to graph on the vertical axis.
* "x0" = starting x value for the shading
* "x1" = ending x value for the shading   

### Optional Keyword Arguments
* "color" = string hex code for the color. Defaults to cq_gridgrey. The color for the shading
* "opacity" Defaults to 0.4. This is how see through the shading is for this region.
* "label" Defaults to None. This is a label for the shading


##  fig_horizonatalshade(**kwargs)
The fig_horizonatalshade function will add a horizontal shading to a region of a chart (fig).
This works best with a linechart or a candlestick chart. 


### Required Keyword Arguments 
* "fig" = a plotly Figure that you want to add a highlighted vertical shading region to.
* "df" = the pandas data frame with the data you want to graph
* "x_column" = (string) dataframe numeric column name you wish to graph on the horizontal axis
* "y_column" = (string) dataframe numeric column name you wish to graph on the vertical axis.
* "y0" = starting y value for the shading
* "y1" = ending y value for the shading
    
    
### Optional Keyword Arguments
* "color" = string hex code for the color. Defaults to cq_gridgrey. The color for the shading
* "opacity" Defaults to 0.4. This is how see through the shading is for this region.
* "label" Defaults to None. This is a label for the shading


## fig_stddevshading(**kwargs)
The fig_stddevshading function will add standard deviation charting to a region of a chart (fig).
This works best with a linechart or a candlestick chart. 

### Required Keyword Arguments 
* "fig" = a plotly Figure that you want to add a highlighted vertical shading region to.
* "df" = the pandas data frame with the data you want to graph
* "x_column" = (string) dataframe numeric column name you wish to graph on the horizontal axis
* "y_column" = (string) dataframe numeric column name you wish to graph on the vertical axis.

### Optional Keyword Arguments
* "lookback_periods" (Integer) Defaults to 6. This is how far back the standard deviation looks
* "deviations" (float) Defaults to 1. How many standard deviations chart.
* "color" = (hex) Defaults to cq_gridgrey ('#e0dede'). The color for the shading of the standard deviation. Examples: '#b4dcfd', '#9bd1fd', '#82c5fc', ...
* "opacity" = (float) Defaults to 0.45. The oppacity of the shaded area. This number should be  greater than zero and less than 1. If you change the color to a darker color it is recommended that you decrase this number



## drawdowns(**kwargs)
The drawdowns function will add drawdown shading to a chart. 

### Required Keyword Arguments 
* "fig" = a plotly Figure that you want to add a highlighted vertical shading region to.
* "df" = the pandas data frame with the data you want to graph
* "x_column" = (string) dataframe numeric column name you wish to calculated the drawdown upon. This should be  the same as the x axis from when you created the figure
* "y_column" = (string) dataframe numeric column name you wish to graph on the vertical axis.This should be the same as the y axis from when you created the figure

### Optional Keyword Arguments
* "threshold" (NEGATIVE float) Defaults to -0.01. This is threshold for charting a drawdown. Drawdowns that are greater than this value are not charted.
* "color" = string Defaults to red. The color for the shading of the drawdown.
* "opacity" = (float) Defaults to 0.45. The oppacity of the shaded area. This number should be greater than zero and less than 1. If you change the color to a darker color it is recommended that you decrase this number
