Metadata-Version: 2.4
Name: cr_cube
Version: 3.3.7
Summary: Crunch.io Cube library
Home-page: https://github.com/Crunch-io/crunch-cube/
Author: Crunch.io
Author-email: dev@crunch.io
License: MIT License
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: scipy
Requires-Dist: tabulate
Provides-Extra: testing
Requires-Dist: pytest; extra == "testing"
Requires-Dist: pytest-cov; extra == "testing"
Requires-Dist: mock; extra == "testing"
Requires-Dist: coverage; extra == "testing"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: summary

# crunch-cube

![Build Status](https://github.com/Crunch-io/crunch-cube/workflows/CI/badge.svg)
![Coverage Status](https://codecov.io/gh/Crunch-io/crunch-cube/branch/master/graph/badge.svg?token=C6auKOj8tZ)
![Documentation Status](https://readthedocs.org/projects/crunch-cube/badge/?version=latest)

---
Open Source Python implementation of the API for working with CrunchCubes

## Introduction

This package contains the implementation of the CrunchCube API. It is used to
extract useful information from CrunchCube responses (we'll refer to them as
_cubes_ in the subsequent text). _Cubes_ are obtained from the _Crunch.io_
platform, as JSON responses to the specific _queries_ created by the user.
These queries specify which data the user wants to extract from the Crunch.io
system. The most common usage is to obtain the following:

- Cross correlation between different variable
- Margins of the cross tab _cube_
- Proportions of the cross tab _cube_ (e.g. proportions of each single element to the entire sample size)
- Percentages

When the data is obtained from the Crunch.io platform, it needs to be
interpreted to the form that's convenient for a user. The actual shape of the
_cube_ JSON contains many internal details, which are not of essence to the
end-user (but are still necessary for proper _cube_ functionality).

The job of this library is to provide a convenient API that handles those
intricacies, and enables the user to quickly and easily obtain (extract) the
relevant data from the _cube_. Such data is best represented in a table-like
format. For this reason, the most of the API functions return some form of the
`ndarray` type, from the `numpy` package. Each function is explained in greater
detail, uner its own section, under the API subsection of this document.

## Installation

The `cr-cube` package can be installed by using the `pip install`:

    pip install cr-cube

### For developers

For development mode, `cr.cube` needs to be installed from the local checkout
of the `crunch-cube` repository. It is strongly advised to use `virtualenv`.
Assuming you've created and activated a virtual environment `venv`, navigate
to the top-level folder of the repo, on the local file system, and run:

    pip install -e .

or

    python setup.py develop

### Running tests

To setup and run tests, you will need to install `cr.cube` as well as testing
dependencies. To do this, from the root directory, simply run:

    pip install -e .[testing]

And then tests can be run using `py.test` in the root directory:

    pytest

## Usage

After the `cr.cube` package has been successfully installed, the usage is as
simple as:

    >>> from cr.cube.cube import Cube

    >>> ### Obtain the crunch cube JSON payload using app.crunch.io, pycrunch, rcrunch or scrunch
    >>> ### And store it in the 'cube_JSON_response' variable

    >>> cube = Cube(cube_JSON_response)
    >>> print(cube)
    Cube(name='MyCube', dimension_types='CAT x CAT')
    >>> cube.counts
    np.array([[1169, 547],
              [1473, 1261]])

## Complete API Doc

Please visit <https://crunch-cube.readthedocs.io/en/latest> for the API reference.

---

## Changes

### 3.3.7

- Rebuild


### 3.3.6

- Rebuild

### 3.3.5

- Fix bug in `_Strand.table_base` and `_Strand.table_missing` for MRs.

### 3.3.4

- Fix bug in `_Slice.rows_disaggregated_missing_unweighted_counts` for Numeric Array
  grouped by categorical
- Fix bug in `_Strand.table_base_scalar` and `_Strand.table_base_range` when a variable
  is entirely missing.

### 3.3.3

- Add information about missing values to partitions:
    - `_Nub`: `.table_missing`
    - `_Strand`: `.table_missing`, `.disaggregated_missing_unweighted_counts`,
      `.disaggregated_missing_labels`, & `.disaggregated_missing_element_ids`
    - `_Slice`: `.rows_disaggregated_missing_unweighted_counts`,
      `.rows_disaggregated_missing_labels`, `.rows_disaggregated_missing_element_ids`
      `.columns_disaggregated_missing_unweighted_counts`,
      `.columns_disaggregated_missing_labels`, &
      `.columns_disaggregated_missing_element_ids`

### 3.3.2

- Bug fix column numeric ranges for _Slice

### 3.3.1

- Add numeric ranges

### 3.2.1

- Fix translate_element_id when is is None


For a complete list of changes see [history](https://github.com/Crunch-io/crunch-cube/blob/master/HISTORY.md).
