Spirogram

Documentation: User Manual · Source Code: GitHub · Report Issues: Issues

Spirogram is a Python package for creating spiral chronograms, a spiral visualization designed for chronological data. The package is intended for datasets containing pairs of collection dates together with an associated quantitative measurement. The measurement may represent quantities such as genetic distances, similarity scores, temperature differences, or any other numeric value defined between two time points.

The package accepts multiple input formats, performs data validation and preprocessing, transforms the data into spiral coordinates, and generates customizable spiral chronograms.

Installation

Install the package using pip.

pip install spirogram

Requirements

• Python 3.10 or later

The following packages are installed automatically when installing spirogram:

• NumPy
• pandas
• matplotlib

Supported File Formats

Input data may be provided as .csv, .dat, or .json files, or as a pandas DataFrame passed directly.

Quick Start

Import the package.

from spirogram import spirogram

Supported Input Formats

Long-format

Each row represents one pairwise comparison.

Required columns:

• Later collection date
• Earlier collection date
• Quantitative measurement

Example

Matrix-format

The input consists of a square distance matrix whose rows and columns correspond to collection dates. The package accepts

• Full matrices
• Upper triangular matrices
• Lower triangular matrices

The matrix is automatically converted internally into the standard long format before generating the spirogram.

Examples

The examples below use SARS-CoV-2 spike protein sequence data downloaded from the National Center for Biotechnology Information (NCBI). The sequences were collected in Illinois between March 2020 and April 2026, and pairwise genetic distances were calculated between collection dates.

Long-format data

spirogram(file="data/spiroExample_long.csv", dataFormat="long", 
laterDate="Date", earlierDate="EarlierDate", distance="Meankdistance")

Matrix-format data

spirogram(file="data/spiroExample_matrix.json", dataFormat="matrix",matrixType="full", invalidDates="drop", cmap="Spectral", turns=5)

Main Function

spirogram(...)

The package provides numerous options for customizing the visualization, including

• spiral spacing
• number of turns
• angular correction
• color maps
• point size
• color scale
• plot title
• colorbar label
• data coverage summary
• returning the processed data

See the User Manual for a complete description of every argument.

License

This project is distributed under the GNU General Public License v3.0.

Acknowledgements

We would like to express our gratitude to Dr. Mengfei Ho, Assistant Research Professor, and Dr. Brenda Wilson, Professor, Department of Microbiology, School of Molecular & Cellular Biology, University of Illinois Urbana-Champaign, for their guidance, many helpful discussions and feedback throughout this project.

We thank Professor Douglas Simpson, Director of the Institute for Mathematical and Statistical Innovation (IMSI), and acknowledge the support of the IMSI Summer Internship Program, funded by the National Science Foundation Grant No. DMS-2425650.