Metadata-Version: 2.4
Name: visdata
Version: 0.2.0.dev1
Summary: Package for data visualisation.
Author-email: Philipp Meder <148459685+PhilippMeder@users.noreply.github.com>
License: BSD 3-Clause License
        
        Copyright (c) 2024-2025, Philipp Meder.
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Project-URL: Homepage, https://github.com/philippmeder/visdata
Project-URL: Issues, https://github.com/philippmeder/visdata/issues
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>2
Requires-Dist: matplotlib>3.8
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

<h1 align="center">
<img src="https://raw.githubusercontent.com/PhilippMeder/visdata/main/docs/figs/visdata_logo.svg" width="300">
</h1>

[![PyPi badge](https://img.shields.io/pypi/v/visdata)](https://pypi.org/project/visdata/)
[![Python versions badge](https://img.shields.io/pypi/pyversions/visdata.svg)](https://pypi.org/project/visdata/)
[![License badge](https://img.shields.io/pypi/l/visdata.svg)](https://github.com/PhilippMeder/visdata/blob/main/LICENSE)
[![GitHub actions status badge](https://github.com/PhilippMeder/visdata/actions/workflows/test-python-package.yml/badge.svg)](https://github.com/PhilippMeder/visdata/actions/workflows/test-python-package.yml)
[![GitHub issues badge](https://img.shields.io/badge/issue_tracking-github-blue.svg)](https://github.com/PhilippMeder/visdata/issues)

**Useful tools for data visualisation, e.g. 2D-profiles, comparison of measurements, or tables.**

> [!WARNING]
> This package is still under development. The features work, but the API might change in the future.

Developed and maintained by [Philipp Meder](https://github.com/philippmeder).

* **Source code:** https://github.com/philippmeder/visdata
* **Report bugs:** https://github.com/philippmeder/visdata/issues

## Quick Start

Install this package:

```bash
pip install visdata
```

You can get the newest stable version with:

```bash
pip install git+https://github.com/philippmeder/visdata
```


## License

Distributed under the [BSD 3-Clause License](https://github.com/PhilippMeder/visdata/blob/main/LICENSE).

## Features

This README covers the following:
1. [Profile2d Plot for 2D-histograms](#profile2d-plot-for-2d-histograms)
2. [Visual Comparison of Measurements](#visual-comparison-of-measurements-including-uncertainties)
3. [Table Output for Terminal, CSV, and LaTeX](#formatted-table-output-for-terminal-csv-and)
4. [Additional Features](#additional-features)

Check out the [examples](./examples)!

### Profile2d Plot for 2D-histograms
Profiles allow a visual interpretation of the data, e.g. in the following figures where red markers represent the mean with the standard error on the mean and pink markers represent the median of the y-data in each x-bin:

Profile shows an angle-dependent deviation from the zero line | Profile shows deviations from the model
----|----
![](https://raw.githubusercontent.com/PhilippMeder/visdata/main/docs/figs/profile2d_example_1.png) | ![](https://raw.githubusercontent.com/PhilippMeder/visdata/main/docs/figs/profile2d_example_2.png)

Create a ``Profile2d`` object with your data and directly add the profile to a plot (you may adjust what and how to plot, see Histogramd2d example) or get the profile data and do the plotting yourself.

```python
from matplotlib import pyplot as plt
from visdata import Profile2d, plot_profile2d

# Example data
x, y = ...

# Create normal 2D-histogram
fig, ax = plt.subplots()
hist, xedges, yedges, image = ax.hist2d(x, y, bins=10)

# Create profile and add it to the axis (using default config)
profile = Profile2d(x, y, bins=10)
plot_profile2d(ax, profile)
```

You can also use a ``Histogram2d`` object which gives you the ability to directly draw a profile.
In addition, it allows to plot 1D-histograms of the x/y data on the margins, which looks like this:

![](https://raw.githubusercontent.com/PhilippMeder/visdata/main/docs/figs/histogram2d_example.png)

You can configure the marginal plots and the profile, see the following example:

```python
from visdata import Histogram2d, Profile2dMeanPlotter, plot_profile2d

hist = Histogram2d(x, y, bins=bins)
# Configure the marginal histograms if wanted, e.g. the color
# Keywords are passed to 'ax.hist'
hist.configure_marginal(color="C2")
# Configure the profile with a set of configs, e.g. only plot the mean but change the marker
hist.profile_plotters = [
    # Keywords are passed to 'ax.errorbar'
    Profile2dMeanPlotter(marker="v")
    # You could add another config here, e.g. to plot the median
]
# Plot hist2d with colorbar + 1D-histograms and profile
hist_result = hist.plot(marginal=True, profile=True)
```

### Visual Comparison of Measurements Including Uncertainties

Sometimes it is easier to understand if different measurements are compatible with each other by looking at a visualisation, e.g. you want to compare your own measurements of some parameters with the measurements presented in other publications with respect to the uncertainties.
The example shows
- *statistical uncertainties* as medium thick errorbars,
- *systematic uncertainties* as thin errorbars with caps,
- *quadratic combination* of both as thick errobars with transparency (for visual guidance only, this value is meaningless).

You can  of course configure what and how to plot.
In this example, *Publication 1* did not provide any values for $\beta$ and $\delta$ while *Publication 2* did not provide a value for $\gamma$.

![](https://raw.githubusercontent.com/PhilippMeder/visdata/main/docs/figs/compare_measurements.png)

```python
from visdata import (
    Measurement, MeasurementResult, CompareMeasurementsPlot
)

# Example measurements for multiple parameters
measurement_1 = Measurement(
    "Measurement name",
    {
        "par 1 name": MeasurementResult(
            1, statistical=0.1, systematic=0.05
        ),
        ...
    }
)
measurement_2 = ...

# Create plot object and do the plotting
comp_plot = CompareMeasurementsPlot(measurment_1, measurement_2)
fig, axs, handles, labels = comp_plot.plot()

# At this point you can configure fig and axs the usual way or include a legend with handles and labels
...
```

### Formatted Table Output for Terminal, CSV, and LaTeX

Create a ``Table`` object from a 2D-array and get the wanted output, either as a nice terminal output, a CSV table, or a LaTeX table ready for your document.
You can name the columns and rows independently and add a caption if you want. Furthermore, you can specify a formatter for the data.

```python
from visdata import Table

# Setup data and example formatter
data, description, column_labels, row_labels = ...
formatter = "5.2f"

# Create table object
table = Table(
    data,
    description=description,
    column_labels=column_labels,
    row_labels=row_labels
)
# Print the terminal representation as well as CSV and LaTeX
print(table)
print(table.csv(formatter=formatter))
print(table.latex(formatter=formatter))
```

The LaTeX output returns a scientific table.
The terminal representation mimics this, e.g.

```console
            Table: Some important values
────────────────────────────────────────────────────
              a0            a1            a2
────────────────────────────────────────────────────
A0              0.00e+00      1.00e+00      2.00e+00
A1              3.00e+00      4.00e+00      5.00e+00
────────────────────────────────────────────────────
```

### Additional Features
- Decorators for code development, e.g. timer for function execution
- Intervals
- Functions like secans or cos called with angle in degrees
- Regular polygons for plotting and calculation of their most important properties
- Some utilities for matplotlib output

## Requirements and Dependencies

Following **requirements** must be satisfied:

* `Python 3.10+` (developed with `Python 3.13`, tested with `Python 3.10+`, lower version are not working due to the use of `match ... case` and `Union`)
* `numpy 2+`
* `matplotlib 3.8+`
