astro-otter 0.0.2__py3-none-any.whl → 0.1.0__py3-none-any.whl

otter/io/host.py

@@ -0,0 +1,106 @@
+"""
+Host object that stores information on the Transient Host and provides utility methods
+for pulling in data corresponding to that host
+"""
+
+from __future__ import annotations
+import numpy as np
+from astropy.coordinates import SkyCoord
+from astropy import units as u
+
+from .data_finder import DataFinder
+from ..exceptions import OtterLimitationError
+
+
+class Host(DataFinder):
+    def __init__(
+        self,
+        host_ra: str | float,
+        host_dec: str | float,
+        host_ra_units: str | u.Unit,
+        host_dec_units: str | u.Unit,
+        host_name: str = None,
+        host_redshift: float = None,
+        reference: list[str] = None,
+        transient_name: str = None,
+        **kwargs,
+    ) -> None:
+        """
+        Object to store host information and query public data sources of host galaxies
+
+        Subclass of the data scraper class to allow for these queries to happen
+
+        Args:
+            host_ra (str|float) : The RA of the host to be passed to an astropy SkyCoord
+            host_dec (str|float) : The declination of the host to be passed to an
+                                   astropy SkyCoord
+            host_ra_units (str|astropy.units.Unit) : units of the RA, to be passed to
+                                                     the unit keyword of SkyCoord
+            host_dec_units (str|astropy.units.Unit) : units of the declination, to be
+                                                      passed to the unit keyword of
+                                                      SkyCoord
+            host_name (str) : The name of the host galaxy
+            host_redshift (float) : The redshift of the host galaxy
+            reference (list[str]) : a list of bibcodes that found this to be the host
+            transient_name (str) : the name of the transient associated with this host
+            kwargs : Just here so we can pass **Transient['host'] into this constructor
+                     and any extraneous properties will be ignored.
+        """
+        self.coord = SkyCoord(host_ra, host_dec, unit=(host_ra_units, host_dec_units))
+        self.name = host_name
+        self.z = host_redshift
+        self.redshift = host_redshift  # just here for ease of use
+        self.bibcodes = reference
+        self.transient_name = transient_name
+
+    def pcc(self, transient_coord: SkyCoord, mag: float = None):
+        """
+        Compute the Probability of Chance Coincindence as described in
+        Bloom et al. (2002) "Offset Distribution of Gamma-Ray Bursts.
+
+        This computes the probability that this galaxy is by chance nearby to the
+        transient on the sky. Or, in simpler terms this essentially computes the
+        probability that we are wrong about this being the transient host. So, a
+        smaller probability is better!
+
+        Note: This probability was initially defined for GRB afterglows, which tend to
+        be redder transients (supernova too). So, be cautious when using this algorithm
+        for TDEs!
+
+        Args:
+            transient_coord (astropy.coordinates.SkyCoord) : The coordinates of the
+                                                             transient object.
+            mag (float) : An r-band magnitude to compute from. Default is None which
+                          will prompt us to check SDSS for one within 10".
+        Returns:
+            A float probability in the range [0,1]
+        """
+
+        # first get the separation r, in arcseconds
+        r = self.coord.separation(transient_coord).arcsec
+
+        # next get the host r magnitude
+        if mag is None:
+            res = self.query_vizier(radius=10 * u.arcsec)
+
+            if len(res) == 0:
+                raise OtterLimitationError(
+                    "No magnitude found in SDSS! Please provide a magnitude via the \
+                    `mag` keyword to make this calculation!"
+                )
+
+            sdss = [k for k in res.keys() if "sdss" in k]
+            use = max(sdss, key=lambda k: int(k.split("sdss")[-1]))
+            print(f"Using the r magnitude from the {use} table")
+            mag = res[use]["rmag"][0]
+
+        # then compute the probability
+        sigma_prefactor = 1 / (3600**2 * 0.334 * np.log(10))
+        sigma_pow = 0.334 * (mag - 22.963) + 4.320
+        sigma = sigma_prefactor * 10**sigma_pow
+
+        eta = np.pi * r**2 * sigma
+
+        prob = 1 - np.exp(-eta)
+
+        return prob

otter/io/otter.py

@@ -192,11 +192,16 @@ class Otter(object):
             "converted_date_unit",
             "converted_wave_unit",
             "converted_freq_unit",
+            "filter_key",
             "obs_type",
             "upperlimit",
             "reference",
+            "human_readable_refs",
         ]
 
+        if "upperlimit" not in fullphot:
+            fullphot["upperlimit"] = False
+
         if not keep_raw:
             if "telescope" in fullphot:
                 fullphot = fullphot[keys_to_keep + ["telescope"]]
@@ -285,7 +290,6 @@ class Otter(object):
 
         # then read and query the summary table
         summary = pd.read_csv(summary_table)
-
         # coordinate search first
         if coords is not None:
             if not isinstance(coords, SkyCoord):
@@ -473,10 +477,14 @@ class Otter(object):
                 }
 
                 if "date_reference" in t:
-                    row["discovery_date"] = t.get_discovery_date()
+                    date_types = {d["date_type"] for d in t["date_reference"]}
+                    if "discovery" in date_types:
+                        row["discovery_date"] = t.get_discovery_date()
 
                 if "distance" in t:
-                    row["z"] = t.get_redshift()
+                    dist_types = {d["distance_type"] for d in t["distance"]}
+                    if "redshift" in dist_types:
+                        row["z"] = t.get_redshift()
 
                 row["hasPhot"] = "photometry" in t
                 row["hasSpec"] = "spectra" in t

otter/io/transient.py

@@ -9,6 +9,7 @@ from copy import deepcopy
 import re
 from collections.abc import MutableMapping
 from typing_extensions import Self
+import logging
 
 import numpy as np
 import pandas as pd
@@ -17,9 +18,6 @@ import astropy.units as u
 from astropy.time import Time
 from astropy.coordinates import SkyCoord
 
-from synphot.units import VEGAMAG, convert_flux
-from synphot.spectrum import SourceSpectrum
-
 from ..exceptions import (
     FailedQueryError,
     IOError,
@@ -27,10 +25,12 @@ from ..exceptions import (
     TransientMergeError,
 )
 from ..util import XRAY_AREAS
+from .host import Host
 
 warnings.simplefilter("once", RuntimeWarning)
 warnings.simplefilter("once", UserWarning)
 np.seterr(divide="ignore")
+logger = logging.getLogger(__name__)
 
 
 class Transient(MutableMapping):
@@ -196,6 +196,19 @@ class Transient(MutableMapping):
                 + " You can set strict_merge=False to override the check"
             )
 
+        # create set of the allowed keywords
+        allowed_keywords = {
+            "name",
+            "date_reference",
+            "coordinate",
+            "distance",
+            "filter_alias",
+            "schema_version",
+            "photometry",
+            "classification",
+            "host",
+        }
+
         # create a blank dictionary since we don't want to overwrite this object
         out = {}
 
@@ -230,24 +243,8 @@ class Transient(MutableMapping):
                 continue
 
             # There are some special keys that we are expecting
-            if key == "name":
-                self._merge_names(other, out)
-            elif key == "coordinate":
-                self._merge_coords(other, out)
-            elif key == "date_reference":
-                self._merge_date(other, out)
-            elif key == "distance":
-                self._merge_distance(other, out)
-            elif key == "filter_alias":
-                self._merge_filter_alias(other, out)
-            elif key == "schema_version":
-                self._merge_schema_version(other, out)
-            elif key == "photometry":
-                self._merge_photometry(other, out)
-            elif key == "spectra":
-                self._merge_spectra(other, out)
-            elif key == "classification":
-                self._merge_class(other, out)
+            if key in allowed_keywords:
+                Transient._merge_arbitrary(key, self, other, out)
             else:
                 # this is an unexpected key!
                 if strict_merge:
@@ -341,7 +338,7 @@ class Transient(MutableMapping):
         else:
             f = "mjd"
 
-        return Time(date["value"], format=f)
+        return Time(str(date["value"]).strip(), format=f)
 
     def get_redshift(self) -> float:
         """
@@ -357,7 +354,73 @@ class Transient(MutableMapping):
         else:
             return default["value"]
 
-    def _get_default(self, key, filt=""):
+    def get_classification(self) -> tuple(str, float, list):
+        """
+        Get the default classification of this Transient.
+        This normally corresponds to the highest confidence classification that we have
+        stored for the transient.
+
+        Returns:
+            The default object class as a string, the confidence level in that class,
+            and a list of the bibcodes corresponding to that classification. Or, None
+            if there is no classification.
+        """
+        default = self._get_default("classification")
+        if default is None:
+            return default
+        return default.object_class, default.confidence, default.reference
+
+    def get_host(self, max_hosts=3, **kwargs) -> list[Host]:
+        """
+        Gets the default host information of this Transient. This returns an otter.Host
+        object. If no host is known in OTTER, it uses astro-ghost to find the best
+        match.
+
+        Args:
+            max_hosts [int] : The maximum number of hosts to return
+            **kwargs : keyword arguments to be passed to getGHOST
+
+        Returns:
+            A list of otter.Host objects. This is useful becuase the Host objects have
+            useful methods for querying public catalogs for data of the host.
+        """
+        # first try to get the host information from our local database
+        if "host" in self:
+            host = [
+                Host(transient_name=self.default_name, **dict(h)) for h in self["host"]
+            ]
+
+        # then try astro-ghost
+        else:
+            logger.warn(
+                "No host known, trying to find it with astro-ghost. \
+                See https://uiucsnastro-ghost.readthedocs.io/en/latest/index.html"
+            )
+
+            # this import has to be here otherwise the code breaks
+            from astro_ghost.ghostHelperFunctions import getTransientHosts, getGHOST
+
+            getGHOST(real=False, verbose=1)
+            res = getTransientHosts(
+                [self.default_name], [self.get_skycoord()], verbose=False
+            )
+
+            host = [
+                Host(
+                    host_ra=row["raStack"],
+                    host_dec=row["decStack"],
+                    host_ra_units="deg",
+                    host_dec_units="deg",
+                    host_name=row["objName"],
+                    transient_name=self.default_name,
+                    reference=["astro-ghost"],
+                )
+                for i, row in res.iterrows()
+            ]
+
+        return host
+
+    def _get_default(self, key, filt=None):
         """
         Get the default of key
 
@@ -370,7 +433,8 @@ class Transient(MutableMapping):
             raise KeyError(f"This transient does not have {key} associated with it!")
 
         df = pd.DataFrame(self[key])
-        df = df[eval(filt)]  # apply the filters
+        if filt is not None:
+            df = df[eval(filt)]  # apply the filters
 
         if "default" in df:
             # first try to get the default
@@ -441,6 +505,10 @@ class Transient(MutableMapping):
         Returns:
             A pandas DataFrame of the cleaned up photometry in the requested units
         """
+        # these imports need to be here for some reason
+        # otherwise the code breaks
+        from synphot.units import VEGAMAG, convert_flux
+        from synphot.spectrum import SourceSpectrum
 
         # check inputs
         if by not in {"value", "raw"}:
@@ -523,8 +591,9 @@ class Transient(MutableMapping):
                 )
 
             unit = unit[0]
+            isvegamag = "vega" in unit.lower()
             try:
-                if "vega" in unit.lower():
+                if isvegamag:
                     astropy_units = VEGAMAG
                 else:
                     astropy_units = u.Unit(unit)
@@ -555,25 +624,24 @@ class Transient(MutableMapping):
                 astropy_units
             )  # assume error and values have the same unit
 
-            # get the effective wavelength
+            # get and save the effective wavelength
             if "freq_eff" in data and not np.isnan(data["freq_eff"].iloc[0]):
-                freq_units = data["freq_units"]
-                if len(np.unique(freq_units)) > 1:
-                    raise OtterLimitationError(
-                        "Can not convert different units to the same unit!"
-                    )
-
-                freq_eff = np.array(data["freq_eff"]) * u.Unit(freq_units.iloc[0])
-                wave_eff = freq_eff.to(u.AA, equivalencies=u.spectral())
+                zz = zip(data["freq_eff"], data["freq_units"])
+                freq_eff = u.Quantity([vv * u.Unit(uu) for vv, uu in zz], freq_unit)
+                wave_eff = freq_eff.to(wave_unit, equivalencies=u.spectral())
 
             elif "wave_eff" in data and not np.isnan(data["wave_eff"].iloc[0]):
-                wave_units = data["wave_units"]
-                if len(np.unique(wave_units)) > 1:
-                    raise OtterLimitationError(
-                        "Can not convert different units to the same unit!"
-                    )
+                zz = zip(data["wave_eff"], data["wave_units"])
+                wave_eff = u.Quantity([vv * u.Unit(uu) for vv, uu in zz], wave_unit)
+                freq_eff = wave_eff.to(freq_unit, equivalencies=u.spectral())
+
+            else:
+                raise ValueError("No known frequency or wavelength, please fix!")
 
-                wave_eff = np.array(data["wave_eff"]) * u.Unit(wave_units.iloc[0])
+            data["converted_wave"] = wave_eff.value
+            data["converted_wave_unit"] = wave_unit
+            data["converted_freq"] = freq_eff.value
+            data["converted_freq_unit"] = freq_unit
 
             # convert using synphot
             # stuff has to be done slightly differently for xray than for the others
@@ -593,39 +661,48 @@ class Transient(MutableMapping):
 
                 # we also need to make this wave_min and wave_max
                 # instead of just the effective wavelength like for radio and uvoir
-                wave_eff = np.array(
-                    list(zip(data["wave_min"], data["wave_max"]))
-                ) * u.Unit(wave_units.iloc[0])
+                zz = zip(data["wave_min"], data["wave_max"], data["wave_units"])
+                wave_eff = u.Quantity(
+                    [np.array([m, M]) * u.Unit(uu) for m, M, uu in zz],
+                    u.Unit(wave_unit),
+                )
 
             else:
                 area = None
 
-            # we unfortunately have to loop over the points here because
-            # syncphot does not work with a 2D array of min max wavelengths
-            # for converting counts to other flux units. It also can't convert
-            # vega mags with a wavelength array because it then interprets that as the
-            # wavelengths corresponding to the SourceSpectrum.from_vega()
-            flux, flux_err = [], []
-            for wave, xray_point, xray_point_err in zip(wave_eff, q, q_err):
-                f_val = convert_flux(
-                    wave,
-                    xray_point,
-                    u.Unit(flux_unit),
-                    vegaspec=SourceSpectrum.from_vega(),
-                    area=area,
-                )
-                f_err = convert_flux(
-                    wave,
-                    xray_point_err,
-                    u.Unit(flux_unit),
-                    vegaspec=SourceSpectrum.from_vega(),
-                    area=area,
-                )
+            if obstype == "xray" or isvegamag:
+                # we unfortunately have to loop over the points here because
+                # syncphot does not work with a 2D array of min max wavelengths
+                # for converting counts to other flux units. It also can't convert
+                # vega mags with a wavelength array because it interprets that as the
+                # wavelengths corresponding to the SourceSpectrum.from_vega()
+
+                flux, flux_err = [], []
+                for wave, xray_point, xray_point_err in zip(wave_eff, q, q_err):
+                    f_val = convert_flux(
+                        wave,
+                        xray_point,
+                        u.Unit(flux_unit),
+                        vegaspec=SourceSpectrum.from_vega(),
+                        area=area,
+                    )
+                    f_err = convert_flux(
+                        wave,
+                        xray_point_err,
+                        u.Unit(flux_unit),
+                        vegaspec=SourceSpectrum.from_vega(),
+                        area=area,
+                    )
+
+                    # then we take the average of the minimum and maximum values
+                    # computed by syncphot
+                    flux.append(np.mean(f_val).value)
+                    flux_err.append(np.mean(f_err).value)
 
-                # then we take the average of the minimum and maximum values
-                # computed by syncphot
-                flux.append(np.mean(f_val).value)
-                flux_err.append(np.mean(f_err).value)
+            else:
+                # this will be faster and cover most cases
+                flux = convert_flux(wave_eff, q, u.Unit(flux_unit))
+                flux_err = convert_flux(wave_eff, q_err, u.Unit(flux_unit))
 
             flux = np.array(flux) * u.Unit(flux_unit)
             flux_err = np.array(flux_err) * u.Unit(flux_unit)
@@ -639,7 +716,7 @@ class Transient(MutableMapping):
         outdata = pd.concat(outdata)
 
         # copy over the flux units
-        outdata["converted_flux_unit"] = [flux_unit] * len(outdata)
+        outdata["converted_flux_unit"] = flux_unit
 
         # make sure all the datetimes are in the same format here too!!
         times = [
@@ -647,27 +724,7 @@ class Transient(MutableMapping):
             for d, f in zip(outdata.date, outdata.date_format.str.lower())
         ]
         outdata["converted_date"] = times
-        outdata["converted_date_unit"] = [date_unit] * len(outdata)
-
-        # same with frequencies and wavelengths
-        freqs = []
-        waves = []
-
-        for _, row in df.iterrows():
-            if "freq_eff" in row and not np.isnan(row["freq_eff"]):
-                val = row["freq_eff"] * u.Unit(row["freq_units"])
-            elif "wave_eff" in df and not np.isnan(row["wave_eff"]):
-                val = row["wave_eff"] * u.Unit(row["wave_units"])
-            else:
-                raise ValueError("No known frequency or wavelength, please fix!")
-
-            freqs.append(val.to(freq_unit, equivalencies=u.spectral()).value)
-            waves.append(val.to(wave_unit, equivalencies=u.spectral()).value)
-
-        outdata["converted_freq"] = freqs
-        outdata["converted_wave"] = waves
-        outdata["converted_wave_unit"] = [wave_unit] * len(outdata)
-        outdata["converted_freq_unit"] = [freq_unit] * len(outdata)
+        outdata["converted_date_unit"] = date_unit
 
         return outdata
 
@@ -756,16 +813,6 @@ class Transient(MutableMapping):
         bothlines = [{"value": k, "reference": t1map[k] + t2map[k]} for k in inboth]
         out[key]["alias"] = line2 + line1 + bothlines
 
-    def _merge_coords(t1, t2, out):  # noqa: N805
-        """
-        Merge the coordinates subdictionaries for t1 and t2 and put it in out
-
-        Use pandas to drop any duplicates
-        """
-        key = "coordinate"
-
-        Transient._merge_arbitrary(key, t1, t2, out)
-
     def _merge_filter_alias(t1, t2, out):  # noqa: N805
         """
         Combine the filter alias lists across the transient objects
@@ -797,8 +844,15 @@ class Transient(MutableMapping):
         key = "photometry"
 
         out[key] = deepcopy(t1[key])
-        refs = np.array([d["reference"] for d in out[key]])
+        refs = []  # np.array([d["reference"] for d in out[key]])
         # merge_dups = lambda val: np.sum(val) if np.any(val.isna()) else val.iloc[0]
+        for val in out[key]:
+            if isinstance(val, list):
+                refs += val
+            elif isinstance(val, np.ndarray):
+                refs += list(val)
+            else:
+                refs.append(val)
 
         for val in t2[key]:
             # first check if t2's reference is in out
@@ -823,12 +877,6 @@ class Transient(MutableMapping):
 
                 out[key][i1] = newdict  # replace the dictionary at i1 with the new dict
 
-    def _merge_spectra(t1, t2, out):  # noqa: N805
-        """
-        Combine spectra sources
-        """
-        pass
-
     def _merge_class(t1, t2, out):  # noqa: N805
         """
         Combine the classification attribute
@@ -864,22 +912,6 @@ class Transient(MutableMapping):
             else:
                 item["default"] = False
 
-    def _merge_date(t1, t2, out):  # noqa: N805
-        """
-        Combine epoch data across two transients and write it to "out"
-        """
-        key = "date_reference"
-
-        Transient._merge_arbitrary(key, t1, t2, out)
-
-    def _merge_distance(t1, t2, out):  # noqa: N805
-        """
-        Combine distance information for these two transients
-        """
-        key = "distance"
-
-        Transient._merge_arbitrary(key, t1, t2, out)
-
     @staticmethod
     def _merge_arbitrary(key, t1, t2, out):
         """
@@ -889,24 +921,36 @@ class Transient(MutableMapping):
         a NxM pandas dataframe!
         """
 
-        df1 = pd.DataFrame(t1[key])
-        df2 = pd.DataFrame(t2[key])
+        if key == "name":
+            t1._merge_names(t2, out)
+        elif key == "filter_alias":
+            t1._merge_filter_alias(t2, out)
+        elif key == "schema_version":
+            t1._merge_schema_version(t2, out)
+        elif key == "photometry":
+            t1._merge_photometry(t2, out)
+        elif key == "classification":
+            t1._merge_class(t2, out)
+        else:
+            # this is where we can standardize some of the merging
+            df1 = pd.DataFrame(t1[key])
+            df2 = pd.DataFrame(t2[key])
 
-        merged_with_dups = pd.concat([df1, df2]).reset_index(drop=True)
+            merged_with_dups = pd.concat([df1, df2]).reset_index(drop=True)
 
-        # have to get the indexes to drop using a string rep of the df
-        # this is cause we have lists in some cells
-        to_drop = merged_with_dups.astype(str).drop_duplicates().index
+            # have to get the indexes to drop using a string rep of the df
+            # this is cause we have lists in some cells
+            to_drop = merged_with_dups.astype(str).drop_duplicates().index
 
-        merged = merged_with_dups.iloc[to_drop].reset_index(drop=True)
+            merged = merged_with_dups.iloc[to_drop].reset_index(drop=True)
 
-        outdict = merged.to_dict(orient="records")
+            outdict = merged.to_dict(orient="records")
 
-        outdict_cleaned = Transient._remove_nans(
-            outdict
-        )  # clear out the nans from pandas conversion
+            outdict_cleaned = Transient._remove_nans(
+                outdict
+            )  # clear out the nans from pandas conversion
 
-        out[key] = outdict_cleaned
+            out[key] = outdict_cleaned
 
     @staticmethod
     def _remove_nans(d):

otter/util.py

@@ -567,3 +567,45 @@ subschema = {
 """
 A useful variable to describe all of the subschemas that are available and can be used
 """
+
+VIZIER_LARGE_CATALOGS = [
+    "2MASS-PSC",
+    "2MASX",
+    "AC2000.2",
+    "AKARI",
+    "ALLWISE",
+    "ASCC-2.5",
+    "B/DENIS",
+    "CMC14",
+    "Gaia-DR1",
+    "GALEX",
+    "GLIMPSE",
+    "GSC-ACT",
+    "GSC1.2",
+    "GSC2.2",
+    "GSC2.3",
+    "HIP",
+    "HIP2",
+    "IRAS",
+    "NOMAD1",
+    "NVSS",
+    "PanSTARRS-DR1",
+    "PGC",
+    "Planck-DR1",
+    "PPMX",
+    "PPMXL",
+    "SDSS-DR12",
+    "SDSS-DR7",
+    "SDSS-DR9",
+    "Tycho-2",
+    "UCAC2",
+    "UCAC3",
+    "UCAC4",
+    "UKIDSS",
+    "USNO-A2",
+    "USNO-B1",
+    "WISE",
+]
+"""
+ViZier catalog names that we query for host information in the Host class
+"""