Merge pull request #46 from alercebroker/feat/fp_query

Exposing Forced Photometries

.github/workflows/tests.yml

@@ -29,6 +29,7 @@ jobs:
       with:
         options: "--check --verbose"
         src: "alerce/"
+        version: "~=24.0"
     - name: Test with pytest
       run: |
         coverage run --source alerce/ -m pytest tests/

alerce/search.py

@@ -160,6 +160,54 @@ def query_non_detections(self, oid, format="json", index=None, sort=None):
         )
         return q.result(index, sort)
 
+    def query_forced_photometry(self, oid, format="json", index=None, sort=None):
+        """
+        Gets all forced photometry epochs of a given object
+
+        Parameters
+        ----------
+        oid : str
+            The object identifier
+        format : str
+            Return format. Can be one of 'pandas' | 'votable' | 'json'
+        """
+        q = self._request(
+            "GET",
+            "https://api.alerce.online/v2/lightcurve/forced-photometry/%s" % oid,
+            result_format=format,
+        )
+
+        # NOTA: la api principal de ztf no tiene ruta de forced photometry, la v2 si tiene. Esto es lo mas facil
+        # pero no es correcto.
+
+        # all this extra code is to expand the extra fields.
+        complete_result = q.result(index, sort)
+
+        FIELDS_TO_REMOVE = ["extra_fields", "aid", "sid"]
+
+        if format == "json":
+            parsed_result = []
+            for result in complete_result:
+                new_result = result.copy()
+                extra_fields = new_result.pop("extra_fields", {})
+                for f_t_r in FIELDS_TO_REMOVE:
+                    new_result.pop(f_t_r, None)
+                new_result.update(extra_fields)
+                parsed_result.append(new_result)
+        if format == "pandas" or format == "csv":
+            extra_fields = complete_result["extra_fields"].copy()
+            complete_result = complete_result.drop(columns=FIELDS_TO_REMOVE)
+            # expand
+            import pandas as pd
+
+            extra_fields = pd.json_normalize(extra_fields)
+            # merge
+            parsed_result = complete_result.merge(extra_fields)
+            if format == "csv":
+                parsed_result = parsed_result.to_csv(index=False)
+
+        return parsed_result
+
     def query_magstats(self, oid, format="json", index=None, sort=None):
         """
         Gets magnitude statistics of a given object

docs/source/models/detection.rst

@@ -40,7 +40,7 @@ Detection Response
     - Magnitude from PSF-fit photometry [mag]
   * - sigmapsf
     - number
-    - 1-sigma uncertainty in magap [mag]
+    - 1-sigma uncertainty in magpsf [mag]
   * - magap
     - number
     - Aperture mag using 8 pixel diameter aperture [mag]

docs/source/models/forced_photometry.rst

@@ -0,0 +1,133 @@
+Forced Photometry Response
+=========================
+
+.. list-table:: Forced Photometry Response Model
+  :widths: 20 10 70
+  :header-rows: 1
+
+  * - Name
+    - Type
+    - Description
+  * - pid
+    - integer
+    - Processing ID for image
+  * - mjd
+    - number
+    - Modified julian Date
+  * - fid
+    - integer
+    - Filter ID (1=g; 2=r; 3=i)
+  * - ra
+    - number
+    - Right Ascension of epoch (same as of candidate) [deg]
+  * - dec
+    - number
+    - Declination of epoch (same as of candidate) [deg]
+  * - e_ra
+    - number
+    - Right Ascension uncertainty
+  * - e_dec
+    - number
+    - Declination uncertainty
+  * - mag
+    - number
+    - Magnitude from PSF-fit photometry [mag], obtained from magzpsci and forcediffimflux avro fields
+  * - e_mag
+    - number
+    - 1-sigma uncertainty in mag [mag], obtained from forcediffimflux and forcediffimfluxunc avro fields
+  * - mag_corr
+    - number
+    - Corrected PSF magnitude
+  * - e_mag_corr
+    - number
+    - Error of the corrected PSF magnitude assuming no contribution from an extended component
+  * - e_mag_corr_ext
+    - number
+    - Error of the corrected PSF magnitude assuming a contribution from an extended component
+  * - isdiffpos
+    - integer
+    - 1: candidate is from positive (sci minus ref) subtraction; -1: didate is from negative (ref minus sci) subtraction
+  * - corrected
+    - boolean
+    - Whether the corrected photometry was applied
+  * - dubious
+    - boolean
+    - Whether the corrected photometry should be flagged
+  * - parent_candid
+    - number
+    - candid of the alert for which forced photometry was triggered
+  * - has_stamp
+    - boolean
+    - Whether the epoch has an associated image stamp triplet (always False for forced photometry)
+  * - field
+    - integer
+    - ZTF field ID
+  * - rcid
+    - integer
+    - Readout channel ID [00 .. 63]
+  * - rfid
+    - integer
+    - Processing ID for reference image to facilitate archive retrieval
+  * - sciinpseeing
+    - number
+    - Effective FWHM of sci image [pixels]
+  * - scibckgnd
+    - number
+    - Background level in sci image [DN]
+  * - scisigpix
+    - number
+    - Robust sigma per pixel in sci image [DN]
+  * - magzpsci
+    - number
+    - Magnitude zero point for photometry estimates [mag]
+  * - magzpsciunc
+    - number
+    - Magnitude zero point uncertainty (in magzpsci) [mag]
+  * - magzpscirms
+    - number
+    - RMS (deviation from average) in all differences between instrumental photometry and matched photometric calibrators from science image processing [mag]
+  * - clrcoeff
+    - number
+    - Color coefficient from linear fit from photometric calibration of science image
+  * - clrcounc
+    - number
+    - Color coefficient uncertainty from linear fit (corresponding to clrcoeff)
+  * - exptime
+    - number
+    - Integration time of camera exposure [sec]
+  * - adpctdif1
+    - number
+    - Full sci image astrometric RMS along R.A. with respect to Gaia1 [arcsec]
+  * - adpctdif2
+    - number
+    - Full sci image astrometric RMS along Dec. with respect to Gaia1 [arcsec]
+  * - diffmaglim
+    - number 
+    - Expected 5-sigma mag limit in difference image based on global noise estimate [mag]
+  * - programid
+    - integer
+    - Program ID: encodes either public, collab, or caltech mode
+  * - procstatus
+    - string
+    - Forced photometry processing status codes (0 => no warnings); see documentation
+  * - distnr
+    - number
+    - distance to nearest source in reference image PSF-catalog [arcsec]
+  * - ranr
+    - number
+    - Right Ascension of nearest source in reference image PSF-catalog; J2000 [deg]
+  * - decnr
+    - number
+    - Declination of nearest source in reference image PSF-catalog; J2000 [deg]
+  * - magnr
+    - number
+    - magnitude of nearest source in reference image PSF-catalog [mag]
+  * - sigmagnr
+    - number
+    - 1-sigma uncertainty in magnr [mag]    
+  * - chinr
+    - number
+    - DAOPhot chi parameter of nearest source in reference image PSF-catalog
+  * - sharpnr
+    - number 
+    - DAOPhot sharp parameter of nearest source in reference image PSF-catalog

tests/test_search.py

@@ -175,3 +175,17 @@ def test_query_classes(mock_request):
     mock_request.return_value.status_code = 200
     r = alerce.query_classes("lc_classifier", "bulk_0.0.1")
     assert r is not None
+
+@patch.object(Session, "request")
+def test_query_detections(mock_request):
+    def mock_result():
+        return [
+            {"candid":"candid1","tid":"ztf","sid":None,"aid":None,"pid":1234,"oid":"oid"},
+            {"candid":"candid2","tid":"ztf","sid":None,"aid":None,"pid":1234,"oid":"oid"}
+        ]
+
+    mock_request.return_value.status_code = 200
+    mock_request.return_value.json = mock_result
+
+    r = alerce.query_forced_photometry("oid")
+    assert r is not None