Skip to content

Welcome to Circumplex

PyPI version pre-commit CI status Linting status Documentation status License

Overview

Image title Image title

circumplex is a Python package for analyzing and visualizing circumplex data. It provides a set of tools for analyzing and visualizing circumplex data, following the Structural Summary Method. This project is a Python implementation based on the R circumplex package. Our goal is to provide a similar functionality and experience for Python users.

This project is a Python implementation based on the R circumplex package. Our goal is to provide a similar functionality and experience for Python users.

Massive update

The upcoming 0.3 release is the largest update to circumplex so far. It introduces a modular package structure, expanded SSM and plotting workflows, built-in instrument and tidying utilities, stronger regression coverage against the R package, and refreshed documentation and CI/release infrastructure. See the changelog for release notes.

Note

This project is still under development. We're working hard to make it as good as possible, but there may be bugs or missing features. If you find any issues, please let us know by submitting an issue on Github.

Key Features

  • SSM Analysis: Mean-based and correlation-based structural summary methods
  • Bootstrap Confidence Intervals: Robust statistical inference for SSM parameters
  • Visualization: Publication-ready circular plots and curve plots
  • Built-in Instruments: IIP-SC, CSIG, IPIP-IPC with normative data
  • Flexible Instrument System: Easy registration of custom circumplex measures
  • Data Tidying: Ipsatization, scoring, and normative standardization

Quick Start

Installation

Install the latest release from PyPI:

pip install circumplex

Basic Usage

from circumplex import load_dataset, ssm_analyze, OCTANTS

# Load sample data
data = load_dataset('jz2017')

# Define scale columns and their angular positions
scales = ['PA', 'BC', 'DE', 'FG', 'HI', 'JK', 'LM', 'NO']
angles = OCTANTS  # [90, 135, 180, 225, 270, 315, 360, 45]

# Perform SSM analysis
results = ssm_analyze(data, scales=scales, angles=angles)

# View results
results.summary()

# Create visualizations
results.plot_circle()
results.plot_curve()

Documentation

Requirements

  • Python 3.11, 3.12, or 3.13
  • NumPy, Pandas, SciPy, Matplotlib, Seaborn

Project Status

This project is in active development. Core SSM analysis functionality is implemented with full numerical parity to the R package (validated to 3+ decimal places). Additional features and documentation are being added continuously.

Contributing

Contributions are welcome! Please see the GitHub repository for guidelines.

Acknowledgments

This project is developed in collaboration with the Centre for Advanced Research Computing, University College London.

Author: Andrew Mitchell (andrew.mitchell.research@gmail.com)

Based on: The R circumplex package by Jeffrey Girard and colleagues

License