tdemocracy 0.0.3__tar.gz

tdemocracy-0.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026, Jannis Necker
+
+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.

tdemocracy-0.0.3/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.3
+Name: tdemocracy
+Version: 0.0.3
+Summary: Listen to nuclear alerts from the Vera Rubin Observatory for the TDEmocracy project
+Author: Jannis Necker
+Author-email: necker@strw.leidenuniv.nl
+Requires-Python: >=3.11,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: dev
+Provides-Extra: docs
+Requires-Dist: autodoc-pydantic[erdantic] (>=2.2.0,<3.0.0) ; extra == "docs"
+Requires-Dist: hop-client (>=0.12.1,<0.13.0)
+Requires-Dist: mypy (>=1.5.1) ; extra == "dev"
+Requires-Dist: pre-commit (>=3.4.0) ; extra == "dev"
+Requires-Dist: py-avro-schema (>=3.8.2,<4.0.0)
+Requires-Dist: pydantic (>=2.13.4,<3.0.0)
+Requires-Dist: pydantic-settings (>=2.14.2,<3.0.0)
+Requires-Dist: pytest (>=7.2) ; extra == "dev"
+Requires-Dist: pytest-cov (>=4.0) ; extra == "dev"
+Requires-Dist: sphinx (>=7.0) ; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints (>=1.25) ; extra == "docs"
+Requires-Dist: sphinx-rtd-theme (>=3.1.0,<4.0.0) ; extra == "docs"
+Requires-Dist: types-pyyaml (>=6.0.12.20260518,<7.0.0.0) ; extra == "dev"
+Project-URL: Documentation, https://JannisNe.github.io/tdemocracy/
+Project-URL: Repository, https://github.com/JannisNe/tdemocracy
+Description-Content-Type: text/markdown
+
+[![Release](https://img.shields.io/github/v/release/JannisNe/tdemocracy)](https://img.shields.io/github/v/release/JannisNe/tdemocracy)
+[![Build status](https://img.shields.io/github/actions/workflow/status/JannisNe/tdemocracy/main.yml?branch=main)](https://github.com/JannisNe/tdemocracy/actions/workflows/main.yml?query=branch%3Amain)
+[![codecov](https://codecov.io/gh/JannisNe/tdemocracy/branch/main/graph/badge.svg)](https://codecov.io/gh/JannisNe/tdemocracy)
+[![Commit activity](https://img.shields.io/github/commit-activity/m/JannisNe/tdemocracy)](https://img.shields.io/github/commit-activity/m/JannisNe/tdemocracy)
+[![License](https://img.shields.io/github/license/JannisNe/tdemocracy)](https://img.shields.io/github/license/JannisNe/tdemocracy)
+[![Deploy Docs](https://github.com/JannisNe/tdemocracy/actions/workflows/deploy-docs.yml/badge.svg)](https://jannisne.github.io/tdemocracy)
+
+# Listen to TDEmocracy!
+
+This repository contains the data model used in the stream of candidate nuclear transients for the TDEmocracy project.
+
+## Prerequisites
+
+You need an account at the [SCIMMA Hopskotch service](https://scimma.org/hopskotch). Please contact the TDEmocracy lead to have your account added to the Ampel-TDEmocracy group. You can store your username and password in your environment variables `TDEMOCRACY_USERNAME` and `TDEMOCRACY_PASSWORD` or in a `.env` file in the root of the repository.
+
+## Installation
+
+Pull the repository and install the dependencies with [`poetry`](https://python-poetry.org/):
+
+```bash
+git clone https://github.com/JannisNe/tdemocracy.git
+cd tdemocracy
+poetry install
+```
+
+In the future, you will be able to install the package via `pip`:
+
+```bash
+pip install tdemocracy
+```
+
+## Usage:
+
+```python
+from tdemocracy.listen import listen_to_nuclear_stream
+
+for report in listen_to_nuclear_stream():
+    # do something with the report
+    ...
+```
+
+Find more detailed documentation [here](https://jannisne.github.io/tdemocracy).
+
+---
+
+Repository initiated with [fpgmaas/cookiecutter-poetry](https://github.com/fpgmaas/cookiecutter-poetry).
+

tdemocracy-0.0.3/README.md

@@ -0,0 +1,46 @@
+[![Release](https://img.shields.io/github/v/release/JannisNe/tdemocracy)](https://img.shields.io/github/v/release/JannisNe/tdemocracy)
+[![Build status](https://img.shields.io/github/actions/workflow/status/JannisNe/tdemocracy/main.yml?branch=main)](https://github.com/JannisNe/tdemocracy/actions/workflows/main.yml?query=branch%3Amain)
+[![codecov](https://codecov.io/gh/JannisNe/tdemocracy/branch/main/graph/badge.svg)](https://codecov.io/gh/JannisNe/tdemocracy)
+[![Commit activity](https://img.shields.io/github/commit-activity/m/JannisNe/tdemocracy)](https://img.shields.io/github/commit-activity/m/JannisNe/tdemocracy)
+[![License](https://img.shields.io/github/license/JannisNe/tdemocracy)](https://img.shields.io/github/license/JannisNe/tdemocracy)
+[![Deploy Docs](https://github.com/JannisNe/tdemocracy/actions/workflows/deploy-docs.yml/badge.svg)](https://jannisne.github.io/tdemocracy)
+
+# Listen to TDEmocracy!
+
+This repository contains the data model used in the stream of candidate nuclear transients for the TDEmocracy project.
+
+## Prerequisites
+
+You need an account at the [SCIMMA Hopskotch service](https://scimma.org/hopskotch). Please contact the TDEmocracy lead to have your account added to the Ampel-TDEmocracy group. You can store your username and password in your environment variables `TDEMOCRACY_USERNAME` and `TDEMOCRACY_PASSWORD` or in a `.env` file in the root of the repository.
+
+## Installation
+
+Pull the repository and install the dependencies with [`poetry`](https://python-poetry.org/):
+
+```bash
+git clone https://github.com/JannisNe/tdemocracy.git
+cd tdemocracy
+poetry install
+```
+
+In the future, you will be able to install the package via `pip`:
+
+```bash
+pip install tdemocracy
+```
+
+## Usage:
+
+```python
+from tdemocracy.listen import listen_to_nuclear_stream
+
+for report in listen_to_nuclear_stream():
+    # do something with the report
+    ...
+```
+
+Find more detailed documentation [here](https://jannisne.github.io/tdemocracy).
+
+---
+
+Repository initiated with [fpgmaas/cookiecutter-poetry](https://github.com/fpgmaas/cookiecutter-poetry).

tdemocracy-0.0.3/pyproject.toml

@@ -0,0 +1,126 @@
+[project]
+name = "tdemocracy"
+version = "0.0.3"
+description = "Listen to nuclear alerts from the Vera Rubin Observatory for the TDEmocracy project"
+readme = "README.md"
+requires-python = ">=3.11,<4.0"
+authors = [
+    { name = "Jannis Necker", email = "necker@strw.leidenuniv.nl" },
+]
+dependencies = [
+    "hop-client (>=0.12.1,<0.13.0)",
+    "py-avro-schema (>=3.8.2,<4.0.0)",
+    "pydantic (>=2.13.4,<3.0.0)",
+    "pydantic-settings (>=2.14.2,<3.0.0)",
+
+]
+
+[project.urls]
+Repository = "https://github.com/JannisNe/tdemocracy"
+Documentation = "https://JannisNe.github.io/tdemocracy/"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.2",
+    "pytest-cov>=4.0",
+    "mypy>=1.5.1",
+    "pre-commit>=3.4.0",
+    "types-pyyaml (>=6.0.12.20260518,<7.0.0.0)",
+]
+docs = [
+    "sphinx>=7.0",
+    "sphinx-autodoc-typehints>=1.25",
+    "autodoc-pydantic[erdantic] (>=2.2.0,<3.0.0)",
+    "sphinx-rtd-theme (>=3.1.0,<4.0.0)",
+]
+
+[build-system]
+requires = ["poetry-core>=2.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.mypy]
+files = ["tdemocracy"]
+disallow_untyped_defs = true
+disallow_any_unimported = true
+no_implicit_optional = true
+check_untyped_defs = true
+warn_return_any = true
+warn_unused_ignores = true
+show_error_codes = true
+plugins = [
+  "pydantic.mypy"
+]
+[[tool.mypy.overrides]]
+module = [
+    "hop.*",
+]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py313"
+line-length = 120
+fix = true
+lint.select = [
+    # flake8-2020
+    "YTT",
+    # flake8-bandit
+    "S",
+    # flake8-bugbear
+    "B",
+    # flake8-builtins
+    "A",
+    # flake8-comprehensions
+    "C4",
+    # flake8-debugger
+    "T10",
+    # flake8-simplify
+    "SIM",
+    # isort
+    "I",
+    # mccabe
+    "C90",
+    # pycodestyle
+    "E",
+    "W",
+    # pyflakes
+    "F",
+    # pygrep-hooks
+    "PGH",
+    # pyupgrade
+    "UP",
+    # ruff
+    "RUF",
+    # tryceratops
+    "TRY",
+]
+lint.ignore = [
+    # LineTooLong
+    "E501",
+    # DoNotAssignLambda
+    "E731",
+]
+
+[tool.ruff.format]
+preview = true
+
+[tool.coverage.report]
+skip_empty = true
+
+[tool.coverage.run]
+branch = true
+source = ["tdemocracy"]
+
+
+[tool.ruff.per-file-ignores]
+"tests/*" = ["S101"]
+
+[tool.poetry.group.docs]
+optional = true
+
+[tool.poetry.group.docs.dependencies]
+sphinx = ">=7.0"
+sphinx-autodoc-typehints = ">=1.25"
+erdantic = ">=0.3.0"

tdemocracy-0.0.3/tdemocracy/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.3"

tdemocracy-0.0.3/tdemocracy/listen.py

@@ -0,0 +1,49 @@
+import logging
+from collections.abc import Generator
+from typing import Any
+
+from hop import Stream
+from hop.auth import Auth
+from hop.io import StartPosition
+
+from tdemocracy import __version__ as tdemocracy_version
+from tdemocracy.model import NuclearTransientReport
+from tdemocracy.settings import Settings
+
+LOGGER = logging.getLogger(__name__)
+
+
+def listen_to_nuclear_stream(
+    start_at: Any = StartPosition.EARLIEST,
+    until_eos: bool = False,
+    settings: Settings | None = None,
+    skip_other_versions: bool = False,
+) -> Generator[NuclearTransientReport]:
+    """
+    Listen to Nuclear stream
+
+    :param start_at: where to start the stream, either of StartPosition.EARLIEST or StartPosition.LATEST
+    :type start_at: Any
+    :param until_eos: Stop loop when the end of the stream is reached or wait for next message (default)
+    :type until_eos: bool
+    :param settings: Settings to use, if not passed reads the corresponding from the environment or a `.env` file. See :class:`tdemocracy.settings.Settings` for details.
+    :type settings: Settings | None
+    :param skip_other_versions: Skip alerts with wrong versions (default)
+    :type skip_other_versions: bool
+    """
+    _settings = settings or Settings()
+    auth = Auth(_settings.username, _settings.password)
+    stream = Stream(auth=auth, start_at=start_at, until_eos=until_eos)
+
+    with stream.open(f"kafka://kafka.scimma.org/{_settings.topic}", mode="r", group_id=_settings.group_id) as s:
+        LOGGER.info(f"Listening to {_settings.topic}...")
+        for message in s:
+            LOGGER.debug("Received message")
+            if ((mv := message.content.get("model_version")) is None) or (mv != tdemocracy_version):
+                if skip_other_versions:
+                    LOGGER.debug(f"Skipping version {mv}")
+                    continue
+                else:
+                    msg = f"Received message with wrong model_version: {mv}, expected: {tdemocracy_version}"
+                    raise ValueError(msg)
+            yield NuclearTransientReport.model_validate(message.content)

tdemocracy-0.0.3/tdemocracy/model.py

@@ -0,0 +1,127 @@
+from collections.abc import Sequence
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict
+
+
+class PhotometricPoint(BaseModel):
+    """
+    Observed photometric point in an LSST alert report.
+    Forced photometry (diaForcedSource) takes preference over alert photometry (diaSource).
+    """
+
+    id: int
+    """diaSourceId or diaForcedSourceId"""
+    source: Literal["LSST_DP", "LSST_FP"]
+    """id source"""
+    time: float
+    """midpointMjdTai"""
+    flux: float
+    """psfFlux"""
+    fluxerr: float
+    """psfFluxErr"""
+    band: str
+    """band"""
+    zp: float
+    """Photometric zero point"""
+    zpsys: str
+    """Zero point system"""
+
+
+class Object(BaseModel):
+    """Object associated with an LSST alert report (diaObject)"""
+
+    id: int
+    """diaObjectId"""
+    external_id: str | None = None
+    """External Object ID"""
+    ra: float
+    """Right ascension (ra; deg)"""
+    ra_err: float | None = None
+    """Right ascension uncertainty (raErr; deg)"""
+    dec: float
+    """Declination (dec; deg)"""
+    dec_err: float | None = None
+    """Declination uncertainty (decErr; deg)"""
+    ra_dec_cov: float | None = None
+    """Right ascension/declination covariance (ra_dec_Doc; deg2)"""
+    source: str
+    """Data source"""
+
+
+class Host(BaseModel):
+    """Host identified through catalog matching"""
+
+    name: str | None
+    """Name of the identifying ampel unit"""
+    source: str | list[str]
+    """Names of the catalogs containing this host"""
+    redshift: float | None
+    """Mean of the best redshift category for all catalog sources containing redshifts (see https://github.com/AmpelAstro/Ampel-HU-astro/blob/main/ampel/contrib/hu/t2/T2DigestRedshifts.py)"""
+    redshift_error: float | None = None
+    """Precision of the redshift category"""
+    distance: float
+    """Distance in arcsec"""
+    info: str | dict[str, dict[str, str | int]] | None = None
+    """Type info if included in the matching catalogs, catalog name -> type key -> type value"""
+
+
+class MeanPosition(BaseModel):
+    """
+    Mean position of the transient calculated as the
+    weighted sum of the diaSource positions contributing to the diaSource.
+    """
+
+    mean_ra: float
+    """The mean RA (deg)"""
+    mean_dec: float
+    """The mean Dec (deg)"""
+    circularized_error: float
+    """Geometric mean of sqrt(raErr^2 + decErr^2) in arcsec"""
+    std: float
+    """Standard deviation of the datapoint distance to the mean position in arcsec"""
+
+
+class TemplateFlux(BaseModel):
+    """Median and 90th percentile of the templateFlux of all diaSources
+    contributing to the diaObject in a single band."""
+
+    band: str
+    """Band name"""
+    median: float
+    """Median template flux"""
+    perc5: float
+    """5th percentile template flux"""
+    perc95: float
+    """95th percentile template flux"""
+
+
+class TemplateFluxes(BaseModel):
+    """Median of the templateFlux of all diaSources contributing to the diaObject."""
+
+    u: TemplateFlux | None
+    g: TemplateFlux | None
+    r: TemplateFlux | None
+    i: TemplateFlux | None
+    z: TemplateFlux | None
+    y: TemplateFlux | None
+
+
+class NuclearTransientReport(BaseModel):
+    """
+    Data model for LSST alert reports from Ampel.
+    """
+
+    version: str
+    """Version of the TDEmocracy nuclear filter"""
+    model_version: str
+    """Version of the TDEmocracy nuclear filter data model"""
+    object: Object
+    state: int
+    """unique identifier for underlying collection of data points in AMPEL"""
+    photometry: Sequence[PhotometricPoint]
+    host: Host | None
+    mean_position: MeanPosition
+    template_fluxes: TemplateFluxes
+
+    model_config = ConfigDict(extra="forbid")

tdemocracy-0.0.3/tdemocracy/settings.py

@@ -0,0 +1,17 @@
+from typing import Any
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Settings for tdemocracy. Per default, the values are being read from the environment as `TDEMOCRACY_<key>`, or the `tdemocracy.env` file."""
+
+    username: str
+    """Username for the Hopskotch stream"""
+    password: str
+    """Password for the Hopskotch stream"""
+    topic: str = "Ampel-TDEmocracy.nucelar-stream-dev"
+    """Hopskotch topic"""
+    group_id: Any | None = None
+    """Group ID when listening to the kafka stream. If None (default) a new value will be assigned with each call (good for testing). Set to a persistent <username>-<key> value to keep track of the stream position between calls (good for production)."""
+    model_config = SettingsConfigDict(env_prefix="TDEMOCRACY_", env_file="tdemocracy.env")