A columnar data container that can be compressed.
Jupyter Notebook C Python C++ CMake Batchfile Other
Permalink
Failed to load latest commit information.
LICENSES Annoucement for 1.0.0 RC1 release Mar 8, 2016
bcolz Use LooseVersion so as to do comparisons with Unicode versions. Fixes #… Oct 21, 2016
bench Preserve cparams during column replacement Jun 16, 2016
bench_asv rename project as bcolz Oct 7, 2015
c-blosc C-Blosc updated to 1.9.3 Jul 6, 2016
conda.recipe use conda Jul 19, 2015
continuous-integration/appveyor use miniconda latest version Aug 29, 2015
docs Added and new defaults_ctx() context for selecting defaults without c… Jul 6, 2016
.binstar.yml remove e-mail notification Nov 24, 2014
.coveragerc coveragerc Aug 31, 2015
.gitignore Struggling with versions May 25, 2016
.mailmap update .mailmap Jun 30, 2015
.travis.yml Final touches for dask support May 23, 2016
ANNOUNCE.rst Getting ready for 1.1.0 final Jun 10, 2016
DISK_FORMAT_v1.rst Added the a description for the blessed format file for bcolz 1.0 Mar 8, 2016
MANIFEST.in doc/ moved into more standard docs/ May 25, 2016
README.rst doc/ moved into more standard docs/ May 25, 2016
RELEASE_NOTES.rst Added and new defaults_ctx() context for selecting defaults without c… Jul 6, 2016
RELEASING.rst Post 1.1.0 release actions done Jun 10, 2016
THANKS.rst THANKS file updated Sep 1, 2015
appveyor.yml Not trying 64-bit builds in Python2 for AppVeyor Jun 13, 2016
coveralls_after_test_succes.sh Fix coverage > 100% Sep 1, 2015
cpuinfo.py Auto-discovery of SSE2 / AVX2 extensions May 23, 2016
makefile doc/ moved into more standard docs/ May 25, 2016
persistence.rst blosc.io -> blosc.org Sep 1, 2015
requirements.txt Updated versions of dependencies Apr 6, 2016
requirements_rtfd.txt Adding all the dependencies so that the Cython docstrings can be incl… May 25, 2016
requirements_test.txt Added the numpydoc requirement for RTFD May 25, 2016
setup.py Updated list classifiers Jun 13, 2016

README.rst

bcolz: columnar and compressed data containers

Join the chat at https://gitter.im/Blosc/bcolz
Version:version
Travis CI:travis
Appveyor:appveyor
Coveralls:coveralls
And...:powered
docs/bcolz.png

bcolz provides columnar, chunked data containers that can be compressed either in-memory and on-disk. Column storage allows for efficiently querying tables, as well as for cheap column addition and removal. It is based on NumPy, and uses it as the standard data container to communicate with bcolz objects, but it also comes with support for import/export facilities to/from HDF5/PyTables tables and pandas dataframes.

bcolz objects are compressed by default not only for reducing memory/disk storage, but also to improve I/O speed. The compression process is carried out internally by Blosc, a high-performance, multithreaded meta-compressor that is optimized for binary data (although it works with text data just fine too).

bcolz can also use numexpr internally (it does that by default if it detects numexpr installed) or dask so as to accelerate many vector and query operations (although it can use pure NumPy for doing so too). numexpr/dask can optimize the memory usage and use multithreading for doing the computations, so it is blazing fast. This, in combination with carray/ctable disk-based, compressed containers, can be used for performing out-of-core computations efficiently, but most importantly transparently.

Just to whet your appetite, here it is an example with real data, where bcolz is already fulfilling the promise of accelerating memory I/O by using compression:

http://nbviewer.ipython.org/github/Blosc/movielens-bench/blob/master/querying-ep14.ipynb

Rationale

By using compression, you can deal with more data using the same amount of memory, which is very good on itself. But in case you are wondering about the price to pay in terms of performance, you should know that nowadays memory access is the most common bottleneck in many computational scenarios, and that CPUs spend most of its time waiting for data. Hence, having data compressed in memory can reduce the stress of the memory subsystem as well.

Furthermore, columnar means that the tabular datasets are stored column-wise order, and this turns out to offer better opportunities to improve compression ratio. This is because data tends to expose more similarity in elements that sit in the same column rather than those in the same row, so compressors generally do a much better job when data is aligned in such column-wise order. In addition, when you have to deal with tables with a large number of columns and your operations only involve some of them, a columnar-wise storage tends to be much more effective because minimizes the amount of data that travels to CPU caches.

So, the ultimate goal for bcolz is not only reducing the memory needs of large arrays/tables, but also making bcolz operations to go faster than using a traditional data container like those in NumPy or Pandas. That is actually already the case in some real-life scenarios (see the notebook above) but that will become pretty more noticeable in combination with forthcoming, faster CPUs integrating more cores and wider vector units.

Requisites

  • Python >= 2.6
  • NumPy >= 1.8
  • Cython >= 0.22 (just for compiling the beast)
  • C-Blosc >= 1.8.0 (optional, as the internal Blosc will be used by default)
  • unittest2 (optional, only in the case you are running Python 2.6)

Optional:

  • numexpr >= 2.5.2
  • dask >= 0.9.0
  • pandas
  • tables (pytables)

Building

There are different ways to compile bcolz, depending if you want to link with an already installed Blosc library or not.

Compiling with an installed Blosc library (recommended)

Python and Blosc-powered extensions have a difficult relationship when compiled using GCC, so this is why using an external C-Blosc library is recommended for maximum performance (for details, see https://github.com/Blosc/python-blosc/issues/110).

Go to https://github.com/Blosc/c-blosc/releases and download and install the C-Blosc library. Then, you can tell bcolz where is the C-Blosc library in a couple of ways:

Using an environment variable:

$ BLOSC_DIR=/usr/local     (or "set BLOSC_DIR=\blosc" on Win)
$ export BLOSC_DIR         (not needed on Win)
$ python setup.py build_ext --inplace

Using a flag:

$ python setup.py build_ext --inplace --blosc=/usr/local

Compiling without an installed Blosc library

bcolz also comes with the Blosc sources with it so, assuming that you have a C++ compiler installed, do:

$ python setup.py build_ext --inplace

That's all. You can proceed with testing section now.

Note: The requirement for the C++ compiler is just for the Snappy dependency. The rest of the other components of Blosc are pure C (including the LZ4 and Zlib libraries).

Testing

After compiling, you can quickly check that the package is sane by running:

$ PYTHONPATH=.   (or "set PYTHONPATH=." on Windows)
$ export PYTHONPATH    (not needed on Windows)
$ python -c"import bcolz; bcolz.test()"  # add `heavy=True` if desired

Installing

Install it as a typical Python package:

$ pip install -U .

Optionally Install the additional dependencies:

$ pip install .[optional]

Documentation

You can find the online manual at:

http://bcolz.blosc.org

but of course, you can always access docstrings from the console (i.e. help(bcolz.ctable)).

Also, you may want to look at the bench/ directory for some examples of use.

Resources

Visit the main bcolz site repository at: http://github.com/Blosc/bcolz

Home of Blosc compressor: http://blosc.org

User's mail list: http://groups.google.com/group/bcolz (bcolz@googlegroups.com)

An introductory talk (20 min) about bcolz at EuroPython 2014. Slides here.

License

Please see BCOLZ.txt in LICENSES/ directory.

Share your experience

Let us know of any bugs, suggestions, gripes, kudos, etc. you may have.

Enjoy Data!