astro-otter 0.6.0__py3-none-any.whl

otter/plotter/otter_plotter.py

@@ -0,0 +1,76 @@
+"""
+OtterPlotter Class which handles the backend of the plotting.
+
+Currently supported backends are:
+- matplotlib
+- plotly
+"""
+
+from __future__ import annotations
+import importlib
+import numpy as np
+
+
+class OtterPlotter:
+    """
+    Handles the backend for the "plotter" module
+
+    Args:
+        backend (string): a string of the module name to import and use
+                          as the backend. Currently supported are "matplotlib",
+                          "matplotlib.pyplot", "plotly", and "plotly.graph_objects"
+    """
+
+    def __init__(self, backend):
+        if backend == "matplotlib.pyplot":
+            self.backend = backend
+        elif backend == "plotly.graph_objects":
+            self.backend = backend
+        elif "plotly" in backend and "graph_objects" not in backend:
+            self.backend = "plotly.graph_objects"
+        elif "matplotlib" in backend and "pyplot" not in backend:
+            self.backend = "matplotlib.pyplot"
+        else:
+            raise ValueError("Not a valid backend string!")
+
+        self.plotter = importlib.import_module(self.backend)
+
+        if self.backend == "matplotlib.pyplot":
+            self.plot = self._plot_matplotlib
+        elif self.backend == "plotly.graph_objects":
+            self.plot = self._plot_plotly
+        else:
+            raise ValueError("Unknown plotting backend!")
+
+    def _plot_matplotlib(self, x, y, xerr=None, yerr=None, ax=None, **kwargs):
+        """
+        General plots using matplotlib, is called by _matplotlib_light_curve and
+        _matplotlib_sed
+        """
+
+        if ax is None:
+            _, ax = self.plotter.subplots()
+
+        if yerr is not None:
+            yerr = np.abs(np.array(yerr))
+        ax.errorbar(x, y, xerr=xerr, yerr=yerr, **kwargs)
+        return ax
+
+    def _plot_plotly(self, x, y, xerr=None, yerr=None, ax=None, *args, **kwargs):
+        """
+        General plotting method using plotly, is called by _plotly_light_curve and
+        _plotly_sed
+        """
+
+        if ax is None:
+            go = self.plotter.Figure()
+        else:
+            go = ax
+
+        if yerr is not None:
+            yerr = np.abs(np.array(yerr))
+        fig = go.add_scatter(
+            x=x, y=y, error_x=dict(array=xerr), error_y=dict(array=yerr), **kwargs
+        )
+
+        return fig

otter/plotter/plotter.py

@@ -0,0 +1,266 @@
+"""
+Some utilities to create common plots for transients that use the OtterPlotter
+"""
+
+from __future__ import annotations
+from warnings import warn
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+
+from .otter_plotter import OtterPlotter
+from ..exceptions import FailedQueryError
+from ..io.otter import Transient, Otter
+
+
+def query_quick_view(
+    db: Otter,
+    ptype: str = "both",
+    sed_dim: str = "freq",
+    dt_over_t: float = 0,
+    plotting_kwargs: dict = {},
+    phot_cleaning_kwargs: dict = {},
+    result_length_tol=10,
+    **kwargs,
+) -> list[plt.Figure]:
+    """
+    Queries otter and then plots all of the transients. It will either query the Otter
+    object provided in db or construct an Otter object from otter_path.
+
+    Args:
+        db (otter.Otter) : The otter object to query
+        ptype (str) : The plot type to generate. Valid options are
+                      - both -> Plot both light curve and sed (default)
+                      - sed -> Plot just the sed
+                      - lc -> Plot just the light curve
+        sed_dim (str) : The x dimension to plot in the SED. Options are "freq" or
+                        "wave". Default is "freq".
+        time_tol (float) : The tolerance to split the days by. Default is 1 day. must be
+                           in units of days.
+        plotting_kwargs (dict) : dictionary of key word arguments to pass to
+                                 otter.plotter.plot_light_curve or
+                                 otter.plotter.plot_sed.
+        phot_cleaning_kwargs (dict) : Keyword arguments passed to
+                                      otter.Transient.clean_photometry
+        result_length_tol (int) : If the query result is longer than this it will throw
+                                  an erorr to prevent 100s of plots from spitting out
+                                  (and likely crashing your computer). Default is 10 but
+                                  can be adjusted.
+        **kwargs : Arguments to pass to otter.Otter.query
+
+    Returns:
+        A list of matplotlib pyplot Figure objects that we plotted
+
+    """
+    res = db.query(**kwargs)
+
+    if len(res) > result_length_tol:
+        raise RuntimeError(
+            f"This query returned {len(res)} results which is greater than the given "
+            + f"tolerance of {result_length_tol}! Either increase the result_length_tol"
+            + " keyword or pass in a stricter query!"
+        )
+
+    figs = []
+    for t in res:
+        try:
+            fig = quick_view(
+                t, ptype, sed_dim, dt_over_t, plotting_kwargs, **phot_cleaning_kwargs
+            )
+        except (KeyError, FailedQueryError):
+            warn(f"No photometry associated with {t.default_name}, skipping!")
+            continue
+
+        fig.suptitle(t.default_name)
+        figs.append(fig)
+
+    return figs
+
+
+def quick_view(
+    t: Transient,
+    ptype: str = "both",
+    sed_dim: str = "freq",
+    dt_over_t: float = 0,
+    plotting_kwargs: dict = {},
+    **kwargs,
+) -> plt.Figure:
+    """
+    Generate a quick view (not necessarily publication ready) of the transients light
+    curve, SED, or both. Default is to do both.
+
+    Args:
+        t (otter.Transient) : An otter Transient object to grab photometry from
+        ptype (str) : The plot type to generate. Valid options are
+                      - both -> Plot both light curve and sed (default)
+                      - sed -> Plot just the sed
+                      - lc -> Plot just the light curve
+        sed_dim (str) : The x dimension to plot in the SED. Options are "freq" or
+                        "wave". Default is "freq".
+        dt_over_t (float) : The tolerance to split the days by. Default is 1 day. must
+                           be unitless.
+        plotting_kwargs (dict) : dictionary of key word arguments to pass to
+                                 otter.plotter.plot_light_curve or
+                                 otter.plotter.plot_sed.
+        **kwargs : Any other arguments to pass to otter.Transient.clean_photometry
+
+    Returns:
+        The matplotlib figure used for plotting.
+    """
+    backend = plotting_kwargs.get("backend", "matplotlib.pyplot")
+    if backend not in {"matplotlib.pyplot", "matplotlib"}:
+        raise ValueError(
+            "Only matplotlib.pyplot backend is available for quick_view!"
+            + " To use plotly, use the plotting functionality individually!"
+        )
+
+    allphot = t.clean_photometry(**kwargs)
+    allphot = allphot.sort_values("converted_date")
+    allphot["time_tol"] = dt_over_t * allphot["converted_date"]
+    allphot["time_diff"] = allphot["converted_date"].diff().fillna(-np.inf)
+    allphot["time_grp"] = (allphot.time_diff > allphot.time_tol).cumsum()
+
+    plt_lc = (ptype == "both") or (ptype == "lc")
+    plt_sed = (ptype == "both") or (ptype == "sed")
+
+    if ptype == "both":
+        fig, (lc_ax, sed_ax) = plt.subplots(1, 2)
+    elif ptype == "sed":
+        fig, sed_ax = plt.subplots()
+    elif ptype == "lc":
+        fig, lc_ax = plt.subplots()
+
+    if np.all(pd.isna(allphot.converted_flux_err)):
+        flux_err = None
+    else:
+        flux_err = allphot.converted_flux_err
+
+    if plt_lc:
+        for filt, phot in allphot.groupby("filter_name"):
+            plot_light_curve(
+                date=phot.converted_date,
+                flux=phot.converted_flux,
+                flux_err=flux_err[allphot.filter_name == filt],
+                xlabel=f"Date [{phot.converted_date_unit.values[0]}]",
+                ylabel=f"Flux [{phot.converted_flux_unit.values[0]}]",
+                ax=lc_ax,
+                label=filt,
+                **plotting_kwargs,
+            )
+
+    if plt_sed:
+        for grp_name, phot in allphot.groupby("time_grp"):
+            if sed_dim == "wave":
+                wave_or_freq = phot.converted_wave
+                xlab = f"Wavelength [{phot.converted_wave_unit.values[0]}]"
+            elif sed_dim == "freq":
+                wave_or_freq = phot.converted_freq
+                xlab = f"Frequency [{phot.converted_freq_unit.values[0]}]"
+            else:
+                raise ValueError("sed_dim value is not recognized!")
+
+            plot_sed(
+                wave_or_freq=wave_or_freq,
+                flux=phot.converted_flux,
+                flux_err=flux_err[allphot.time_grp == grp_name],
+                ax=sed_ax,
+                xlabel=xlab,
+                ylabel=f"Flux [{phot.converted_flux_unit.values[0]}]",
+                label=phot.converted_date.mean(),
+                **plotting_kwargs,
+            )
+
+        sed_ax.set_xscale("log")
+
+    return fig
+
+
+def plot_light_curve(
+    date: float,
+    flux: float,
+    date_err: float = None,
+    flux_err: float = None,
+    fig=None,
+    ax=None,
+    backend: str = "matplotlib",
+    xlabel: str = "Date",
+    ylabel: str = "Flux",
+    **kwargs,
+):
+    """
+    Plot the light curve for the input data
+
+    Args:
+        date (float): MJD dates
+        flux (float): Flux
+        date_err (float): optional error on the MJD dates
+        flux_err (float): optional error on the flux
+        fig (float): matplotlib fig object, optional. Will be created if not provided.
+        ax (float): matplitlib axis object, optional. Will be created if not provided.
+        backend (str): backend for plotting. options: "matplotlib" (default) or "plotly"
+        xlabel (str): x-axis label
+        ylabel (str): y-axis label
+        **kwargs: keyword arguments to pass to either plotly.graph_objects.add_scatter
+                  or matplotlib.pyplot.errorbar
+
+    Returns:
+       Either a matplotlib axis or plotly figure
+    """
+
+    plt = OtterPlotter(backend)
+    fig = plt.plot(date, flux, date_err, flux_err, ax=ax, **kwargs)
+
+    if backend == "matplotlib":
+        fig.set_ylabel(ylabel)
+        fig.set_xlabel(xlabel)
+
+    elif backend == "plotly":
+        fig.update_layout(xaxis_title=xlabel, yaxis_title=ylabel)
+
+    return fig
+
+
+def plot_sed(
+    wave_or_freq: float,
+    flux: float,
+    wave_or_freq_err: float = None,
+    flux_err: float = None,
+    fig=None,
+    ax=None,
+    backend: str = "matplotlib",
+    xlabel: str = "Frequency or Wavelength",
+    ylabel: str = "Flux",
+    **kwargs,
+):
+    """
+    Plot the SED for the input data
+
+    Args:
+        wave_or_freq (float): wave or frequency array
+        flux (float): Flux
+        wave_or_freq_err (float): optional error on the MJD dates
+        flux_err (float): optional error on the flux
+        fig (float): matplotlib fig object, optional. Will be created if not provided.
+        ax (float): matplitlib axis object, optional. Will be created if not provided.
+        backend (str): backend for plotting. Options: "matplotlib" (default) or "plotly"
+        xlabel (str): x-axis label
+        ylabel (str): y-axis label
+        **kwargs: keyword arguments to pass to either plotly.graph_objects.add_scatter
+                  or matplotlib.pyplot.errorbar
+
+    Returns:
+       Either a matplotlib axis or plotly figure
+    """
+
+    plt = OtterPlotter(backend)
+    fig = plt.plot(wave_or_freq, flux, wave_or_freq_err, flux_err, ax=ax, **kwargs)
+
+    if backend == "matplotlib":
+        fig.set_ylabel(ylabel)
+        fig.set_xlabel(xlabel)
+
+    elif backend == "plotly":
+        fig.update_layout(xaxis_title=xlabel, yaxis_title=ylabel)
+
+    return fig

otter/schema.py

@@ -0,0 +1,312 @@
+"""
+Pydantic Schema Model of our JSON schema
+"""
+
+from pydantic import BaseModel, model_validator, field_validator
+from typing import Optional, Union, List
+
+
+class VersionSchema(BaseModel):
+    value: Union[str, int] = None
+    comment: str = None
+
+
+class _AliasSchema(BaseModel):
+    value: str
+    reference: Union[str, List[str]]
+
+
+class _XrayModelSchema(BaseModel):
+    # the following two lines are needed to prevent annoying warnings
+    model_config: dict = {}
+    model_config["protected_namespaces"] = ()
+
+    # required keywords
+    model_name: str
+    param_names: List[str]
+    param_values: List[Union[float, int, str]]
+    param_units: List[Union[str, None]]
+    min_energy: Union[float, int, str]
+    max_energy: Union[float, int, str]
+    energy_units: str
+
+    # optional keywords
+    param_value_err_upper: Optional[List[Union[float, int, str]]] = None
+    param_value_err_lower: Optional[List[Union[float, int, str]]] = None
+    param_upperlimit: Optional[List[Union[float, int, str]]] = None
+    param_descriptions: Optional[List[str]] = None
+    model_reference: Optional[Union[str, List[str]]] = None
+
+
+class _ErrDetailSchema(BaseModel):
+    # all optional keywords!
+    upper: Optional[List[Union[float, int, str]]] = None
+    lower: Optional[List[Union[float, int, str]]] = None
+    systematic: Optional[List[Union[float, int, str]]] = None
+    statistical: Optional[List[Union[float, int, str]]] = None
+    iss: Optional[List[Union[float, int, str]]] = None
+
+
+class NameSchema(BaseModel):
+    default_name: str
+    alias: list[_AliasSchema]
+
+
+class CoordinateSchema(BaseModel):
+    reference: Union[List[str], str]
+    ra: Union[str, float] = None
+    dec: Union[str, float] = None
+    l: Union[str, float] = None  # noqa: E741
+    b: Union[str, float] = None
+    lon: Union[str, float] = None
+    lat: Union[str, float] = None
+    ra_units: str = None
+    dec_units: str = None
+    l_units: str = None
+    b_units: str = None
+    lon_units: str = None
+    lat_units: str = None
+    ra_error: Union[str, float] = None
+    dec_error: Union[str, float] = None
+    l_error: Union[str, float] = None
+    b_error: Union[str, float] = None
+    lon_error: Union[str, float] = None
+    lat_error: Union[str, float] = None
+    epoch: str = None
+    frame: str = "J2000"
+    coord_type: str = None
+    computed: bool = False
+    default: bool = False
+
+    @model_validator(mode="after")
+    def _has_coordinate(self):
+        uses_ra_dec = self.ra is not None and self.dec is not None
+        uses_galactic = self.l is not None and self.b is not None
+        uses_lon_lat = self.lon is not None and self.lat is not None
+
+        if uses_ra_dec:
+            if self.ra_units is None:
+                raise ValueError("ra_units must be provided for RA!")
+            if self.dec_units is None:
+                raise ValueError("dec_units must be provided for Dec!")
+
+        elif uses_galactic:
+            if self.l_units is None:
+                raise ValueError("l_units must be provided for RA!")
+            if self.b_units is None:
+                raise ValueError("b_units must be provided for Dec!")
+
+        elif uses_lon_lat:
+            if self.lon_units is None:
+                raise ValueError("lon_units must be provided for RA!")
+            if self.lat_units is None:
+                raise ValueError("lat_units must be provided for Dec!")
+
+        else:
+            raise ValueError("Must have RA/Dec, l/b, and/or lon/lat!")
+
+        return self
+
+
+class DistanceSchema(BaseModel):
+    value: Union[str, float, int]
+    unit: str = None
+    reference: Union[str, List[str]]
+    distance_type: str
+    error: Union[str, float, int] = None
+    cosmology: str = None
+    computed: bool = False
+    uuid: str = None
+    default: bool = False
+
+    @model_validator(mode="after")
+    def _has_units(self):
+        if self.distance_type != "redshift" and self.unit is None:
+            raise ValueError("Need units if the distance_type is not redshift!")
+
+        return self
+
+
+class ClassificationSchema(BaseModel):
+    object_class: str
+    confidence: float
+    reference: Union[str, List[str]]
+    default: bool = False
+    class_type: str = None
+
+
+class ClassificationDictSchema(BaseModel):
+    spec_classed: Optional[int] = None
+    unambiguous: Optional[bool] = None
+    value: list[ClassificationSchema]
+
+
+class ReferenceSchema(BaseModel):
+    name: str
+    human_readable_name: str
+
+
+class DateSchema(BaseModel):
+    value: Union[str, int, float]
+    date_format: str
+    date_type: str
+    reference: Union[str, List[str]]
+    computed: bool = None
+
+
+class PhotometrySchema(BaseModel):
+    reference: Union[List[str], str]
+    raw: list[Union[float, int]]
+    raw_err: Optional[List[float]] = []
+    raw_units: Union[str, List[str]]
+    value: Optional[list[Union[float, int]]] = None
+    value_err: Optional[list[Union[float, int]]] = None
+    value_units: Optional[Union[str, List[str]]] = None
+    epoch_zeropoint: Optional[Union[float, str, int]] = None
+    epoch_redshift: Optional[Union[float, int]] = None
+    filter: Optional[Union[str, List[str]]] = None
+    filter_key: Union[str, List[str]]
+    obs_type: Union[str, List[str]]
+    telescope_area: Optional[Union[float, List[float]]] = None
+    date: Union[str, float, List[Union[str, float]]]
+    date_format: Union[str, List[str]]
+    date_err: Optional[Union[str, float, List[Union[str, float]]]] = None
+    date_min: Optional[Union[str, float, List[Union[str, float]]]] = None
+    date_max: Optional[Union[str, float, List[Union[str, float]]]] = None
+    ignore: Optional[Union[bool, List[bool]]] = None
+    upperlimit: Optional[Union[bool, List[bool]]] = None
+    sigma: Optional[Union[str, float, List[Union[str, float]]]] = None
+    sky: Optional[Union[str, float, List[Union[str, float]]]] = None
+    telescope: Optional[Union[str, List[str]]] = None
+    instrument: Optional[Union[str, List[str]]] = None
+    phot_type: Optional[Union[str, List[str]]] = None
+    exptime: Optional[Union[str, int, float, List[Union[str, int, float]]]] = None
+    aperture: Optional[Union[str, int, float, List[Union[str, int, float]]]] = None
+    observer: Optional[Union[str, List[str]]] = None
+    reducer: Optional[Union[str, List[str]]] = None
+    pipeline: Optional[Union[str, List[str]]] = None
+    corr_k: Optional[Union[bool, str, List[Union[bool, str]]]] = None
+    corr_s: Optional[Union[bool, str, List[Union[bool, str]]]] = None
+    corr_av: Optional[Union[bool, str, List[Union[bool, str]]]] = None
+    corr_host: Optional[Union[bool, str, List[Union[bool, str]]]] = None
+    corr_hostav: Optional[Union[bool, str, List[Union[bool, str]]]] = None
+    val_k: Optional[Union[float, int, str, List[Union[float, int, str]]]] = None
+    val_s: Optional[Union[float, int, str, List[Union[float, int, str]]]] = None
+    val_av: Optional[Union[float, int, str, List[Union[float, int, str]]]] = None
+    val_host: Optional[Union[float, int, str, List[Union[float, int, str]]]] = None
+    val_hostav: Optional[Union[float, int, str, List[Union[float, int, str]]]] = None
+    xray_model: Optional[Union[List[_XrayModelSchema], List[None]]] = None
+    raw_err_detail: Optional[_ErrDetailSchema] = None
+    value_err_detail: Optional[_ErrDetailSchema] = None
+
+    @field_validator(
+        "raw_units",
+        "raw_err",
+        "filter_key",
+        "obs_type",
+        "date_format",
+        "upperlimit",
+        "date",
+        "telescope",
+    )
+    @classmethod
+    def ensure_list(cls, v):
+        if not isinstance(v, list):
+            return [v]
+        return v
+
+    @model_validator(mode="after")
+    def _ensure_min_and_max_date(self):
+        """
+        This will make sure that if date_min is provided so is date_max
+        """
+        if (self.date_min is not None and self.date_max is None) or (
+            self.date_min is None and self.date_max is not None
+        ):
+            raise ValueError(
+                "If you provide date_min or date_max you must provide the other!"
+            )
+
+    @model_validator(mode="after")
+    def _ensure_xray_model(self):
+        """
+        This will eventually ensure the xray_model key is used if obs_type="xray"
+
+        It will be commented out until we get the data setup correctly
+        """
+        # if self.obs_type == "xray" and self.xray_model is None:
+        #     raise ValueError(
+        #         "Need an xray_model for this xray data!"
+        #     )
+
+        return self
+
+
+class FilterSchema(BaseModel):
+    filter_key: str
+    filter_name: str
+    wave_eff: Union[str, float, int] = None
+    wave_min: Union[str, float, int] = None
+    wave_max: Union[str, float, int] = None
+    freq_eff: Union[str, float, int] = None
+    freq_min: Union[str, float, int] = None
+    freq_max: Union[str, float, int] = None
+    zp: Union[str, float, int] = None
+    wave_units: Union[str, float, int] = None
+    freq_units: Union[str, float, int] = None
+    zp_units: Union[str, float, int] = None
+    zp_system: Union[str, float, int] = None
+
+
+class HostSchema(BaseModel):
+    reference: Union[str, List[str]]
+    host_ra: Optional[Union[str, float]] = None
+    host_dec: Optional[Union[str, float]] = None
+    host_ra_units: Optional[str] = None
+    host_dec_units: Optional[str] = None
+    host_z: Optional[Union[str, int, float]] = None
+    host_type: Optional[str] = None
+    host_name: Optional[str] = None
+
+    @model_validator(mode="after")
+    def _has_coordinate_or_name(self):
+        has_coordinate = self.host_ra is not None and self.host_dec is not None
+        has_name = self.host_name is not None
+
+        # if it has the RA/Dec keys, make sure it also has ra_unit, dec_unit keys
+        if has_coordinate:
+            if self.host_ra_units is None:
+                raise ValueError("Need RA unit if coordinates are provided!")
+            if self.host_dec_units is None:
+                raise ValueError("Need Dec unit if coordinates are provided!")
+
+        # we need either the coordinate or name to identify this object
+        # Both are okay too (more info is always better)
+        if not has_coordinate and not has_name:
+            raise ValueError("Need to provide a Host name and/or host coordinates!")
+
+        # Make sure that if one of RA/Dec is given then both are given
+        if (self.host_ra is None and self.host_dec is not None) or (
+            self.host_ra is not None and self.host_dec is None
+        ):
+            raise ValueError("Please provide RA AND Dec, not just one or the other!")
+
+        return self
+
+
+class OtterSchema(BaseModel):
+    schema_version: Optional[VersionSchema] = None
+    name: NameSchema
+    coordinate: list[CoordinateSchema]
+    distance: Optional[list[DistanceSchema]] = None
+    classification: Optional[ClassificationDictSchema] = None
+    reference_alias: list[ReferenceSchema]
+    date_reference: Optional[list[DateSchema]] = None
+    photometry: Optional[list[PhotometrySchema]] = None
+    filter_alias: Optional[list[FilterSchema]] = None
+    host: Optional[list[HostSchema]] = None
+
+    @model_validator(mode="after")
+    def _verify_filter_alias(self):
+        if self.photometry is not None and self.filter_alias is None:
+            raise ValueError("filter_alias is needed if photometry is given!")