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

otter/util.py

@@ -3,9 +3,14 @@ Some constants, mappings, and functions to be used across the software
 """
 
 from __future__ import annotations
+from itertools import chain
 import os
+from multiprocessing import Pool
 import ads
+from ads.exceptions import APIResponseError
+import json
 import astropy.units as u
+import numpy as np
 
 """
 Helper functions first that just don't belong anywhere else
@@ -24,9 +29,31 @@ def filter_to_obstype(band_name):
             f"No Effective Wavelength Known for {band_name}, please add it to constants"
         ) from exc
 
-    if wave_eff > 1 * u.mm:
+    return wave_to_obstype(wave_eff)
+
+
+def freq_to_obstype(freq_eff):
+    """
+    Converts a frequency value to either 'radio', 'uvoir', 'xray'
+
+    Args:
+        freq_eff (u.Quantity) : An astropy quantity in frequency space
+    """
+
+    wave_eff = freq_eff.to(u.nm, equivalencies=u.spectral())
+    return wave_to_obstype(wave_eff)
+
+
+def wave_to_obstype(wave_eff):
+    """
+    Converts a wavelength value to either 'radio', 'uvoir', 'xray'
+
+    Args:
+        wave_eff (u.Quantity) : An astropy quantity in wavelength space
+    """
+    if wave_eff > 0.1 * u.mm:
         return "radio"
-    elif wave_eff <= 1 * u.mm and wave_eff >= 10 * u.nm:
+    elif wave_eff <= 0.1 * u.mm and wave_eff >= 10 * u.nm:
         return "uvoir"
     else:
         return "xray"
@@ -42,31 +69,154 @@ def clean_schema(schema):
     return schema
 
 
-def bibcode_to_hrn(bibcode):
+def bibcode_to_hrn(bibcode, local_reference_map="reference_map_local.json"):
+    if isinstance(bibcode, str):
+        bibcode = [bibcode]
+
+    if os.path.exists(local_reference_map):
+        with open(local_reference_map, "r") as j:
+            local_map = json.load(j)
+    else:
+        local_map = {}
+
+    hrns = []
+    bibcodes = []
+    bibcodes_to_query = []
+    for b in bibcode:
+        if b in local_map:
+            hrns.append(local_map[b])
+            bibcodes.append(b)
+        else:
+            bibcodes_to_query.append(b)
+
+    if len(bibcodes_to_query) > 0:
+        queried_bibs, queried_hrns = _bibcode_to_hrn_with_query(bibcodes_to_query)
+        hrns += queried_hrns
+        bibcodes += queried_bibs
+
+    return bibcodes, hrns
+
+
+def _bibcode_to_hrn_with_query(bibcode):
     """
     Converts a bibcode to a human_readable_name (hrn) using ADSQuery
     """
+    if isinstance(bibcode, str):
+        bibcode = bibcode.strip()
+        query = f"bibcode:{bibcode}"
+        bibcodes = [bibcode]
+    else:
+        # make sure the bibcodes are lists instead of strings of lists
+        bibcode = [b.strip("[]").replace("'", "").split(", ") for b in bibcode]
+
+        bibcode = list(chain(*[v if isinstance(v, list) else [v] for v in bibcode]))
+
+        bibcodes_flat = np.array(bibcode).flatten()
+        bibcodes_cleaned = np.array([b.strip() for b in bibcodes_flat])
+
+        bibcodes = list(np.unique(bibcodes_cleaned))
+
+    protected_vals = ["private", "new", "current work"]
+    for val in protected_vals:
+        if val in bibcodes:
+            bibcodes.pop(bibcodes.index(val))
+
+    query = f"bibcode:{bibcodes[0]}"
+    if len(bibcodes) > 1:
+        for b in bibcodes[1:]:
+            query += f" OR {b}"
 
     try:
-        adsquery = list(ads.SearchQuery(bibcode=bibcode))[0]
+        qobj = ads.SearchQuery(q=query)
+        qobj.execute()  # do the query
+        adsquery = list(qobj)
     except IndexError:
         raise ValueError(f"Could not find {bibcode} on ADS!")
+    except APIResponseError as exc:
+        raise ValueError(
+            f"""Failed on query {query}! \n Potentially out of ADS
+            queries! Run curl command to check like\n
+            https://github.com/adsabs/adsabs-dev-api/blob/master/README.md"""
+        ) from exc
+
+    hrns = []
+    bibcodes_to_return = []
+    for res in adsquery:
+        authors = res.author
+        year = res.year
 
-    authors = adsquery.author
-    year = adsquery.year
+        if len(authors) == 0:
+            raise ValueError("This ADS bibcode does not exist!")
+        elif len(authors) == 1:
+            author = authors[0]
+        elif len(authors) == 2:
+            author = authors[0] + " & " + authors[1]
+        else:  # longer than 2
+            author = authors[0] + " et al."
 
-    if len(authors) == 0:
-        raise ValueError("This ADS bibcode does not exist!")
-    elif len(authors) == 1:
-        author = authors[0]
-    elif len(authors) == 2:
-        author = authors[0] + " & " + authors[1]
-    else:  # longer than 2
-        author = authors[0] + " et al."
+        # generate the human readable name
+        hrn = author + " (" + year + ")"
+        hrns.append(hrn)
+        bibcodes_to_return.append(res.bibcode)
 
-    # generate the human readable name
-    hrn = author + " (" + year + ")"
-    return hrn
+    if len(hrns) == 0 and len(bibcodes) != 0:
+        raise ValueError(f"Could not find any bibcodes associated with {bibcodes}!")
+
+    if isinstance(bibcode, str):
+        return hrns[0]
+
+    if len(hrns) != len(bibcodes):
+        raise ValueError(
+            f"ADS has multiple sources associated with one of these bibcodes! \
+            {bibcode}"
+        )
+
+    return bibcodes_to_return, hrns
+
+
+def freq_to_band(freq: u.Quantity) -> str:
+    """
+    Converts an effective frequency to the corresponding band name based on the
+    standards listed in RADIO_BAND_MAPPING
+
+    Args:
+        freq (astropy Quantity) : Astropy Quantity of the frequency to get the band name
+    Returns:
+        string with the commonly used band name
+    """
+
+    for key, freq_range in RADIO_BAND_MAPPING.items():
+        if freq_range[0] * u.GHz < freq <= freq_range[1] * u.GHz:
+            return key
+
+    raise ValueError(f"No band name found for the frequency {freq}. Please verify that \
+                      it is in a range in RADIO_BAND_MAPPING and, if not, add it!")
+
+
+def _wrap_single_conversion(t):
+    """
+    t is a tuple of (frequency, unit)
+    """
+    return freq_to_band(t[0] * u.Unit(t[1]))
+
+
+def freqlist_to_band(
+    freq_list: list[float], freq_unit_list: list[str], ncores=1
+) -> list[str]:
+    """
+    Converts a list of effective frequencies to the corresponding band names based on
+    the standards listed in RADIO_BAND_MAPPING
+
+    Args:
+        freq_list (list[float]): floats for the frequencies
+        freq_unit_list (list[str]): List of astropy unit strings to apply to freq_list
+        ncores (int): The number of cores to multiprocess with
+
+    Returns:
+        list of strings with the band names
+    """
+    with Pool(ncores) as p:
+        return p.map(_wrap_single_conversion, zip(freq_list, freq_unit_list))
 
 
 """
@@ -324,9 +474,13 @@ XRAY_AREAS = {
     # https://www.cosmos.esa.int/web/xmm-newton/technical-details-mirrors
     "xmm": 1500 * u.cm**2,
     "xmm slew": 1500 * u.cm**2,
+    "xmm-slew": 1500 * u.cm**2,
     "xmm pointed": 1500 * u.cm**2,
+    "xmm-newton": 1500 * u.cm**2,
     # https://cxc.harvard.edu/cdo/about_chandra
     "chandra": 600 * u.cm**2,
+    # https://www.cosmos.esa.int/documents/332006/954765/Brunner_TopicK.pdf
+    "erosita": 1500 * u.cm**2,
 }
 """
 X-Ray telescope areas that are used for converting from counts to other units.
@@ -338,6 +492,45 @@ NOTE: These are estimates from the following links
 * https://cxc.harvard.edu/cdo/about_chandra
 """
 
+# Radio Band names with frequency ranges in GHz
+RADIO_BAND_MAPPING = {
+    # use some lower bands from IEEE standards up to GMRT standards
+    # These are mostly here just as catchalls for low frequency radio telescopes
+    # like GEETEE or LOFAR
+    "HF": (0.003, 0.03),
+    "VHF": (0.03, 0.125),  # Official: (0.03, 0.3) but adjust to work with GMRT standard
+    # use GMRT standards for low frequencies
+    "gmrt.2": (0.125, 0.250),
+    "gmrt.3": (0.25, 0.55),  # Official: (0.25, 0.5)
+    # IEEE Standard Naming
+    # https://terasense.com/terahertz-technology/radio-frequency-bands/
+    "UHF": (0.55, 1),
+    "L": (1, 2),
+    "S": (2, 4),
+    "C": (4, 8),
+    "X": (8, 12),
+    "Ku": (12, 18),
+    "K": (18, 27),
+    "Ka": (27, 40),
+    # then switch to ALMA standard for mm
+    # https://www.eso.org/public/teles-instr/alma/receiver-bands/
+    # I widened some of the official ranges slightly so we don't leave gaps
+    # although these gaps probably wouldn't have mattered because **atmosphere**
+    "alma.1": (40, 50),  # Official: (35, 50)
+    "alma.3": (84, 116),  # skip alma.2 cause it's just a smaller range of alma.3
+    "alma.4": (116, 163),  # official: (125, 163)
+    "alma.5": (163, 211),
+    "alma.6": (211, 275),
+    "alma.7": (275, 373),
+    "alma.8": (373, 500),  # official: (385,500)
+    "alma.9": (500, 720),  # official: (602, 720)
+    "alma.10": (787, 950),
+}
+"""
+Mapping of common radio/mm band names to their corresponding frequency ranges.
+All frequencies are in GHz. The upperlimit is inclusive, that is these ranges
+are really (xx, yy].
+"""
 
 # define a working base directory constant
 BASEDIR = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
@@ -345,11 +538,59 @@ BASEDIR = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file
 Base directory for the OTTER API software package
 """
 
+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
+"""
+
 DATADIR = os.path.join(BASEDIR, "data", "base")
 """
 Deprecated database directory that IS NOT always constant anymore
 """
 
+####################################################################
+# The following schema dictionaries are here so the code remains
+# backwards compatible. BUT! All future code should use the pydantic
+# schema defined in schema.py
+####################################################################
+
 # Overarching schema that stops once we get down to a string or list
 schema = {
     "schema_version": {"value": "0", "comment": "Copied from tde.space"},
@@ -567,45 +808,3 @@ 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
-"""

astro_otter-0.1.0.dist-info/RECORD

@@ -1,17 +0,0 @@
-otter/__init__.py,sha256=ml7fLtTVno4fvpJvw91bAp8ff2nuRG1hZ1lMCt3ZumY,440
-otter/_version.py,sha256=IwGQL03Wwse3OmpK33wS6CFwrF8rqxvbN79PydSE480,76
-otter/exceptions.py,sha256=3lQF4AXVTfs9VRsVePQoIrXnramsPZbUL5crvf1s9Ng,1702
-otter/util.py,sha256=7ZJYeTjBmwpXKgqXcmBtxhtn2j7XSQMaBbTurPKyEO0,15788
-otter/io/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-otter/io/data_finder.py,sha256=pBGtfzjFt9pbJQR4exXP17eZoHVHClm_Jno1vXmcpAU,28026
-otter/io/host.py,sha256=ZYewz347_6FD5mVcQLDxHSS75n5RCv69xxLHAmpjoiI,4410
-otter/io/otter.py,sha256=VMtDCfiQniQNLIOL_P3NySwS-YnDF-nT4ceQjV0XJfE,18016
-otter/io/transient.py,sha256=YVOppPAqhChPx8sxRPfuC_9BBJVtE7ku5ITKkWKSL9w,35551
-otter/plotter/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-otter/plotter/otter_plotter.py,sha256=iQe5AFsB5plw5eClUfuEfqcNRiXEcKc5-hkLPVKCkg8,2091
-otter/plotter/plotter.py,sha256=i9ZAlbIjftpzyFzgCIFdye9XnppTwOSwazb5ruLpjnE,2896
-astro_otter-0.1.0.dist-info/LICENSE,sha256=s9IPE8A3CAMEaZpDhj4eaorpmfLYGB0mIGphq301PUY,1067
-astro_otter-0.1.0.dist-info/METADATA,sha256=nR8WxIF2Yez-yZxyv0kMZ-QZHuJJdcClr--J9cvbqHw,5905
-astro_otter-0.1.0.dist-info/WHEEL,sha256=Z4pYXqR_rTB7OWNDYFOm1qRk0RX6GFP2o8LgvP453Hk,91
-astro_otter-0.1.0.dist-info/top_level.txt,sha256=Wth72sCwBRUk3KZGknSKvLQDMFuJk6qiaAavMDOdG5k,6
-astro_otter-0.1.0.dist-info/RECORD,,