Issue 326 darktime updates (#467)

* Modified reading of CCDTAB

* Removed hard-coded darktime scaling value and read new post-flashed
and unflashed columns from an updated CCDTAB to use for the offset to
the DARKTIME keyword value for appropriate date and supported subarrary
criteria.  The DARKTIME keyword value is the default scaling factor for
the superdarks, with the offset being an additive correction.

* Update to ensure the supported subaperture array is complete.

* Added a new PyTest to accommodate the updated darktime correction.
Full-frame data is categorized as pre- and post-SM4, and post-flashed or
unflashed.  Subarray data is categorized as pre- and post-Cycle24, and
post-flashed or unflashed.  The post-Cycle24 data must also be a
"supported" subarray to have the offset adjustment applied.

* Added curley braces to all "if" blocks in dodark.c, and removed some
deprecated code.  Set the full frame CTE tests in the new Pytest,
test_wfc_darktime.py, to SKIP.

pkg/acs/calacs/Dates

@@ -1,3 +1,10 @@
+ 10-Jan-2020   CALACS 10.2.2 Removed hard-coded darktime scaling value and read new 
+                             post-flashed and unflashed columns from updated CCDTAB reference 
+                             file to use for the offset to the DARKTIME FITS keyword value 
+                             under appropropriate date and supported subarray criteria.  The 
+                             DARKTIME keyword value is now the default scaling factor for the 
+                             superdarks, with the offset being an additive correction to DARKTIME 
+                             under appropriate circumstances.  The offset only applies to WFC and HRC.
  25-Sep-2019   CALACS 10.2.1 CALACS has been modified to allow the PHOTMODE keyword
                              to be updated with the MJDUTC for the SBC, in addition to
                              the HRC and WFC. This will allow time-dependent sensitivity

pkg/acs/calacs/History

@@ -1,3 +1,12 @@
+### 10-Jan-2020 - MDD -- Version 10.2.2
+    Removed hard-coded darktime scaling value and read new post-flashed and
+    unflashed columns from updated CCDTAB reference file to use for the
+    offset to the DARKTIME FITS keyword value under appropropriate
+    date and supported subarray criteria.  The DARKTIME keyword value is 
+    now the default scaling factor for the superdarks, with the offset 
+    being an additive correction to DARKTIME under appropriate circumstances
+    The offset only applies to WFC and HRC.
+
 ### 25-Sep-2019 - MDD -- Version 10.2.1
     CALACS has been modified to allow the PHOTMODE keyword to be updated with
     the MJD for the SBC, in addition to the HRC and WFC. This will allow

pkg/acs/calacs/Updates

@@ -1,4 +1,16 @@
-update for version 10.2.1 - 25-Sep-2019 (MDD)
+Update for version 10.2.2 - 10-Jan-2020 (MDD)
+    pkg/acs/calacs/Dates
+    pkg/acs/calacs/History
+    pkg/acs/calacs/Updates
+    pkg/acs/calacs/acs2d/dodark.c
+    pkg/acs/calacs/include/acs.h
+	pkg/acs/calacs/include/acsinfo.h
+	pkg/acs/calacs/include/acsversion.h
+	pkg/acs/calacs/lib/acsinfo.c
+	pkg/acs/calacs/lib/getacskeys.c
+	pkg/acs/calacs/lib/getccdtab.c
+
+Update for version 10.2.1 - 25-Sep-2019 (MDD)
     pkg/acs/calacs/Dates
     pkg/acs/calacs/History
     pkg/acs/calacs/Updates

pkg/acs/calacs/acs2d/dodark.c

@@ -56,7 +56,26 @@
  M.D. De La Pena, 2018 June 05:
  Dark correction processing is now done on the entire image instead of 
  line by line. Also, performed some clean up and new commentary.
+ M.D. De La Pena, 2019 November 26:
+ Removed hard-coded darktime scaling value and read new
+ post-flashed and unflashed columns from updated CCDTAB reference
+ file to use for the offset to the DARKTIME FITS keyword value
+ under appropropriate date and supported subarray criteria.  The
+ DARKTIME keyword value is now the default scaling factor for the
+ superdarks, with the offset being an additive correction to DARKTIME
+ under appropriate circumstances. The offset values is applicable for 
+ WFC and HRC only.
  */
+static const char *subApertures[] = {"WFC1A-2K", "WFC1B-2K", "WFC2C-2K", "WFC2D-2K",
+                                     "WFC1A-1K", "WFC1B-1K", "WFC2C-1K", "WFC2D-1K",
+                                     "WFC1A-512", "WFC1B-512", "WFC2C-512", "WFC2D-512",
+                                     "WFC1-IRAMPQ", "WFC1-MRAMPQ", "WFC2-ORAMPQ",
+                                     "WFC1-POL0UV", "WFC1-POL0V", 
+                                     "WFC1-POL60UV", "WFC1-POL60V", 
+                                     "WFC1-POL120UV", "WFC1-POL120V", 
+                                     "WFC1-SMFL"};
+
+static const int numSupportedSubApertures = sizeof(subApertures) / sizeof(subApertures[0]);
 
 int doDark (ACSInfo *acs2d, SingleGroup *x, float *meandark) {
 
@@ -68,8 +87,6 @@ int doDark (ACSInfo *acs2d, SingleGroup *x, float *meandark) {
 
   extern int status;
 
-  const float darkscaling = 3.0;  /* Extra idle time */
-
   int extver = 1;	/* get this imset from dark image */
 
   /* Assumption is the science and dark images are the same size and bin factor */
@@ -82,7 +99,9 @@ int doDark (ACSInfo *acs2d, SingleGroup *x, float *meandark) {
   double mean;      /* mean value for the image */
   double weight;    /* weight value for the image (No. good pixels/all pixels) */
   int update;
-  float darktime;
+  float darktimeFromHeader;  /* base darktime value based upon FITS keyword DARKTIME from image header */
+  float darktime;        /* final darktime value after applicable offset, if any */
+  float darktimeOffset;  /* overhead offset time (s) based upon full-frame/subarray and post-flashed/unflashed */
 
   int DetCCDChip (char *, int, int, int *);
 
@@ -97,28 +116,71 @@ int doDark (ACSInfo *acs2d, SingleGroup *x, float *meandark) {
   scicols = x->sci.data.nx;
   scirows = x->sci.data.ny; 
 
-  /* Compute DARKTIME */
-  /* SBC does not have FLASH keywords */
-  if (acs2d->detector == MAMA_DETECTOR)
-     darktime = acs2d->exptime;
-  else {
-     darktime = acs2d->exptime + acs2d->flashdur;
-
-     /* Post-SM4 non-BIAS WFC only */
-     /* TARGNAME unavailable, assume EXPTIME=0 means BIAS */
-     if (acs2d->detector == WFC_CCD_DETECTOR && acs2d->expstart > SM4MJD && acs2d->exptime > 0)
-        darktime += darkscaling;
+  /* Get the DARKTIME FITS keyword value stored in the ACSInfo structure */
+  darktimeFromHeader = (float)acs2d->darktime;
+
+  /*
+     The overhead offset time is a function of full-frame vs subarray and post-flash vs unflashed 
+     and has been determined empirically for CCD data.  Both the unflashed and post-flash
+     overhead values for full-frame or subarray were extracted from the calibration file 
+     during the table read.  Now it is just necessary to determine which offset actually
+     applies.
+  */
+
+  /* Unflashed observation */
+  darktimeOffset = acs2d->overhead_unflashed;
+
+  /* Post-flashed observation */
+  if ((acs2d->flashdur > 0.0) && (strcmp(acs2d->flashstatus, "SUCCESSFUL") == 0)) {
+        darktimeOffset = acs2d->overhead_postflashed;
   }
-
+
+  /* 
+     Compute the final darktime based upon the date of full-frame or subarray data.
+     The full-frame overhead offset is applicable to all data post-SM4.  The subarray 
+     overhead offset is applicable to all data post-CYCLE24 and ONLY for supported
+     subarrays. 
+
+     Effectively the additive factor only applies to ACS/WFC as the HRC was no longer
+     operational by SM4MJD or CYCLE24, and SBC is a MAMA detector.
+  */
+  darktime = darktimeFromHeader;  /* Default */
+  if (acs2d->detector != MAMA_DETECTOR) {
+
+     /* Full-frame data */
+     if (acs2d->subarray == NO) {
+         if (acs2d->expstart >= SM4MJD) {
+              darktime = darktimeFromHeader + darktimeOffset;
+         }
+         sprintf(MsgText, "Full Frame adjusted Darktime: %f\n", darktime);
+         trlmessage(MsgText);
+
+     /* Subarray data */
+     } else {
+         if (acs2d->expstart >= CYCLE24) {
+             for (unsigned int i = 0; i < numSupportedSubApertures; i++) {
+                 if (strcmp(acs2d->aperture, subApertures[i]) == 0) {
+                     darktime = darktimeFromHeader + darktimeOffset;
+                     sprintf(MsgText, "Supported Subarray adjusted Darktime: %f for aperture: %s\n", darktime, subApertures[i]);
+                     trlmessage(MsgText);
+                     break;
+                 }
+             }
+         }
+     }
+  }
+
   /* Compute correct extension version number to extract from
      reference image to correspond to CHIP in science data.
   */
   if (acs2d->pctecorr == PERFORM) {
-     if (DetCCDChip (acs2d->darkcte.name, acs2d->chip, acs2d->nimsets, &extver) )
+     if (DetCCDChip (acs2d->darkcte.name, acs2d->chip, acs2d->nimsets, &extver) ) {
         return (status);
+     }
   } else {
-     if (DetCCDChip (acs2d->dark.name, acs2d->chip, acs2d->nimsets, &extver) )
+     if (DetCCDChip (acs2d->dark.name, acs2d->chip, acs2d->nimsets, &extver) ) {
         return (status);
+     }
   }
 
   if (acs2d->verbose) {
@@ -207,13 +269,6 @@ int doDark (ACSInfo *acs2d, SingleGroup *x, float *meandark) {
      return (status);
   }
 
-  /* Compute the weighted mean for the image */	
-  /* *** MDD FIX - Not sure this is really needed anymore */
-  /*
-  *meandark = 0.0;
-  if ( (weight > 0.0) && (scirows > 0) )
-     *meandark = (float) (mean / weight); 
-  */
   /* This is to force a compatibility match to the previous version of the
      code.  
   */

pkg/acs/calacs/include/acs.h

@@ -87,6 +87,9 @@ void errchk ();                 /* HSTIO error check */
 
 # define        SM4MJD          54967
 
+/* October 01, 2016: Date of first observation in Cycle 24. The new ACS subarray configurations validated for Cycle 24. */
+# define        CYCLE24         57662
+
 /* A reference image. */
 typedef struct {
     char name[CHAR_FNAME_LENGTH];            /* name of image */

pkg/acs/calacs/include/acsinfo.h

@@ -91,6 +91,9 @@ typedef struct {
     int biassectb[2];   /* Columns to use for trailing overscan region */
     float flashdur; 	/* duration of post-flash (in seconds) */
     char flashstatus[ACS_CBUF+1];		/* status of post-flash exposure */
+    float overhead_postflashed;  /* Overhead for post-flashed observations (s) */
+    float overhead_unflashed;    /* Overhead for unflashed observations (s) */
+    double darktime;    /* total time for dark current to accrue (s) */
 
     /* calibration flags (switches) for ACSCCD */
     int dqicorr;        /* data quality initialization */

pkg/acs/calacs/include/acsversion.h

@@ -2,8 +2,8 @@
 #define INCL_ACSVERSION_H
 
 /* This string is written to the output primary header as CAL_VER. */
-#define ACS_CAL_VER "10.2.1 (25-Sept-2019)"
-#define ACS_CAL_VER_NUM "10.2.1"
+#define ACS_CAL_VER "10.2.2 (10-Jan-2020)"
+#define ACS_CAL_VER_NUM "10.2.2"
 
 /* name and version number of the CTE correction algorithm */
 #define ACS_GEN1_CTE_NAME "PixelCTE 2012"

pkg/acs/calacs/lib/acsinfo.c

@@ -11,6 +11,7 @@
    17-Apr-2002 WJH - removed all references to 'statcorr'.
    12-Dec-2012 PLL - added CTE corrected flash reference file.
    12-Aug-2013 PLL - Tidied up code layout.
+   05-Dec-2019 MDD - Added overhead for post-flash, unflashed, and DARKTIME values.
 */
 #include <string.h>
 
@@ -100,6 +101,9 @@ void ACSInit (ACSInfo *acs) {
     acs->biassectb[1] = 0;
     acs->flashdur = 0;
     acs->flashstatus[0] = '\0';
+    acs->overhead_postflashed = 0.;
+    acs->overhead_unflashed = 0.;
+    acs->darktime = 0.;
 
     /* Initialize Calibration switches */
     acs->dqicorr = OMIT;

pkg/acs/calacs/lib/getacskeys.c

@@ -22,6 +22,7 @@
  4-Dec-2001 WJH - Read in EXPSTART and EXPEND for computing darktime.
  12-Dec-2012 PLL - Changed FLASHDUR and FLASHSTA defaults.
  26-Jul-2018 MDD - Convert APERTURE and JWROTYPE values to upper-case. 
+ 05-Dec-2019 MDD - Read the DARKTIME keyword and convert FLASHSTA to upper-case.
  */
 
 int getACSKeys (ACSInfo *acs, Hdr *phdr) {
@@ -113,6 +114,9 @@ int getACSKeys (ACSInfo *acs, Hdr *phdr) {
             return (status);
         if (GetKeyStr (phdr, "FLASHSTA", USE_DEFAULT, "", acs->flashstatus, ACS_CBUF))
             return (status);
+
+	    if (GetKeyDbl (phdr, "DARKTIME", USE_DEFAULT, 0., &acs->darktime))
+        return (status);
     }
 	return (status);
 }
@@ -143,6 +147,7 @@ int checkACSKeys(ACSInfo *acs)
 
     upperCase(&acs->aperture);
     upperCase(&acs->jwrotype);
+    upperCase(&acs->flashstatus);
 
     // Convert number of extensions to number of SingleGroups.
     // NOTE: this is technically incorrect and instead findTotalNumberOfImsets()