astro-otter 0.0.1__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

@@ -2,6 +2,7 @@
 This is the primary class for user interaction with the catalog
 """
 
+from __future__ import annotations
 import os
 import json
 import glob
@@ -28,14 +29,11 @@ class Otter(object):
     This is the primary class for users to access the otter backend database
 
     Args:
-        username [str]: Your connection username to the database, default is the user
-                        login which only has read permission.
-        password [str]: Your password corresponding to your username.
-        db [str]: The database name to connect to. This is default to 'otter' which is
-                  the only database so far.
-        collection [str]: The collection to read data from. Right now the only
-                          collection is 'tdes'.
-        debug [bool]: debug mode, set to true to limit reading from database.
+        datadir (str): Path to the data directory with the otter data. If not provided
+                       will default to a ".otter" directory in the CWD where you call
+                       this class from.
+        debug (bool): If we should just debug and not do anything serious.
+
     """
 
     def __init__(self, datadir: str = None, debug: bool = False) -> None:
@@ -87,9 +85,9 @@ class Otter(object):
         Performs a cone search of the catalog over the given coords and radius.
 
         Args:
-            coords [SkyCoord]: An astropy SkyCoord object with coordinates to match to
-            radius [float]: The radius of the cone in arcseconds, default is 0.05"
-            raw [bool]: If False (the default) return an astropy table of the metadata
+            coords (SkyCoord): An astropy SkyCoord object with coordinates to match to
+            radius (float): The radius of the cone in arcseconds, default is 0.05"
+            raw (bool): If False (the default) return an astropy table of the metadata
                         for matching objects. Otherwise, return the raw json dicts
 
         Return:
@@ -117,35 +115,40 @@ class Otter(object):
         unit conversion for you!
 
         Args:
-            flux_units [astropy.unit.Unit]: Either a valid string to convert
+            flux_units (astropy.unit.Unit): Either a valid string to convert
                                             or an astropy.unit.Unit
-            date_units [astropy.unit.Unit]: Either a valid string to convert to a date
+            date_units (astropy.unit.Unit): Either a valid string to convert to a date
                                             or an astropy.unit.Unit
-            return_type [str]: Either 'astropy' or 'pandas'. If astropy, returns an
+            return_type (str): Either 'astropy' or 'pandas'. If astropy, returns an
                                astropy Table. If pandas, returns a pandas DataFrame.
                                Default is 'astropy'.
-            obs_type [str]: Either 'radio', 'uvoir', or 'xray'. Will only return that
+            obs_type (str): Either 'radio', 'uvoir', or 'xray'. Will only return that
                             type of photometry if not None. Default is None and will
                             return any type of photometry.
-            keep_raw [bool]: If True, keep the raw flux/date/freq/wave associated with
+            keep_raw (bool): If True, keep the raw flux/date/freq/wave associated with
                              the dataset. Else, just keep the converted data. Default
                              is False.
-            **kwargs : Arguments to pass to Otter.query(). Can be:
-                       names [list[str]]: A list of names to get the metadata for
-                       coords [SkyCoord]: An astropy SkyCoord object with coordinates
+            **kwargs : Arguments to pass to Otter.query(). Can be::
+
+                       names (list[str]): A list of names to get the metadata for
+                       coords (SkyCoord): An astropy SkyCoord object with coordinates
                                           to match to
-                       radius [float]: The radius in arcseconds for a cone search,
+                       radius (float): The radius in arcseconds for a cone search,
                                        default is 0.05"
-                       minZ [float]: The minimum redshift to search for
-                       maxZ [float]: The maximum redshift to search for
-                       refs [list[str]]: A list of ads bibcodes to match to. Will only
+                       minZ (float): The minimum redshift to search for
+                       maxZ (float): The maximum redshift to search for
+                       refs (list[str]): A list of ads bibcodes to match to. Will only
                                          return metadata for transients that have this
                                          as a reference.
-                       hasSpec [bool]: if True, only return events that have spectra.
+                       hasSpec (bool): if True, only return events that have spectra.
 
         Return:
-           The photometry for the requested transients that match the arguments.
-           Will be an astropy Table sorted by transient default name.
+            The photometry for the requested transients that match the arguments.
+            Will be an astropy Table sorted by transient default name.
+
+        Raises:
+            FailedQueryError: When the query returns no results
+            IOError: if one of your inputs is incorrect
         """
         queryres = self.query(hasphot=True, **kwargs)
 
@@ -153,16 +156,25 @@ class Otter(object):
         for transient in queryres:
             # clean the photometry
             default_name = transient["name/default_name"]
-            phot = transient.clean_photometry(
-                flux_unit=flux_unit,
-                date_unit=date_unit,
-                wave_unit=wave_unit,
-                freq_unit=freq_unit,
-                obs_type=obs_type,
-            )
-            phot["name"] = [default_name] * len(phot)
 
-            dicts.append(phot)
+            try:
+                phot = transient.clean_photometry(
+                    flux_unit=flux_unit,
+                    date_unit=date_unit,
+                    wave_unit=wave_unit,
+                    freq_unit=freq_unit,
+                    obs_type=obs_type,
+                )
+
+                phot["name"] = [default_name] * len(phot)
+
+                dicts.append(phot)
+
+            except FailedQueryError:
+                # This is fine, it just means that there is no data associated
+                # with this one transient. We'll check and make sure there is data
+                # associated with at least one of the transients later!
+                pass
 
         if len(dicts) == 0:
             raise FailedQueryError()
@@ -180,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"]]
@@ -203,7 +220,7 @@ class Otter(object):
         Loads an otter JSON file
 
         Args:
-            filename [str]: The path to the file to load
+            filename (str): The path to the OTTER JSON file to load
         """
 
         # read in files from summary
@@ -234,15 +251,15 @@ class Otter(object):
         same units.
 
         Args:
-            names [list[str]]: A list of names to get the metadata for
-            coords [SkyCoord]: An astropy SkyCoord object with coordinates to match to
-            radius [float]: The radius in arcseconds for a cone search, default is 0.05"
-            minz [float]: The minimum redshift to search for
-            maxz [float]: The maximum redshift to search for
-            refs [list[str]]: A list of ads bibcodes to match to. Will only return
+            names (list[str]): A list of names to get the metadata for
+            coords (SkyCoord): An astropy SkyCoord object with coordinates to match to
+            radius (float): The radius in arcseconds for a cone search, default is 0.05"
+            minz (float): The minimum redshift to search for
+            maxz (float): The maximum redshift to search for
+            refs (list[str]): A list of ads bibcodes to match to. Will only return
                               metadata for transients that have this as a reference.
-            hasphot [bool]: if True, only returns transients which have photometry.
-            hasspec [bool]: if True, only return transients that have spectra.
+            hasphot (bool): if True, only returns transients which have photometry.
+            hasspec (bool): if True, only return transients that have spectra.
 
         Return:
            Get all of the raw (unconverted!) data for objects that match the criteria.
@@ -273,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):
@@ -344,24 +360,29 @@ class Otter(object):
 
         return outdata
 
-    def save(self, schema: list[dict], testing=False, **kwargs) -> None:
+    def save(self, schema: list[dict], testing=False) -> None:
         """
         Upload all the data in the given list of schemas.
 
         Args:
-            schema [list[dict]]: A list of json dictionaries
+            schema (list[dict]): A list of json dictionaries
+            testing (bool): Should we just enter test mode? Default is False
+
+        Raises:
+            OtterLimitationError: If some objects in OTTER are within 5" we can't figure
+                                  out which ones to merge with which ones.
         """
 
         if not isinstance(schema, list):
             schema = [schema]
 
         for transient in schema:
-            print(transient["name/default_name"])
-
             # convert the json to a Transient
             if not isinstance(transient, Transient):
                 transient = Transient(transient)
 
+            print(transient["name/default_name"])
+
             coord = transient.get_skycoord()
             res = self.cone_search(coords=coord)
 
@@ -405,8 +426,6 @@ class Otter(object):
             outfilepath = os.path.join(self.DATADIR, todel[0] + ".json")
             if test_mode:
                 print("Renaming the following file for backups: ", outfilepath)
-            else:
-                os.rename(outfilepath, outfilepath + ".backup")
         else:
             if test_mode:
                 print("Don't need to mess with the files at all!")
@@ -429,13 +448,16 @@ class Otter(object):
             print(f"Would write to {outfilepath}")
             # print(out)
 
-    def generate_summary_table(self, save=False):
+    def generate_summary_table(self, save=False) -> pd.DataFrame:
         """
         Generate a summary table for the JSON files in self.DATADIR
 
         args:
-            save [bool]: if True, save the summary file to "summary.csv"
-                         in self.DATADIR. Default is False.
+            save (bool): if True, save the summary file to "summary.csv"
+                         in self.DATADIR. Default is False and is just returned.
+
+        returns:
+            pandas.DataFrame of the summary meta information of the transients
         """
         allfiles = glob.glob(os.path.join(self.DATADIR, "*.json"))
 
@@ -455,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