adding source detection step

docs/roman/package_index.rst

@@ -5,3 +5,4 @@
    references_general/index.rst
    stpipe/index.rst
    refpix/index.rst
+   source_detection/index.rst

docs/roman/ramp_fitting/arguments.rst

@@ -2,18 +2,45 @@ Arguments
 =========
 The ramp fitting step has three optional arguments that can be set by the user:
 
-* ``--save_opt``: A True/False value that specifies whether to write
-  the optional output product. Default if False.
+* ``--save_catalog``: A True/False flag to specify if the source catalog should
+                      be saved to an output file. The name of this file will be
+                      the rootname of the input file, with the suffix
+                      'source_cat.csv'. Defaults to False
+* ``--catalog_output_name``: Invoked only if `save_catalog=True`. New rootname
+                            for output catalog, overriding the default of using
+                            the file input name. Defaults to None
+* ``--catalog_output_dir``:  Invoked only if `save_catalog=True`. Directory
+                            for output catalog, overriding the default of using
+                            the file input directory. Defaults to None
 
-* ``--opt_name``: A string that can be used to override the default name
-  for the optional output product.
-
-* ``--maximum_cores``: The fraction of available cores that will be
-  used for multi-processing in this step. The default value is 'none' which does not use
-  multi-processing. The other options are 'quarter', 'half', and 'all'. Note that these
-  fractions refer to the total available cores and on most CPUs these include physical
-  and virtual cores. The clock time for the step is reduced
-  almost linearly by the number of physical cores used on all machines. For example, on an Intel CPU with
-  six real cores and 6 virtual cores setting maximum_cores to 'half' results in a
-  decrease of a factor of six in the clock time for the step to run. Depending on the system
-  the clock time can also decrease even more with maximum_cores is set to 'all'.
+* ``--kernel_fwhm``: A parameter for DAOStarFinder. The size of the Gaussian
+                     kernel, in pixels.
+* ``--sharplo``: A parameter for DAOStarFinder. Lower bound for source
+                  sharpness. Default is 0.5.
+* ``--sharphi``: A parameter for DAOStarFinder. Upper bound for source
+                 sharpness. Default is 
+* ``--roundlo``: A parameter for DAOStarFinder. Lower bound for source roundness.
+* ``--roundhi``: A parameter for DAOStarFinder. Upper bound for source roundness.
+* ``--peakmax``: A parameter for DAOStarFinder. Upper limit on brightest pixel.
+                 in sources.
+* ``--max_sources``: The maximum number of sources in the ouput catalog, ranked
+                     by brightness. Dimmer objects will be eliminated.
+* ``--scalar_threshold``: If specified, a singular, scalar value to be used as
+                          the detection threshold for source detection with
+                          DAOStarFinder. One of scalar_threshold, calc_threshold,
+                          or calc_threshold_2d must be specified. Default is None.
+* ``--calc_threshold``: If True, a single scalar value for the detection
+                        threshold for source detection with DAOStarFinder will
+                        be used. Default is False.
+* ``--calc_threshold_2d``: If True, a 2d threshold image will be used for source
+                           detection. The image will be split into boxes of size
+                           `bkg_boxsize`, and the threshold will be computed in
+                           each box. DAOStarFinder will then run on the image
+                           in boxes of the same size, using that threshold for
+                           detection. Default is False.
+* ``--snr_threhsold``:
+* ``--bkg_estimator``:
+* ``--bkg_boxsize``:
+* ``--bkg_sigma``:
+* ``--bkg_filter_size``:
+* ``--bkg_coverage_mask``:

docs/roman/source_detection/arguments.rst

@@ -0,0 +1,55 @@
+Arguments
+=========
+The source detection fitting step has several arguments. These can be specified by the user by passing
+them to the step in a Python session, or setting them in a parameter file. 
+
+* ``--save_catalogs``: A True/False value that specifies whether to write
+  the optional output catalog. Default is False.
+
+* ``--kernel_fwhm``: A parameter for DAOStarFinder: size of Gaussian kernel in
+                     pixels. Default is 1.5.
+* ``--sharplo``: A parameter for DAOStarFinder: lower bound for sharpness.
+                 Default is 0.5.
+* ``--sharphi``: A parameter for DAOStarFinder: upper bound for sharpness.
+                 Default is 1.0.
+* ``--roundlo``: A parameter for DAOStarFinder: lower bound for roundness.
+                 Default is -1.0.
+* ``--roundhi``: A parameter for DAOStarFinder: upper bound for roundness.
+                 Default is 1.0.
+* ``--peakmax``: A parameter for DAOStarFinder: upper limit on brightest pixel
+                 in sources. Default is 1000.0.
+* ``--max_sources``: The maximum number of sources in the output catalog,
+                     choosing brightest. Default is None, which will return all
+                     detected sources.
+* ``--scalar_threshold``: If specified, a single scalar threshold to be used
+                          for source detection with DAOStarFinder across the
+                          entire image. One of `scalar_threshold`,
+                          `calc_scalar_threshold`, or `calc_threshold_2d` must
+                          be chosen. Default is None.
+* ``--calc_scalar_threshold``: If specified, a single scalar threshold will be
+                               determined for the entire image. This is done by
+                               calculating a 2D background image, and using that
+                               to determine a single threshold value for the
+                               entire image. One of `scalar_threshold`,
+                               `calc_scalar_threshold`, or `calc_threshold_2d`
+                               must be chosen.
+* ``--calc_threshold_2d``: (**NOTE: this option is not currently enabled**) 
+                           If specified, a 2D threshold image will be calculated,
+                           and sources will be detected in segments of the image
+                           to use these thresholds (based on `bkg_boxsize`).
+* ``--snr_threshold``: If using `calc_threshold_img` or `calc_threshold_2d`,
+                       the SNR for the threshold image. Default is 3.0.
+* ``--bkg_estimator``: If using `calc_threshold_img` or `calc_threshold_2d`, 
+                       choice of mean, median, or mode. Default is `median`.
+* ``--bkg_boxsize``: If using `calc_threshold_img` or `calc_threshold_2d`, 
+                     size of box in pixels for 2D background / threshold images
+                     and if using calc_threshold_2d, the size of the box used
+                     when detecting sources. Default is 3.
+* ``--bkg_sigma``: If using `calc_threshold_img` or `calc_threshold_2d`, 
+                    n sigma for sigma clipping for background calculation.
+                    Default is 2.0.
+* ``--bkg_filter_size``: If using `calc_threshold_img` or `calc_threshold_2d`,
+                         size of square gaussian kernel for background
+                         calculation. Default is 3.
+* ``--coverage_mask``: Optional mask for image (i.e to mask artifacts).
+                           Default is None.

docs/roman/source_detection/description.rst

@@ -0,0 +1,41 @@
+Description
+============
+
+The source detection step produces catalogs of point-like sources for use by the
+tweakreg step for image alignment. It uses DAOStarFinder to detect point sources
+in the image. The output source catalog will be returned with the output file
+as an attribute under `meta.source_catalog`, in a dictionary keyed by input
+file rootname. Optionally, the file may be saved to disk as well.
+
+Options for Thresholding
+========================
+
+The DAOStarFinder routine detects point-like sources in in image that are above
+a certain, specified floating point threshold. This step provides several options
+for calculating this threshold, either using one value for the entire image, 
+or by detecting sources in segments of the image and using a different appropriate
+threshold for each (useful if background varies across the image).
+
+The first option is to set `scalar_threshold` - this will use the specified
+threshold as the detection threshold for the entire image.
+
+The second option is to use `calc_threshold` - this will calculate a single
+threshold value for the entire image on-the-fly, based on the median background
+level of the whole image.
+
+(**NOTE: this option is not currently enabled**) Finally, if `calc_threshold_2d`
+is set, a 2D threshold image will be generated, and sources will be deteteced
+within each box of this image.
+
+Output Catalogs
+===============
+
+The output catalog will be in the form of an astropy table stored in the output
+image's `meta` section. If `save_catalogs` is specified, a `.csv` table will
+be written out to the same directory as the input image. The output catalogs
+will contain the following columns - `id`, `xcentroid`, `ycentroid`, `flux`,
+where `id` is the source ID (a unique identifier determined by DAOStarFinder),
+`xcentroid` and `ycentroid` are the centroid positions of the detected source
+in image coordinates, and `flux` is the non-background subtracted total sum
+within the source. If `calc_threshold_2d` is used, there will be additional
+columns reporting the threshold level used for that source.

docs/roman/source_detection/index.rst

@@ -0,0 +1,13 @@
+.. _source_detection_step:
+
+================
+Source Detection
+================
+
+.. toctree::
+   :maxdepth: 2
+
+   description.rst
+   arguments.rst
+
+.. automodapi:: romancal.source_detection

romancal/pipeline/exposure_pipeline.py

@@ -16,6 +16,7 @@
 from romancal.dark_current import DarkCurrentStep
 from romancal.linearity import LinearityStep
 from romancal.photom import PhotomStep
+from romancal.source_detection import SourceDetectionStep
 from romancal.ramp_fitting import ramp_fit_step
 from romancal.saturation import SaturationStep
 
@@ -52,6 +53,7 @@ class ExposurePipeline(RomanPipeline):
                  'assign_wcs': AssignWcsStep,
                  'flatfield': FlatFieldStep,
                  'photom': PhotomStep,
+                 'source_detection': SourceDetectionStep
                  }
 
     # start the actual processing
@@ -109,6 +111,8 @@ def process(self, input):
             result.meta.cal_step.flat_field = 'SKIPPED'
         result = self.photom(result)
 
+        result = self.source_detection(result)
+
         # setup output_file for saving
         self.setup_output(result)
         log.info('Roman exposure calibration pipeline ending...')
@@ -145,7 +149,7 @@ def create_fully_saturated_zeroed_image(self, input_model):
 
         # Set all subsequent steps to skipped
         for step_str in ['linearity', 'dark', 'jump', 'ramp_fit', 'assign_wcs',
-                         'flat_field', 'photom']:
+                         'flat_field', 'photom', 'source_detection']:
             fully_saturated_model.meta.cal_step[step_str] = 'SKIPPED'
 
         # Set suffix for proper output naming

romancal/source_detection/__init__.py

@@ -0,0 +1,3 @@
+from .source_detection_step import SourceDetectionStep
+
+__all__ = ['SourceDetectionStep']