Metadata-Version: 2.3
Name: lstein
Version: 1.0.0
Summary: LStein: a new approach to visualizing sparse 2.5-dimensional data in 2D
Keywords: visualization,projection
Author: Lukas Steinwender
Author-email: Lukas Steinwender <lukas.steinwender99+lstein@gmail.com>
License: MIT License
         
         Copyright (c) 2025 Lukas Steinwender
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Dist: matplotlib>=3.10.5
Requires-Dist: numpy>=2.3.2
Requires-Dist: plotly>=6.4.0
Maintainer: Lukas Steinwender
Maintainer-email: Lukas Steinwender <lukas.steinwender99+lstein@gmail.com>
Requires-Python: >=3.11
Project-URL: Docs, https://lstein.readthedocs.io/
Project-URL: Homepage, https://lstein.readthedocs.io/
Project-URL: Issues, https://github.com/TheRedElement/LStein/issues
Project-URL: Repository, https://github.com/TheRedElement/LStein
Description-Content-Type: text/markdown


# WELCOME

![](gfx/lstein_logo.svg)


<!-- local table of contents -->
```{contents} Table of Contents
:local:
:depth: 3
```

<!-- block -->
> [!WARNING]
> Note, that this package is currently under development.
> Most functionalities should work, but changes will be implemented on a running basis and without notice.
> No tests have been performed yet.
<!-- block -->

<!-- block -->
> [!NOTE]
> This page summarizes the most common characteristics, pitfalls etc.
> Please refer to the paper (in prep) for a more detailed list and [Tutorials](docs/pages/tutorals.rst) for solutions to some known issues/missing features.
<!-- block -->

## Reference
If you use this code in your work please use this entry in your bibliography (for now):

```latex
@software{PY_Steinwender2025_lstein,
	author    = {{Steinwender}, Lukas},
	title     = {LStein: Linking Series to envision information neatly},
	month     = Jul,
	year      = 2025,
	version   = {latest},
	url       = {https://github.com/TheRedElement/LStein.git}
}
```


## Installation
You can easily install the package using [pip](https://pypi.org/project/pip/):

```shell
pip3 install git+https://github.com/TheRedElement/LStein.git
```

## Quick Start
Data used for [Tutorials](docs/pages/tutorals.rst) can be found in [data/](https://github.com/TheRedElement/LStein/blob/main/data/).
There are also a few other datasets so feel free to have a play around.
Each dataset is a `.csv` file with the following columns:

| Column | Description |
| :- | :- |
$\theta$-values | values to be plotted as azimuthal offset of the panel
$x$-values      | values to be plotted radially
$y$-values      | values to be plotted as an azimuthal offset constraint to a circle-sector
$y$-errors      | errors assigned to $y$-values
`processing context`  | which processing was used

The demo will behave as follows:
1. take the first 3 columns (in order) as $\theta$-, $x$-, $y$-values
2. take the column names as axis-labels
3. plot a scatter for `processing context="raw"`
4. plot a line for `processing context!="raw"`

You can try your own data as well, but make sure to
1. follow the above-mentioned conventions
2. add at least one row with `processing context!="raw"`
    1. if you just have raw data, you can always just duplicate the rows and change half of the rows to `processing context!="raw"`

```{raw} html
<iframe src="_static/_notebooks/quickstart.html" width=100% height=600px></iframe>
```

## Example Plots
|||
|:-|:-|
<a name=fig-lsteinsnia></a>
|![](gfx/1189_snia_elasticc.png)|![](gfx/2025_tde_elasticc.png)|
|Example for visualizing an [ELAsTICC](https://portal.nersc.gov/cfs/lsst/DESC_TD_PUBLIC/ELASTICC/) SN Ia. I compare `LStein` on the left to traditional displays on the right. | Example for visualizing an [ELAsTICC](https://portal.nersc.gov/cfs/lsst/DESC_TD_PUBLIC/ELASTICC/) TDE. I compare `LStein` on the left to traditional displays on the right. |
|![](gfx/0901_snii_elasticc.png)|![](gfx/sin_simulated.png)|
|Example for visualizing an [ELAsTICC](https://portal.nersc.gov/cfs/lsst/DESC_TD_PUBLIC/ELASTICC/) SN II. I compare `LStein` on the left to traditional displays on the right. | Example for visualizing a set of artificially simulated sine waves. I compare `LStein` on the left to traditional displays on the right. |

## Advantages and Downsides

### Pros

+ no overcrowded panels
+ similar $\theta$-values (i.e., passbands) are plotted closer together
+ allows to preserve amplitude-differences across $\theta$-values for same $y$-values
+ allows depicting arbitrary number of $\theta$-values (by means of reducing the angular size of each $\theta$-panel) 
+ works for people with color-blindness due to relational display of information
+ can be applied to variety of data (not only lightcurves)
	+ examples: spectra over time, different machine learning models, spiking neural networks
+ layout entirely customizable

### Cons

- projection effects close to `xmin`
- does currently *not* support plotting errorbars
	- workaround: plot another line if you want to indicate uncertainties


## Known Bugs
### Open

### Resolved
- [x] `y_projection_method="theta"` goes haywire for huge $x$-values (for sure $x\ge10000$)
    * the reason is the necessity to compute $\tan$ and $arc\tan$ when converting back and forth between coordinate systems
    * workarounds
        * formulate your series relative to some value so you remain in a reasonable range
        * use `y_projection_method="y"`


## TODO
* update [README.md](./README.md) once paper published
	* remove warning
	* adjust note