Metadata-Version: 2.4
Name: spirogram
Version: 1.0.0
Summary: A spiral visualization for chronological data.
Author: Sucharita Mallick, Rachita Mondal, Garcia Sun
Author-email: Sarah Mensah <sarahmensah@montana.edu>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/sfmensah/spirogram
Project-URL: Issues, https://github.com/sfmensah/spirogram/issues
Keywords: spiral,chronogram,data visualization,chronological data,longitudinal data,genomics
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: matplotlib
Dynamic: license-file


# Spirogram


**Documentation:** [User Manual](https://github.com/sfmensah/spirogram/blob/main/docs/user_manual.pdf) · **Source Code:** [GitHub](https://github.com/sfmensah/spirogram) · **Report Issues:** [Issues](https://github.com/sfmensah/spirogram/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.

```bash
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.

```python
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

| LaterDate | EarlierDate | Distance |
|-----------|-------------|----------|
|2020-04-10|2020-03-15|0.0024|
|2020-04-15|2020-03-20|0.0031|


### 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

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


![Long-format Example](https://raw.githubusercontent.com/sfmensah/spirogram/main/images/example1.png)


### Matrix-format data

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

![Matrix-format Example](https://raw.githubusercontent.com/sfmensah/spirogram/main/images/example2.png)


## Main Function

```python
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](https://github.com/sfmensah/spirogram/blob/main/docs/user_manual.pdf) for a complete description of every argument.


## License

This project is distributed under the [GNU General Public License v3.0](https://github.com/sfmensah/spirogram/blob/main/LICENSE).

## 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.
