count-api 3.1.9
API client for count.co

# Count API Documentation

Harness the exploration, collaboration, and visualisation capabilities of the [count.co](https://count.co) web service in your workflow with the *Count API* package for Python.

This project contains an API client for the [count.co](https://count.co) web service, providing methods for authentication, data upload, and data visualisation. 

# Requirements

Python 2 or 3

Optimised for Jupyter Notebook environment

Packages installed as dependencies:

- [requests](http://docs.python-requests.org/en/master/)
- [protobuf](https://pypi.org/project/protobuf/)

# Supported versions

Python 2.7, 3.4, 3.5, 3.6.0, 3.6

# Access

In order to use the Count API module, you need to generate a token in your accounts page on [count.co](https://count.co). 

# Installation

In your terminal, you can use pip to install count: 

  - `pip install count_api`
  - `pip3 install count_api`

## Import

    from count_api import CountAPI

## Initialise
```python
token = "TOKEN GENERATED FROM COUNT.CO ADMIN PAGE"
count = CountAPI()
count.set_api_token(token)
```

# Load data to Count

## Tables

In the Count API, tables are objects that represent the data you are sending to Count.

```python
#Upload a File (.csv or .txt)
path = 'Users/me/Downloads/norweiganCarSales.csv'
table = count.upload(path=path, name='MyTableName')

#Upload a dataframe
df = pd.read_csv('norweiganCarSales.csv')
table = count.upload(data=df, name='MyTableName')

#Upload raw data
table = count.upload(data='Column1,Column2,Column3\n1,10,100\n2,20,200', name='MyTableName')
```

## Previewing table contents
The first rows of a table can be printed to screen by using the `table.head(rows,columns)` method, e.g.
```python
table.head()
```

The last rows of a table can be printed to screen by using the `table.tail(rows,columns)` method, e.g.
```python
table.tail()
```

You can also find the number of rows in a column via 
```python
table.size()
```
which returns a tuple of ints `(number_of_rows, number_of_columns)`.
## Generate Count URL

If you want to visualise your table in Count, you'll need the URL. See the example scripts on examples of how to best use this URL to distribute to your team, and visualise for yourself. 

```python
url = table.url()
```

# Create a Visual

## Visuals

Like Table objects, Visual objects are created to represent a visual you have created with the `table.upload_visual` method. The `table.upload_visual` method contains the following parameters;

- `x`, `y`, `size`, `color`: specify which column to plot on each axis, via the name of the column or the column object itself
- `aggregates`: a tuple/list of tuples/dict of the column-to-aggregrate mapping specifying the aggregate to perform on each column. For example, for performing a `sum` on a column named 'ColumnName1' and an 'avg' on a column named `ColumnName2`, you can use `{'ColumnName1' : 'sum', 'ColumnName2' : 'avg'}`
- `groupings`: a tuple/list of tuples/dict of the groupings to apply to a column. For example, to group a `datetime` column by month you can use `{'ColumnName1': 'month'}`
- `filters`: a tuple/list of tuples/dict of the filters to apply to a column. For example, for filtering on a `datetime` colum named 'Year' for values between the year 2007 and 2012, you can use `[('Year', '>=', (2007,)), ('Year', '<=', (2012,)]
- `chart_options`: a dict of chart options allowing specification of axis-scale e.g. `{'x_type' : 'linear', 'y_type': 'log'}`; chart type  `{'type' : 'circle'}`.

A full example snippet is shown below:

```python
visual = table.upload_visual(x = 'Year',
                             y = 'Quantity',
                             color = 'Type',
                             filters=[('Year', '>=', (2007,1,1)), ('Year', '<=', (2012,1))]
                             aggregates = {'Quantity', 'sum'},
                             chart_options = {'y_type': 'linear', 'chart_type': 'line'}
                            )
```

## Selecting columns

To create a visual, you will need to reference the columns in the Table object. Column references are used for selecting axes `x`,`y`,`color`,`size`, constructing the `filters`, selecting `aggregates` and `groupings`.

CountAPI provides several ways to reference a column in the table.

```python
q_columns = table.columns('Quantity') # List of Column objects for columns with title matching string 'Quantity'
q_column  = table['Quantity']         # Column object of first column with title matching string 'Quantity'
col_type = table.column('Type')       # Column object of first column with title matching string 'Type'
first_column = table[0]               # Column object of first column in table
first_column = table.column(0)        # Column object of first column in table
```

You can also use the column name directly in the `upload_visual` signature itself, as shown in the example in the [link](#Visuals) section. Referencing columns directly via their names is equivalent to using the `table['ColumnName']` form shown above.

## Axes

Visuals on [count.co](https://count.co) can have the following axes: `x`, `y`, `size`, `color`. 

## Filters

Filters can be represented as a tuple, a lists of tuples, or a dict object. The syntax has been designed to give as much flexibility to the user as possible. The `filters` parameter is typically formed of a singular or repeated units of column reference, comparator string, and value.

### Comparators

Available comparator strings are
- For strings:
    - 'IN', 'NOT_IN'
- For numbers:
    - '>', '>=', '<', '<=', '!=', '=', 'IN', 'NOT_IN'

Note that
- For a single column, each of '>'/'>=' or '<'/'<=' can only appear once
- '='/'!=' can only appear once for each column. Consider using 'IN'/'NOT_IN' for multiple equalities/inequalities
- Only '>'/'>=' and '<'/'<=' operators can be combined in 'OR' operations

### Datetime values

Columns of type `'datetime'` have extra flexibilty with regards to values in filters. Values in 
a datetime column can of types:
- `datetime` objects from the python [datetime](https://docs.python.org/3/library/datetime.html) module
- tuples of 1-3 integers: `(year,)`, `(year, month,)`, `(year, month, day)`
- integer miliseconds since the [epoch](https://en.wikipedia.org/wiki/Unix_time) 01/01/1970

### Tuple syntax

The below examples are all equivalent
```python
from datetime import datetime 
...
filters=('Year', '>', datetime(2016,1,1))
...
filters=('Year', '>', (2016,1,1))
...
filters=(table['Year'], '>', (2016,1,1))
```

### List of tuples syntax

The below examples are all equivalent
```python
filters=[('NumberColumn1', '<=', 10), ('NumberColumn1', '>=', 5)]
...
filters=[('NumberColumn1', '<=', 10, 'AND', '>=', 5)]
```

Further examples include filters on multiple columns
```python
filters=[('NumberColumn1', '<=', 10), ('StringColumn1', 'IN', ['blah', 'foo'])]
```

### Dict syntax

```python
filters={'NumberColumn1': [('<=', 10), ('>=', 5)], table['StringColumn1']: ('IN', ['blah', 'foo'])}
```

### AND and OR

Filters can be combined via 'OR' or 'AND'. Filters specied via a list of tuples (see above) are combined by 'AND' by default. To use 'OR', the following syntax is accepted
```python
...
filters=[('NumberColumn1', '<=', 10, 'OR', '>=', 5)]
```

Note that 'OR' can only be used once per column and cannot be combined with 'AND' on the same column.

## Aggregates

Aggregates can be selected for a particular column using the `aggregates` parameter. The `aggregates` parameter accepts a tuple/list of tuples/dict of the column-to-aggregrate mapping specifying the aggregate to perform on each column. 

For example the following are equivalent
```python
aggregates = ('ColumnName1', 'sum')
...
aggregates = (table['ColumnName1'], 'sum')
...
aggregates = [('ColumnName1', 'sum')]
...
aggregates = {'ColumnName1' : 'sum'}
```

Aggregate options (case insensitive):

- For `string` type columns: 'number', 'distinct', 'min', 'max'
- For `int`, `double` and `datetime` type columns: 'number', 'distinct', 'min', 'max', 'med', 'sum', 'avg', 'med'

Note that you cannot use both grouping and aggregate on a column.

## Groupings

Groupings can be selected for a particular column using the `groupings` parameter. The `groupings` parameter accepts a tuple/list of tuples/dict of the column-to-aggregrate mapping specifying the grouping to perform on each column. 

Grouping options (case insensitive):
- For `int`, `double` type columns: 'auto'
- For `datetime` type columns: 'year', 'month', 'week', 'day', 'hour', 'minute', 'second'

Note that you cannot use both grouping and aggregate on a column.

## Set chart options
Chart options can be set using the `chart_options` dict parameter. Options that can be set include
- `x_type`, `y_type`, `size_type`, `color_type`: set scale of the axis to be either `linear` or `log` e.g. `{'x_type' : 'linear'}`. Note that this cannot be set for an axis representing a 'string' or 'datetime' column. Default is `linear` for number columns.
- `type`: set chart type to be one of `line`,`bar`,`circle`,`area`, `auto` e.g `{'type' : 'circle'}`

## Embedding a visual
Once a Visual object has been created, it can be embedded within a Jupyter notebook with the 
```python
visual.embed()
```
method, which returns an IFrame of the embedded representation of the chart on [count.co](https://count.co).

## Chart sharing
A visual can be shared by using the
```python
visual.url()
```
method. This returns a string url of the full visual url on [count.co](https://count.co).

# Manage your data in Count

## Overwrite an existing table

```python
table = count.upload(data=pd, name = 'MyTableName', overwrite_key = 'TwPhiNcdxc7')
```

or if the Table object is still in memory,

```python
table = table.overwite(data=pd, name = 'MyTableName')
```

## Append to an existing table

```python
table = count.upload(data=pd, name = 'MyTableName', append_key = 'TwPhiNcdxc7')
```

or if the Table object is still in memory,

```python
table = table.append(data=pd, name = 'MyTableName')
```

Note that the new data being appended
- must have a header row
- must have the same number of columns as the original table
- must have the same column types as the original column

## Column types

Column types of a data file/blob are automatically interpreted on upload to [count.co](http://count.co). Possible column types are

- `int`: column of integer values
- `double`: column of floating point values
- `datetime`: column of datetime values
- `string`: column of words

Should you wish to force a column to be of a particular type, it is possible to do this by specifying the `column_types` list parameter on `count.upload` or `table.overwrite`, for example to specify the first 4 column types of a dataset with more than 4 columns:

```python
table = count.upload(data=pd, name = 'MyTableName', column_types=['int', 'double', 'double', 'datetime'])
```

Note that
- `column_types` parameter cannot be used in conjunction with append methods
- columns that cannot be interpreted as either `int`, `double`, or `datetime` will be interpreted as `string` columns
- if used in conjunction with `column_names` parameter, the length of both lists must be the same

## Column names

Default column names are taken from the first header of the of the file/data uploaded. Column names can be overridden by specifying the `column_names` list parameter on `count.upload` or `table.overwrite`, for example to specify the first 4 column names of a dataset with more than 4 columns:

```python
table = count.upload(data=pd, name = 'MyTableName', column_types=['MyColumn1', 'MyColumn2', 'MyColumn3', 'MyColumn4'])
```

Note that
- `column_names` parameter cannot be used in conjunction with append methods
- if used in conjunction with `column_names` parameter, the length of both lists must be the same

## Delete a table

This deletes a table on [count.co](http://count.co). As such, any operations on a deleted table will throw error with 404 status code 
```python
table.delete()
count.delete_table('TwPhiNcdxc7')
```
---
# A Full Example:
```python
import pandas as pd
from count_api import CountAPI

token = "Use token generated from Count Admin page"
count = CountAPI()
count.set_api_token(token)

#Upload a dataframe
df = pd.read_csv('norweiganCarSales.csv')
table = count.upload(data=df,name = 'Car Sales in Norway')

#You can view the table and create your own visuals in Count using the table.url() method
url = table.url()

#Preview first 10 lines of table
table.head()

#Get size of table
table.size()

# Create visual of chart of SUM('Quantity') vs 'Year' separated by color for 'Type'
# for year between 2007 and end of 2016
# with linear scale for y-axis, and line chart type
visual = table.upload_visual(x = 'Year',
                             y = 'Quantity',
                             color = 'Type',
                             aggregates = {'Quantity' : 'sum'},
                             filters=[('Year','>=',(2007,)),('Year','<=',(2016,))]
                             chart_options = {'y_type':'linear', 'chart_type': 'line'}
                            )


# Get visual url
visual.url()

#If using Jupyter notebook, you can also embed a chart via
visual.embed()

#Delete table on count.co if no longer needed
table.delete()

```
---

# Technical Documentation

## CountAPI
CountAPI class containing the following methods:
- `set_api_token(api_token)`
  - Sets API token obtained from [count.co](https://count.co).
  - `api_token`: String API token 
- `upload(path = None, name = None, data = None, overwrite_key = None)`
  - Uploads csv file from path or csv data from str (keyword arg only method).
  - `path`: String filepath to the .csv or .xls(x). Cannot be used in conjunction with `path`.
  - `data`: String csv data to upload. Cannot be used in conjunction with `path`.
  - `name`: String name of table.
  - `overwrite_key`: String key of the table for which you would like to replace the data.
  - `append_key`: String key of the table to which you would like to append data.
  - `column_types`: List of strings of column types. Acceptable types of column type are 'string', 'int', 'double', and 'datetime'.
  - `column_names`: List of strings of column names.
  - if `column_names`/`column_types` have length greater than the number of columns in the table, the extra enties are ignored.
  - `column_names`: and `column_types` must have same length if both are set.
  - `column_names` and `column_types` cannot be used in conjuction with `append_key`
  - `Return`: Table object.
- `delete_table(table_key)`:
    - Deletes specified table from [count.co](https://count.co) server.
    - `table_key`: String table key.
- `table(table_key)`:
    - Get a table object from an existing table key.
    - `table_key`: String table key.
    - `Return`: Table Object.

## Table
Table class containing the following methods:
- `[index]`:
  - Get Column object from column index.
  - `index`: Integer index of column
  - `Return`: Column Object.
- `[name]`:
  - Get Column object from column name. Returns first column found with header matching name.
  - `name`: String column name.
  - `Return`: Column Object.
- `append(path = None, data = None)`:
  - Appends csv file from path or csv data from str (keyword arg only method) to existing table. New table must match column types of existing table.
  - `path`: String filepath to the .csv or .xls(x). Cannot be used in conjunction with `path`.
  - `data`: String csv data to upload. Cannot be used in conjunction with `path`.
  - `Return`: Self.
- `column(index)`:
  - Get Column object from column index.
  - `index`: Integer index of column
  - `Return`: Column Object.
- `column(name)`:
  - Get Column object from column name. Returns first column found with header matching name.
  - `name`: String column name.
  - `Return`: Column Object.
- `columns(name = None)`:
  - Get list of Column objects with headers matching name parameter. If name is defaulted, returns all columns in table.
  - `Return`: List of Column Objects.
- `delete()`:
  - Deletes table from [count.co](https://count.co) server. Future references to this Table will be undefined.
- `head(rows=10,columns=10)`:
  - Prints first n rows of table
  - `rows`: Integer number of rows requested. Max 100. Default 10.
  - `columns`: Integer number of columns requested. Max 20. Default 10.
- `tail(rows=10,columns=10)`:
  - Prints last n rows of table
  - `rows`: Integer number of rows requested. Max 100. Default 10.
  - `columns`: Integer number of columns requested. Max 20. Default 10.
- `overwrite(path = None, name = None, data = None, column_types = None, column_names = None)`:
  - Uploads csv file from path or csv data from str (keyword arg only method), overwriting existing table. New table must match column types of existing table.
  - `path`: String filepath to the .csv or .xls(x). Cannot be used in conjunction with `path`.
  - `data`: String csv data to upload. Cannot be used in conjunction with `path`.
  - `name`: String name of table.
  - `column_types`: List of strings of column types. Acceptable types of column type are 'string', 'int', 'double', and 'datetime'.
  - `column_names`: List of strings of column names.
  - if `column_names`/`column_types` have length greater than the number of columns in the table, the extra enties are ignored.
  - `column_names`: and `column_types` must have same length if both are set.
  - `Return`: Self.
- `size()`:
  - Size of table as a tuple of ints (column_extent, row_extent)
  - `Return`: Tuple (int, int)
- `upload_visual(x = None, y = None, color = None, size = None, label = None, aggregates = None, filters = None, groupings = None, chart_options = None)`:
  - Uploads chart visual to [count.co](https://count.co).
  - `x`: Column object/string column name to be used for x-axis
  - `y`: Column object/string column name to be used for y-axis
  - `color`: Column object/string column name to be used for color-axis
  - `size`: Column object/string column name to be used for size-axis           
  - `label`: Column object/string column name to be used for label-axis
  - `aggregates`: Tuple/list of tuples/dictionary of aggregates to be applied to columns.
  - `filters`: Tuple/list of tuples/dictionary of filters to be applied to columns.
  - `groupings`: Tuple/list of tuples/dictionary of groupings to be applied to columns.
  - `chart_options`: Dictionary of chart options to be applied. Accepted dict keys:values:
    - `type`: `line`,`bar`,`circle`,`area`, `auto`
    - `x_type`: `linear`, `log`
    - `y_type`: `linear`, `log`
    - `size_type`: `linear`, `log`
    - `color_type`: `linear`, `log`
  - `Return`: Visual object.
- `url()`:
  - Get url to table view on count.co.
  - `Return`: String of URL.

## Visual
Visual class containing the following methods:
- `embed()`:
  - Returns IFrame to current visual. For use with interactive environments, e.g Jupyter notebooks.
  - `Return` IFrame.
- `download_csv()`:
  - Download csv of visual on [count.co](https://count.co).
  - Downloads to Downloads folder if path is defaulted.
  - path: str download path.
- `download_preview()`:
  - Download png of visual on [count.co](https://count.co).
  - Downloads to Downloads folder if path is defaulted.
  - path: str download path.
  - height: int pixels.
  - width: int pixels.
- `preview_url()`:
  - Returns url to preview view on [count.co](https://count.co).
  - `Return`: String.
- `set_chart_options(dict: chart_option)`:
  - Set chart options.
  - `chart_options`: Dictionary of chart options to be applied. Accepted dict keys:values:
    - `type`: `line`,`bar`,`circle`,`area`, `auto`
    - `x_type`: `linear`, `log`
    - `y_type`: `linear`, `log`
    - `size_type`: `linear`, `log`
    - `color_type`: `linear`, `log`
  - `Return`: Self.
- `url()`:
  - Returns url to visual view on [count.co](https://count.co).
  - `Return`: String.
- `url_embed()`:
  - Returns url to visual view on [count.co](https://count.co) suitable for embedding
  - `Return`: String.

## Column
Column class containing the following methods:

- `aggregate(aggregate)`:
  - Add aggregate function to Column object. Note: cannot perform both group_by and aggregate on the same Column object.
  - `aggregate`: String aggregate
      - str: ['DISTINCT', 'MIN', 'MAX', 'MED']
      - other: ['DISTINCT', 'MIN', 'MAX', 'MED', 'SUM', 'AVG', 'STD', 'VAR', 'MED']
  - `Return`: self
- `filter(comparator, str or int or float or datetime: value)`:
  - Returns Filter object with specified comparator and value
  - `comparator`: String comparator. Available comparators are:
    str: ['IN']
    other : ['>', '>=', '<', '<=']
  - `value`: string/integer/float/datetime value to compare against
  - `Return`: self