|
|
import numpy as np |
|
|
from scipy.sparse import coo_matrix |
|
|
from scipy._lib._bunch import _make_tuple_bunch |
|
|
|
|
|
|
|
|
CrosstabResult = _make_tuple_bunch( |
|
|
"CrosstabResult", ["elements", "count"] |
|
|
) |
|
|
|
|
|
|
|
|
def crosstab(*args, levels=None, sparse=False): |
|
|
""" |
|
|
Return table of counts for each possible unique combination in ``*args``. |
|
|
|
|
|
When ``len(args) > 1``, the array computed by this function is |
|
|
often referred to as a *contingency table* [1]_. |
|
|
|
|
|
The arguments must be sequences with the same length. The second return |
|
|
value, `count`, is an integer array with ``len(args)`` dimensions. If |
|
|
`levels` is None, the shape of `count` is ``(n0, n1, ...)``, where ``nk`` |
|
|
is the number of unique elements in ``args[k]``. |
|
|
|
|
|
Parameters |
|
|
---------- |
|
|
*args : sequences |
|
|
A sequence of sequences whose unique aligned elements are to be |
|
|
counted. The sequences in args must all be the same length. |
|
|
levels : sequence, optional |
|
|
If `levels` is given, it must be a sequence that is the same length as |
|
|
`args`. Each element in `levels` is either a sequence or None. If it |
|
|
is a sequence, it gives the values in the corresponding sequence in |
|
|
`args` that are to be counted. If any value in the sequences in `args` |
|
|
does not occur in the corresponding sequence in `levels`, that value |
|
|
is ignored and not counted in the returned array `count`. The default |
|
|
value of `levels` for ``args[i]`` is ``np.unique(args[i])`` |
|
|
sparse : bool, optional |
|
|
If True, return a sparse matrix. The matrix will be an instance of |
|
|
the `scipy.sparse.coo_matrix` class. Because SciPy's sparse matrices |
|
|
must be 2-d, only two input sequences are allowed when `sparse` is |
|
|
True. Default is False. |
|
|
|
|
|
Returns |
|
|
------- |
|
|
res : CrosstabResult |
|
|
An object containing the following attributes: |
|
|
|
|
|
elements : tuple of numpy.ndarrays. |
|
|
Tuple of length ``len(args)`` containing the arrays of elements |
|
|
that are counted in `count`. These can be interpreted as the |
|
|
labels of the corresponding dimensions of `count`. If `levels` was |
|
|
given, then if ``levels[i]`` is not None, ``elements[i]`` will |
|
|
hold the values given in ``levels[i]``. |
|
|
count : numpy.ndarray or scipy.sparse.coo_matrix |
|
|
Counts of the unique elements in ``zip(*args)``, stored in an |
|
|
array. Also known as a *contingency table* when ``len(args) > 1``. |
|
|
|
|
|
See Also |
|
|
-------- |
|
|
numpy.unique |
|
|
|
|
|
Notes |
|
|
----- |
|
|
.. versionadded:: 1.7.0 |
|
|
|
|
|
References |
|
|
---------- |
|
|
.. [1] "Contingency table", http://en.wikipedia.org/wiki/Contingency_table |
|
|
|
|
|
Examples |
|
|
-------- |
|
|
>>> from scipy.stats.contingency import crosstab |
|
|
|
|
|
Given the lists `a` and `x`, create a contingency table that counts the |
|
|
frequencies of the corresponding pairs. |
|
|
|
|
|
>>> a = ['A', 'B', 'A', 'A', 'B', 'B', 'A', 'A', 'B', 'B'] |
|
|
>>> x = ['X', 'X', 'X', 'Y', 'Z', 'Z', 'Y', 'Y', 'Z', 'Z'] |
|
|
>>> res = crosstab(a, x) |
|
|
>>> avals, xvals = res.elements |
|
|
>>> avals |
|
|
array(['A', 'B'], dtype='<U1') |
|
|
>>> xvals |
|
|
array(['X', 'Y', 'Z'], dtype='<U1') |
|
|
>>> res.count |
|
|
array([[2, 3, 0], |
|
|
[1, 0, 4]]) |
|
|
|
|
|
So ``('A', 'X')`` occurs twice, ``('A', 'Y')`` occurs three times, etc. |
|
|
|
|
|
Higher dimensional contingency tables can be created. |
|
|
|
|
|
>>> p = [0, 0, 0, 0, 1, 1, 1, 0, 0, 1] |
|
|
>>> res = crosstab(a, x, p) |
|
|
>>> res.count |
|
|
array([[[2, 0], |
|
|
[2, 1], |
|
|
[0, 0]], |
|
|
[[1, 0], |
|
|
[0, 0], |
|
|
[1, 3]]]) |
|
|
>>> res.count.shape |
|
|
(2, 3, 2) |
|
|
|
|
|
The values to be counted can be set by using the `levels` argument. |
|
|
It allows the elements of interest in each input sequence to be |
|
|
given explicitly instead finding the unique elements of the sequence. |
|
|
|
|
|
For example, suppose one of the arguments is an array containing the |
|
|
answers to a survey question, with integer values 1 to 4. Even if the |
|
|
value 1 does not occur in the data, we want an entry for it in the table. |
|
|
|
|
|
>>> q1 = [2, 3, 3, 2, 4, 4, 2, 3, 4, 4, 4, 3, 3, 3, 4] # 1 does not occur. |
|
|
>>> q2 = [4, 4, 2, 2, 2, 4, 1, 1, 2, 2, 4, 2, 2, 2, 4] # 3 does not occur. |
|
|
>>> options = [1, 2, 3, 4] |
|
|
>>> res = crosstab(q1, q2, levels=(options, options)) |
|
|
>>> res.count |
|
|
array([[0, 0, 0, 0], |
|
|
[1, 1, 0, 1], |
|
|
[1, 4, 0, 1], |
|
|
[0, 3, 0, 3]]) |
|
|
|
|
|
If `levels` is given, but an element of `levels` is None, the unique values |
|
|
of the corresponding argument are used. For example, |
|
|
|
|
|
>>> res = crosstab(q1, q2, levels=(None, options)) |
|
|
>>> res.elements |
|
|
[array([2, 3, 4]), [1, 2, 3, 4]] |
|
|
>>> res.count |
|
|
array([[1, 1, 0, 1], |
|
|
[1, 4, 0, 1], |
|
|
[0, 3, 0, 3]]) |
|
|
|
|
|
If we want to ignore the pairs where 4 occurs in ``q2``, we can |
|
|
give just the values [1, 2] to `levels`, and the 4 will be ignored: |
|
|
|
|
|
>>> res = crosstab(q1, q2, levels=(None, [1, 2])) |
|
|
>>> res.elements |
|
|
[array([2, 3, 4]), [1, 2]] |
|
|
>>> res.count |
|
|
array([[1, 1], |
|
|
[1, 4], |
|
|
[0, 3]]) |
|
|
|
|
|
Finally, let's repeat the first example, but return a sparse matrix: |
|
|
|
|
|
>>> res = crosstab(a, x, sparse=True) |
|
|
>>> res.count |
|
|
<COOrdinate sparse matrix of dtype 'int64' |
|
|
with 4 stored elements and shape (2, 3)> |
|
|
>>> res.count.toarray() |
|
|
array([[2, 3, 0], |
|
|
[1, 0, 4]]) |
|
|
|
|
|
""" |
|
|
nargs = len(args) |
|
|
if nargs == 0: |
|
|
raise TypeError("At least one input sequence is required.") |
|
|
|
|
|
len0 = len(args[0]) |
|
|
if not all(len(a) == len0 for a in args[1:]): |
|
|
raise ValueError("All input sequences must have the same length.") |
|
|
|
|
|
if sparse and nargs != 2: |
|
|
raise ValueError("When `sparse` is True, only two input sequences " |
|
|
"are allowed.") |
|
|
|
|
|
if levels is None: |
|
|
|
|
|
actual_levels, indices = zip(*[np.unique(a, return_inverse=True) |
|
|
for a in args]) |
|
|
else: |
|
|
|
|
|
if len(levels) != nargs: |
|
|
raise ValueError('len(levels) must equal the number of input ' |
|
|
'sequences') |
|
|
|
|
|
args = [np.asarray(arg) for arg in args] |
|
|
mask = np.zeros((nargs, len0), dtype=np.bool_) |
|
|
inv = np.zeros((nargs, len0), dtype=np.intp) |
|
|
actual_levels = [] |
|
|
for k, (levels_list, arg) in enumerate(zip(levels, args)): |
|
|
if levels_list is None: |
|
|
levels_list, inv[k, :] = np.unique(arg, return_inverse=True) |
|
|
mask[k, :] = True |
|
|
else: |
|
|
q = arg == np.asarray(levels_list).reshape(-1, 1) |
|
|
mask[k, :] = np.any(q, axis=0) |
|
|
qnz = q.T.nonzero() |
|
|
inv[k, qnz[0]] = qnz[1] |
|
|
actual_levels.append(levels_list) |
|
|
|
|
|
mask_all = mask.all(axis=0) |
|
|
indices = tuple(inv[:, mask_all]) |
|
|
|
|
|
if sparse: |
|
|
count = coo_matrix((np.ones(len(indices[0]), dtype=int), |
|
|
(indices[0], indices[1]))) |
|
|
count.sum_duplicates() |
|
|
else: |
|
|
shape = [len(u) for u in actual_levels] |
|
|
count = np.zeros(shape, dtype=int) |
|
|
np.add.at(count, indices, 1) |
|
|
|
|
|
return CrosstabResult(actual_levels, count) |
|
|
|
