PyForce
Python implementation of ggforce-style annotations for matplotlib.
PyForce brings the elegant annotation capabilities of R's ggforce package to Python's matplotlib. Create publication-quality visualizations with smart annotations.
Features
- Smart Point Annotations (
annotate_points) - Elbow connectors with adjustText for collision avoidance - Margin Annotations (
annotate_margin) - 3-segment connectors with labels at plot edges - Edge Annotations (
annotate_edge) - Universal function for heatmaps, line plots, any plot - Convex Hull Groupings (
geom_mark_hull) - Smooth boundaries around point groups
Installation
pip install pyforce-plot
Or install from source:
git clone https://github.com/albert-ying/pyforce
cd pyforce
pip install -e .
Examples
Smart Elbow Annotations
from pyforce import annotate_points
annotate_points(
ax, x, y,
labels=gene_names,
indices=sig_indices,
point_size=60,
connector_type="elbow",
force_points=1.5,
)
Margin Annotations (3-segment connectors)
from pyforce import annotate_margin
annotate_margin(
ax, x, y,
labels=gene_names,
indices=sig_indices,
side="both", # 'right', 'left', or 'both'
)
Edge Annotations (Universal)
Works for heatmaps, line plots, or any plot:
from pyforce import annotate_edge
# For heatmap rows
annotate_edge(
ax,
y_positions=[74, 75, 76],
labels=["Target_A", "Target_B", "Target_C"],
x_start=n_cols - 0.5, # Heatmap edge
min_spacing=2.0,
)
# For line plot ends
annotate_edge(
ax,
y_positions=[y1[-1], y2[-1], y3[-1]],
labels=["Line 1", "Line 2", "Line 3"],
x_start=x[-1], # End of lines
min_spacing=0.4,
)
Smart dodge: Straight line when labels are far apart, 3-segment (1/3 + 1/3 + 1/3) when close.
Hull Annotations
from pyforce import geom_mark_hull
geom_mark_hull(
ax, x, y,
groups=groups,
labels=["Cluster A", "Cluster B", "Cluster C"],
hull_alpha=0.12,
)
API Reference
annotate_points()
Smart elbow annotations with adjustText collision avoidance.
| Parameter | Type | Default | Description |
|---|---|---|---|
ax |
Axes | required | Matplotlib axes |
x, y |
array-like | required | Point coordinates |
labels |
list[str] | required | Labels for points |
indices |
array-like | None | Indices to annotate |
connector_type |
str | 'elbow' | 'elbow', 'straight', 'horizontal' |
force_points |
float | 1.0 | Repulsion from points |
annotate_margin()
Labels aligned at plot margins with 3-segment connectors.
| Parameter | Type | Default | Description |
|---|---|---|---|
ax |
Axes | required | Matplotlib axes |
x, y |
array-like | required | Point coordinates |
labels |
list[str] | required | Labels for points |
side |
str | 'right' | 'right', 'left', 'both' |
annotate_edge()
Universal edge annotation for any plot type.
| Parameter | Type | Default | Description |
|---|---|---|---|
ax |
Axes | required | Matplotlib axes |
y_positions |
list[float] | required | Y positions to annotate |
labels |
list[str] | required | Labels |
x_start |
float | None | X where connectors start |
side |
str | 'right' | 'right' or 'left' |
min_spacing |
float | auto | Min spacing between labels |
geom_mark_hull()
Convex hull annotations for grouped data.
| Parameter | Type | Default | Description |
|---|---|---|---|
ax |
Axes | required | Matplotlib axes |
x, y |
array-like | required | Point coordinates |
groups |
array-like | None | Group membership |
labels |
list[str] | None | Group labels |
hull_alpha |
float | 0.2 | Fill transparency |
Requirements
- Python >= 3.8
- numpy >= 1.20.0
- matplotlib >= 3.5.0
- scipy >= 1.7.0
- adjustText >= 0.8
License
MIT License
Acknowledgments
Inspired by ggforce for R.
Metadata
Release files for pyforce-plot 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pyforce_plot-0.1.1.tar.gz | 17.1 kB | Without provenance | Details for pyforce_plot-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pyforce_plot-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for pyforce_plot-0.1.1-py3-none-any.whl |
Total release size: 31.6 kB
Release files / pyforce_plot-0.1.1.tar.gz
| Download URL | pyforce_plot-0.1.1.tar.gz |
|---|---|
| Size | 17.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a875c3df7bd85056ea454ec55b32ce947fce30182cfec06f047007500639cf9a
|
|
BLAKE2b-256 checksum How to use checksums |
1f8c31994d83082a8c27740bdae74106fb359213303f9772151cd6439cef540a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.14
|
Release files / pyforce_plot-0.1.1-py3-none-any.whl
| Download URL | pyforce_plot-0.1.1-py3-none-any.whl |
|---|---|
| Size | 14.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
97d5aeafc94a63d9d310f78f8684ded2dc41589716ffcba14b104c3dd098f238
|
|
BLAKE2b-256 checksum How to use checksums |
1af6c580629ca35c5976c7d1a75b622087f7a85f8707ff2ef9ae907f0fb6aab6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.14
|
Security for pyforce-plot 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.