Metadata-Version: 2.4
Name: tscat
Version: 0.5.1
Summary: A library which stores, loads and filters time-series-events and catalogues.
Project-URL: homepage, https://github.com/SciQLop/tscat
Project-URL: repository, https://github.com/SciQLop/tscat
Project-URL: documentation, https://github.com/SciQLop/tscat
Author-email: Patrick Boettcher <p@yai.se>
Maintainer-email: Patrick Boettcher <p@yai.se>, Alexis Jeandet <alexis.jeandet@member.fsf.org>
License: GNU GENERAL PUBLIC LICENSE
                              Version 3, 29 June 2007
        
            Library handling the time serie event and catalogues
            Copyright (C) 2021  Patrick Boettcher
        
            This program is free software: you can redistribute it and/or modify
            it under the terms of the GNU General Public License as published by
            the Free Software Foundation, either version 3 of the License, or
            (at your option) any later version.
        
            This program is distributed in the hope that it will be useful,
            but WITHOUT ANY WARRANTY; without even the implied warranty of
            MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
            GNU General Public License for more details.
        
            You should have received a copy of the GNU General Public License
            along with this program.  If not, see <http://www.gnu.org/licenses/>.
        
        Also add information on how to contact you by electronic and paper mail.
        
          You should also get your employer (if you work as a programmer) or school,
        if any, to sign a "copyright disclaimer" for the program, if necessary.
        For more information on this, and how to apply and follow the GNU GPL, see
        <http://www.gnu.org/licenses/>.
        
          The GNU General Public License does not permit incorporating your program
        into proprietary programs.  If your program is a subroutine library, you
        may consider it more useful to permit linking proprietary applications with
        the library.  If this is what you want to do, use the GNU Lesser General
        Public License instead of this License.  But first, please read
        <http://www.gnu.org/philosophy/why-not-lgpl.html>.
        
License-File: AUTHORS.rst
License-File: LICENSE
Keywords: CDF,amda,cdpp,nasa-data,plasma-physics,satellite
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: alembic
Requires-Dist: appdirs>=1.4.4
Requires-Dist: astropy
Requires-Dist: orjson
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: typing-extensions>=3.7
Provides-Extra: doc
Requires-Dist: sphinx; extra == 'doc'
Requires-Dist: sphinx-autodoc-typehints; extra == 'doc'
Requires-Dist: sphinx-rtd-theme; extra == 'doc'
Provides-Extra: test
Requires-Dist: appdirs-stubs; extra == 'test'
Requires-Dist: ddt; extra == 'test'
Requires-Dist: flake8; extra == 'test'
Requires-Dist: mypy; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-timeout; extra == 'test'
Requires-Dist: pytest>=4.6.5; extra == 'test'
Description-Content-Type: text/markdown

# tscat — Time Series Catalogues

![Test Status](https://github.com/SciQLop/tscat/actions/workflows/test_main.yml/badge.svg)
![Coverage Status](https://codecov.io/gh/SciQLop/tscat/branch/main/graph/badge.svg)

tscat is a Python library for managing catalogues of time intervals (events). It is the catalogue backend for [SciQLop](https://github.com/SciQLop/SciQLop) and is designed for space physics workflows — storing event lists such as magnetopause crossings, ICMEs, or any user-defined intervals with arbitrary metadata.

Events are persisted in a local SQLite database. No server required.

## Installation

```bash
pip install tscat
```

## Quick start

```python
from datetime import datetime
from tscat import create_event, create_catalogue, add_events_to_catalogue, save

catalogue = create_catalogue("Bow shock crossings", author="Alice",
                             tags=["MMS", "bow_shock"])

events = [
    create_event(datetime(2023, 1, 1, 10, 0), datetime(2023, 1, 1, 10, 30),
                 author="Alice", tags=["inbound"], Bz_max=12.5),
    create_event(datetime(2023, 1, 3, 14, 0), datetime(2023, 1, 3, 14, 45),
                 author="Alice", tags=["outbound"], Bz_max=8.3),
]

add_events_to_catalogue(catalogue, events)
save()
```

Any keyword argument beyond the fixed fields (`start`, `stop`, `author`, `tags`, `products`, `rating`) becomes a custom attribute stored alongside the event.

## Filtering

Retrieve events matching conditions using a natural Python DSL:

```python
from tscat import get_events
from tscat.filtering import event, In, Field

# Events after a date
get_events(event.start >= datetime(2023, 1, 2))

# Combine predicates with &, |, ~
get_events((event.author == "Alice") & In("inbound", Field("tags")))

# Filter on custom attributes
get_events(event.Bz_max > 10.0)
```

## Dynamic catalogues

A catalogue with a `predicate` automatically includes all matching events:

```python
from tscat import create_catalogue
from tscat.filtering import event

dynamic = create_catalogue(
    "High Bz events", author="Alice",
    predicate=event.Bz_max > 10.0,
)
```

## Import / export

Share catalogues as JSON or VOTable (AMDA-compatible):

```python
from tscat import export_json, import_json, export_votable_str

json_str = export_json(catalogue)
import_json(json_str)  # into another database
```

## Documentation

Full usage guide: [docs/usage.rst](docs/usage.rst)

## Development

This project uses [uv](https://docs.astral.sh/uv/):

```bash
uv sync --extra test
uv run pytest
uv run flake8 tscat tests
```

## License

GNU General Public License v3
