Merge pull request #58 from lsst/tickets/DM-35186

Add focus_z to properties.

python/astro_metadata_translator/observationInfo.py

@@ -135,6 +135,7 @@ class ObservationInfo:
         detector_serial: str
         detector_group: str
         detector_exposure_id: int
+        focus_z: astropy.units.Quantity
         object: str
         temperature: astropy.units.Quantity
         pressure: astropy.units.Quantity

python/astro_metadata_translator/properties.py

@@ -103,6 +103,16 @@ def simple_to_angle(simple: float, **kwargs: Any) -> astropy.coordinates.Angle:
     return astropy.coordinates.Angle(simple * astropy.units.deg)
 
 
+def focusz_to_simple(focusz: astropy.units.Quantity) -> float:
+    """Convert focusz to meters."""
+    return focusz.to_value(astropy.units.m)
+
+
+def simple_to_focusz(simple: float, **kwargs: Any) -> astropy.units.Quantity:
+    """Convert simple form back to Quantity."""
+    return simple * astropy.units.m
+
+
 def temperature_to_simple(temp: astropy.units.Quantity) -> float:
     """Convert temperature to kelvin."""
     return temp.to(astropy.units.K, equivalencies=astropy.units.temperature()).to_value()
@@ -274,6 +284,13 @@ class PropertyDefinition:
         "int",
         int,
     ),
+    "focus_z": PropertyDefinition(
+        "Defocal distance.",
+        "astropy.units.Quantity",
+        astropy.units.Quantity,
+        focusz_to_simple,
+        simple_to_focusz,
+    ),
     "object": PropertyDefinition("Object of interest or field name.", "str", str),
     "temperature": PropertyDefinition(
         "Temperature outside the dome.",

python/astro_metadata_translator/translator.py

@@ -1113,6 +1113,19 @@ def to_has_simulated_content(self) -> bool:
         """
         return False
 
+    @cache_translation
+    def to_focus_z(self) -> u.Quantity:
+        """Return a default defocal distance of 0.0 mm if there is no
+        keyword for defocal distance in the header. The default
+        keyword for defocal distance is ``FOCUSZ``.
+
+        Returns
+        -------
+        focus_z: `astropy.units.Quantity`
+            The defocal distance from header or the 0.0mm default
+        """
+        return 0.0 * u.mm
+
     @classmethod
     def determine_translatable_headers(
         cls, filename: str, primary: Optional[MutableMapping[str, Any]] = None

python/astro_metadata_translator/translators/decam.py

@@ -314,6 +314,14 @@ def to_detector_name(self) -> str:
         name = self.to_detector_unique_name()
         return name[1:]
 
+    @cache_translation
+    def to_focus_z(self) -> u.Quantity:
+        # Docstring will be inherited. Property defined in properties.py
+        # ``TELFOCUS`` is a comma-separated string with six focus offsets
+        # (fx, fy, fz, tx, ty, tz) recorded in units of microns.
+        tel_focus_list = self._header["TELFOCUS"].split(",")
+        return float(tel_focus_list[2]) * u.um
+
     @classmethod
     def fix_header(
         cls, header: MutableMapping[str, Any], instrument: str, obsid: str, filename: Optional[str] = None

python/astro_metadata_translator/translators/fits.py

@@ -38,7 +38,8 @@ class FitsTranslator(MetadataTranslator):
 
     # Direct translation from header key to standard form
     _trivial_map: Dict[str, Union[str, List[str], Tuple[Any, ...]]] = dict(
-        instrument="INSTRUME", telescope="TELESCOP"
+        instrument="INSTRUME",
+        telescope="TELESCOP",
     )
 
     @classmethod

python/astro_metadata_translator/translators/hsc.py

@@ -301,3 +301,9 @@ def to_detector_name(self) -> str:
         # Name is defined from unique name
         unique = self.to_detector_unique_name()
         return unique.split("_")[1]
+
+    @cache_translation
+    def to_focus_z(self) -> u.Quantity:
+        # Docstring will be inherited. Property defined in properties.py
+        foc_val = self._header["FOC-VAL"]
+        return foc_val * u.mm

tests/test_basics.py

@@ -44,6 +44,7 @@ def test_simple(self):
 
         reference = dict(
             boresight_airmass=1.5,
+            focus_z=1.0 * u.mm,
             temperature=15 * u.deg_C,
             observation_type="bias",
             exposure_time=5 * u.ks,

tests/test_cfht.py

@@ -41,6 +41,7 @@ def test_megaprime_translator(self):
                     exposure_id=1038843,
                     exposure_group="1038843",
                     exposure_time=615.037 * u.s,
+                    focus_z=0.0 * u.mm,  # default value
                     group_counter_end=1038843,
                     group_counter_start=1038843,
                     has_simulated_content=False,
@@ -74,6 +75,7 @@ def test_megaprime_translator(self):
                     exposure_id=849375,
                     exposure_group="849375",
                     exposure_time=300.202 * u.s,
+                    focus_z=0.0 * u.mm,  # default value
                     group_counter_end=849375,
                     group_counter_start=849375,
                     has_simulated_content=False,

tests/test_decam.py

@@ -40,6 +40,7 @@ def test_decam_translator(self):
                     exposure_id=229388,
                     exposure_group="229388",
                     exposure_time=200.0 * u.s,
+                    focus_z=2497.32 * u.um,
                     group_counter_end=229388,
                     group_counter_start=229388,
                     has_simulated_content=False,
@@ -75,6 +76,7 @@ def test_decam_translator(self):
                     exposure_id=160496,
                     exposure_group="160496",
                     exposure_time=0.0 * u.s,
+                    focus_z=0.0 * u.um,
                     group_counter_end=160496,
                     group_counter_start=160496,
                     has_simulated_content=False,
@@ -110,6 +112,7 @@ def test_decam_translator(self):
                     exposure_id=412037,
                     exposure_group="412037",
                     exposure_time=86.0 * u.s,
+                    focus_z=2828.00 * u.um,
                     group_counter_end=412037,
                     group_counter_start=412037,
                     has_simulated_content=False,
@@ -145,6 +148,7 @@ def test_decam_translator(self):
                     exposure_id=845291,
                     exposure_group="845291",
                     exposure_time=120.0 * u.s,
+                    focus_z=2174.28 * u.um,
                     group_counter_end=845291,
                     group_counter_start=845291,
                     has_simulated_content=False,

tests/test_subaru.py

@@ -40,6 +40,7 @@ def test_hsc_translator(self):
                     exposure_id=904024,
                     exposure_group="904024",
                     exposure_time=30.0 * u.s,
+                    focus_z=3.7 * u.mm,
                     group_counter_end=904024,
                     group_counter_start=904024,
                     has_simulated_content=False,
@@ -72,6 +73,7 @@ def test_hsc_translator(self):
                     exposure_id=40900,
                     exposure_group="40900",
                     exposure_time=150.0 * u.s,
+                    focus_z=3.83 * u.mm,
                     group_counter_end=40900,
                     group_counter_start=40900,
                     has_simulated_content=False,