coola

Overview

coola is a Python library that provides simple functions to check in a single line if two complex/nested objects are equal or not. coola was initially designed to work with PyTorch Tensors and NumPy ndarray, but it is possible to extend it to support other data structures.

• Motivation
• Documentation
• Installation
• Contributing
• API stability
• License

Motivation

Let's imagine you have the following dictionaries that contain both a PyTorch Tensor and a NumPy ndarray. You want to check if the two dictionaries are equal or not. By default, Python does not provide an easy way to check if the two dictionaries are equal or not. It is not possible to use the default equality operator == because it will raise an error. The coola library was developed to fill this gap. coola provides a function objects_are_equal that can indicate if two complex/nested objects are equal or not.

>>> import numpy
>>> import torch
>>> from coola import objects_are_equal
>>> data1 = {"torch": torch.ones(2, 3), "numpy": numpy.zeros((2, 3))}
>>> data2 = {"torch": torch.zeros(2, 3), "numpy": numpy.ones((2, 3))}
>>> objects_are_equal(data1, data2)
False

coola also provides a function objects_are_allclose that can indicate if two complex/nested objects are equal within a tolerance or not.

>>> import numpy
>>> import torch
>>> from coola import objects_are_allclose
>>> data1 = {"torch": torch.ones(2, 3), "numpy": numpy.zeros((2, 3))}
>>> data2 = {"torch": torch.zeros(2, 3), "numpy": numpy.ones((2, 3))}
>>> objects_are_allclose(data1, data2, atol=1e-6)
False

The current supported types are:

• jax.numpy.ndarray
• numpy.ndarray
• numpy.ma.MaskedArray
• pandas.DataFrame
• pandas.Series
• polars.DataFrame
• polars.Series
• torch.Tensor
• torch.nn.utils.rnn.PackedSequence
• xarray.DataArray
• xarray.Dataset
• xarray.Variable

Please check the quickstart page to learn more on how to use coola.

Documentation

• latest (stable): documentation from the latest stable release.
• main (unstable): documentation associated to the main branch of the repo. This documentation may contain a lot of work-in-progress/outdated/missing parts.

Installation

We highly recommend installing a virtual environment. coola can be installed from pip using the following command:

pip install coola

To make the package as slim as possible, only the minimal packages required to use coola are installed. To include all the dependencies, you can use the following command:

pip install coola[all]

Please check the get started page to see how to install only some specific dependencies or other alternatives to install the library. The following is the corresponding coola versions and tested dependencies.

coola	jax*	numpy*	pandas*	polars*	torch*	xarray*	python
main	>=0.4.1,<1.0	>=1.21,<2.0	>=1.3,<3.0	>=0.18.3,<1.0	>=1.10,<3.0	>=2023.1	>=3.9,<3.13
0.6.1	>=0.4.1,<1.0	>=1.21,<2.0	>=1.3,<3.0	>=0.18.3,<1.0	>=1.10,<3.0	>=2023.1	>=3.9,<3.13
0.6.0	>=0.4.1,<1.0	>=1.21,<2.0	>=1.3,<3.0	>=0.18.3,<1.0	>=1.10,<3.0	>=2023.1	>=3.9,<3.13
0.5.0	>=0.4.1,<0.5	>=1.21,<1.27	>=1.3,<2.2	>=0.18.3,<1.0	>=1.10,<2.2	>=2023.1,<2023.13	>=3.9,<3.13
0.4.0	>=0.4.1,<0.5	>=1.21,<1.27	>=1.3,<2.2	>=0.18.3,<1.0	>=1.10,<2.2	>=2023.1,<2023.13	>=3.9,<3.13

^* indicates an optional dependency

older versions

coola	jax*	numpy*	pandas*	polars*	torch*	xarray*	python
0.3.1	>=0.4.1,<0.5	>=1.21,<1.27	>=1.3,<2.2	>=0.18.3,<1.0	>=1.10,<2.2	>=2023.1,<2023.13	>=3.9,<3.13
0.3.0	>=0.4.1,<0.5	>=1.21,<1.27	>=1.3,<2.2	>=0.18.3,<1.0	>=1.10,<2.2	>=2023.1,<2023.13	>=3.9,<3.13
0.2.2	>=0.4.1,<0.5	>=1.21,<1.27	>=1.3,<2.2	>=0.18.3,<1.0	>=1.10,<2.2	>=2023.1,<2023.13	>=3.9,<3.13
0.2.1	>=0.4.1,<0.5	>=1.21,<1.27	>=1.3,<2.2	>=0.18.3,<1.0	>=1.10,<2.2	>=2023.1,<2023.13	>=3.9,<3.13
0.2.0	>=0.4.1,<0.5	>=1.21,<1.27	>=1.3,<2.2	>=0.18.3,<1.0	>=1.10,<2.2	>=2023.1,<2023.13	>=3.9,<3.13
0.1.2	>=0.4.1,<0.5	>=1.21,<1.27	>=1.3,<2.2	>=0.18.3,<0.21	>=1.10,<2.2	>=2023.1,<2023.13	>=3.9,<3.13
0.1.1	>=0.4.1,<0.5	>=1.21,<1.27	>=1.3,<2.2	>=0.18.3,<0.20	>=1.10,<2.2	>=2023.1,<2023.13	>=3.9,<3.13
0.1.0	>=0.4.1,<0.5	>=1.21,<1.27	>=1.3,<2.2	>=0.18.3,<0.20	>=1.10,<2.2	>=2023.1,<2023.13	>=3.9,<3.12
0.0.26	>=0.4.1,<0.5	>=1.21,<1.27	>=1.3,<2.2	>=0.18.3,<0.20	>=1.10,<2.2	>=2023.1,<2023.13	>=3.9,<3.12
0.0.25	>=0.4.1,<0.5	>=1.21,<1.27	>=1.3,<2.2	>=0.18.3,<0.20	>=1.10,<2.2	>=2023.4,<2023.11	>=3.9,<3.12
0.0.24	>=0.3,<0.5	>=1.21,<1.27	>=1.3,<2.2	>=0.18.3,<0.20	>=1.10,<2.2	>=2023.3,<2023.9	>=3.9,<3.12
0.0.23	>=0.3,<0.5	>=1.21,<1.27	>=1.3,<2.2	>=0.18.3,<0.20	>=1.10,<2.1	>=2023.3,<2023.9	>=3.9,<3.12
0.0.22	>=0.3,<0.5	>=1.20,<1.26	>=1.3,<2.1	>=0.18.3,<0.19	>=1.10,<2.1	>=2023.3,<2023.9	>=3.9,<3.12
0.0.21	>=0.3,<0.5	>=1.20,<1.26	>=1.3,<2.1	>=0.18.3,<0.19	>=1.10,<2.1	>=2023.3,<2023.8	>=3.9,<3.12
0.0.20	>=0.3,<0.5	>=1.20,<1.26	>=1.3,<2.1	>=0.18.3,<0.19	>=1.10,<2.1	>=2023.3,<2023.8	>=3.9

Contributing

Please check the instructions in CONTRIBUTING.md.

Suggestions and Communication

Everyone is welcome to contribute to the community. If you have any questions or suggestions, you can submit Github Issues. We will reply to you as soon as possible. Thank you very much.

API stability

⚠️ While coola is in development stage, no API is guaranteed to be stable from one release to the next. In fact, it is very likely that the API will change multiple times before a stable 1.0.0 release. In practice, this means that upgrading coola to a new version will possibly break any code that was using the old version of coola.

License

coola is licensed under BSD 3-Clause "New" or "Revised" license available in LICENSE file.