cachai 0.1.0

Customizable visualization toolkit for science

---

---

cachai (Custom Axes and CHarts Advanced Interface) is a fully customizable Python visualization toolkit designed to deliver polished, publication-ready plots built on top of Matplotlib. Currently, the package includes the ChordDiagram module as its primary feature. For details on the toolkit’s capabilities, motivations and future projections, refer to this paper.

The code documentation is currently consolidated in docs/documentation.md. To contribute or report bugs, please visit the issues page.

:cookie: Fun fact:

"Cachai" (/kɑːˈtʃaɪ/) is a slang word from Chilean informal speech, similar to saying "ya know?" or "get it?" in English. Don't know how to pronounce it? Think of "kah-CHAI" (like "cut" + "chai" tea, with stress on "CHAI").

:gear: Installation guide

Installing cachai

All official releases of cachai are published on PyPI. To install, simply run:

pip install cachai

If you want to verify that cachai works correctly on your system, you can install it with optional testing dependencies by running:

pip install pytest

Requirements

cachai has been tested on Python >= 3.10.

Core dependencies: This Python packages are mandatory:

• numpy >= 2.0.0
• matplotlib >= 3.9.0
• pandas >= 2.3.0
• scipy >= 1.13.0
• seaborn >= 0.12.0

Optional dependencies:
This Python packages are optional:

• pytest >= 7.1.0 (Only required for testing)

To verify that cachai installed correctly and is functioning properly on your system, you can run:

import cachai

cachai.run_tests()

Alternatively, execute this in your terminal:

cachai-test

:hatching_chick: Getting started

You’ll typically need the following imports to begin using cachai:

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
import cachai.chplot as chp

To quickly test cachai, you can load one of the included datasets. Currently, the available datasets are tailored for Chord Diagram use cases. Here’s a minimal example using the large_correlations dataset to generate a Chord Diagram:

import cachai.data as chd
import cachai.chplot as chp

data = chd.load_dataset('large_correlations')
chp.chord(data)

[!NOTE] Downloading datasets requires an internet connection. If the files are already cached (i.e., you’ve accessed them before), cachai will use the local copies, allowing offline work.

For more advanced examples, explore the Jupyter notebooks in the docs/notebooks.

:black_nib: Citing cachai

If cachai contributed to a project that resulted in a publication, please cite this paper.

Example citation format:

@ARTICLE{Beltran_2025,
       author = {{Beltr{\'a}n}, D. and {Dantas}, M.~L.~L.},
        title = "{CACHAI's First Module: A Fully Customizable Chord Diagram for Astronomy and Beyond}",
      journal = {Research Notes of the American Astronomical Society},
     keywords = {Interdisciplinary astronomy, Astronomy data analysis, Astronomy data visualization, Astronomy software, 804, 1858, 1968, 1855},
         year = 2025,
        month = aug,
       volume = {9},
       number = {8},
          eid = {216},
        pages = {216},
          doi = {10.3847/2515-5172/adf8df},
       adsurl = {https://ui.adsabs.harvard.edu/abs/2025RNAAS...9..216B},
      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}