Step Arguments
==============

The ``extract_1d`` step has the following step-specific arguments.

``--smoothing_length``
  If ``smoothing_length`` is greater than 1 (and is an odd integer), the
  image data used to perform background extraction will be smoothed in the
  dispersion direction with a boxcar of this width.  If ``smoothing_length``
  is None (the default), the step will attempt to read the value from the
  :ref:`EXTRACT1D <extract1d_reffile>` reference file.
  If a value is specified in the reference file,
  that value will be used.  Note that by specifying this parameter in the
  :ref:`EXTRACT1D <extract1d_reffile>` reference file, a different value can
  be designated for each slit, if desired.
  If no value is specified either by the user or in the
  :ref:`EXTRACT1D <extract1d_reffile>` reference file,
  no background smoothing is done.

``--bkg_fit``
  The type of fit to perform to the background data in each image column
  (or row, if the dispersion is vertical). There are four allowed values:
  "poly", "mean", and "median", and None (the default value). If left as None,
  the step will search the reference file for a value - if none is found,
  ``bkg_fit`` will be set to "poly". If set to "poly", the background
  values for each pixel within all background regions in a given column (or
  row) will be fit with a polynomial of order "bkg_order" (see below).
  Values of "mean" and "median" compute the simple average and median,
  respectively, of the background region values in each column (or row).
  This parameter can also be specified in the
  :ref:`EXTRACT1D <extract1d_reffile>` reference file. If
  specified in the reference file and given as an argument to the step by
  the user, the user-supplied value takes precedence.

``--bkg_order``
  The order of a polynomial function to be fit to the background
  regions.  The fit is done independently for each column (or row, if the
  dispersion is vertical) of the input image, and the fitted curve will be
  subtracted from the target data.  ``bkg_order`` = 0 (the minimum allowed
  value) means to fit a constant.  The user-supplied value (if any)
  overrides the value in the
  :ref:`EXTRACT1D <extract1d_reffile>` reference file.  If neither is specified, a
  value of 0 will be used. If a sufficient number of valid data points is
  unavailable to construct the polynomial fit, the fit will be forced to
  0 for that particular column (or row). If "bkg_fit" is not "poly", this
  parameter will be ignored.

``--bkg_sigma_clip``
  The background values will be sigma-clipped to remove outlier values from
  the determination of the background. The default value is a 3.0 sigma clip.

``--log_increment``
  Most log messages are suppressed while looping over integrations, i.e. when
  the input is a CubeModel or a 3-D SlitModel.  Messages will be logged while
  processing the first integration, but since they would be the same for
  every integration, most messages will only be written once.  However, since
  there can be hundreds or thousands of integrations, which can take a long
  time to process, it would be useful to log a message every now and then to
  let the user know that the step is still running.

  ``log_increment`` is an integer, with default value 50.  If it is greater
  than 0, an INFO message will be printed every ``log_increment``
  integrations, e.g. "... 150 integrations done".

``--subtract_background``
  This is a boolean flag to specify whether the background should be
  subtracted.  If None, the value in the :ref:`EXTRACT1D <extract1d_reffile>`
  reference file (if any) will be used.  If not None, this parameter overrides
  the value in the reference file.

``--use_source_posn``
  This is a boolean flag to specify whether the target and background extraction
  region locations specified in the :ref:`EXTRACT1D <extract1d_reffile>` reference
  file should be shifted
  to account for the expected position of the source. If None (the default),
  the step will make the decision of whether to use the source position based
  on the observing mode and the source type. The source position will only be
  used for point sources and for modes where the source could be located
  off-center due to things like nodding or dithering. If turned on, the position
  of the source is used in conjunction with the World Coordinate System (WCS) to
  compute the x/y source location. For NIRSpec non-IFU modes, the source position
  is determined from the ``source_xpos/source_ypos`` parameters. For MIRI LRS fixed slit,
  the dither offset is applied to the sky pointing location to determine source position.
  All other modes use ``targ_ra/targ_dec``. If this parameter is specified in the
  :ref:`EXTRACT1D <extract1d_reffile>` reference file, the reference file value will
  override any automatic settings based on exposure and source type. As always, a value
  given by the user as an argument to the step overrides all settings in the reference
  file or within the step code.

``--center_xy``
  A list of two integer values giving the desired x/y location for the center
  of the circular extraction aperture used for extracting spectra from 3-D
  IFU cubes. Ignored for non-IFU modes and non-point sources. Must be given in
  x,y order and in units of pixels along the x,y axes of the 3-D IFU cube, e.g.
  ``--center_xy="27,28"``. If given, the values override any position derived
  from the use of the ``use_source_posn`` argument. Default is None.

``--apply_apcorr``
  Switch to select whether or not to apply an APERTURE correction during the
  Extract1dStep processing. Default is ``True``

``--ifu_autocen``
  Switch to select whether or not to enable auto-centroiding of the extraction
  aperture for IFU point sources.  Auto-centroiding works by median collapsing the
  IFU cube across all wavelengths and using DAOStarFinder to locate the brightest
  source in the field. Default is ``False``.

``--ifu_rfcorr``
  Switch to select whether or not to run 1d residual fringe correction on the
  extracted 1d spectrum (MIRI MRS only). Default is ``False``.

``--ifu_set_srctype``
  A string that can be used to override the extraction method for the source_type
  given by the SRCTYPE keyword. The allowed values are POINT and EXTENDED. The SRCTYPE keyword is
  not changed, instead the extraction method used is based on this parameter setting. This is
  only allowed for MIRI MRS IFU data. 

``--ifu_rscale``
   A float designating the number of PSF FWHMs to use for the extraction radius. This
   is a MIRI MRS only paramenter. Values accepted are between 0.5 to 3.0. The default extraction
   size is set to 2 * FWHM. Values below 2 will result in a smaller
   radius, a value of 2 results in no change to radius and a value above 2 results in a larger
   extraction radius.  
   
``--soss_atoca``
  This is a NIRISS-SOSS algorithm-specific parameter; if True, use the ATOCA
  algorithm to treat order contamination. Default is ``True``.

``--soss_threshold``
  This is a NIRISS-SOSS algorithm-specific parameter; this sets the threshold
  value for a pixel to be included when modelling the spectral trace. The default
  value is 0.01.

``--soss_n_os``
  This is a NIRISS-SOSS algorithm-specific parameter; this is an integer that sets
  the oversampling factor of the underlying wavelength grid used when modeling the
  trace. The default value is 2.

``--soss_estimate``
  This is a NIRISS-SOSS algorithm-specific parameter; filename or SpecModel of the
  estimate of the target flux. The estimate must be a SpecModel with wavelength and
  flux values.

``--soss_wave_grid_in``
  This is a NIRISS-SOSS algorithm-specific parameter; filename or SossWaveGridModel
  containing the wavelength grid used by ATOCA to model each valid pixel of the
  detector. If not given, the grid is determined based on an estimate of the flux
  (soss_estimate), the relative tolerance (soss_rtol) required on each pixel model
  and the maximum grid size (soss_max_grid_size).

``--soss_wave_grid_out``
  This is a NIRISS-SOSS algorithm-specific parameter; filename to hold the wavelength
  grid calculated by ATOCA, stored in a SossWaveGridModel.

``--soss_rtol``
  This is a NIRISS-SOSS algorithm-specific parameter; the relative tolerance needed on a
  pixel model. It is used to determine the sampling of the soss_wave_grid when not
  directly given. Default value is 1.e-4.

``--soss_max_grid_size``
  This is a NIRISS-SOSS algorithm-specific parameter; the maximum grid size allowed. It is
  used when soss_wave_grid is not provided to make sure the computation time or the memory
  used stays reasonable. Default value is 20000.

``--soss_transform``
  This is a NIRISS-SOSS algorithm-specific parameter; this defines a rotation to
  apply to the reference files to match the observation. It should be specified as
  a list of three floats, with default values of None.

``--soss_tikfac``
  This is a NIRISS-SOSS algorithm-specific parameter; this is the regularization
  factor used in the SOSS extraction. If not specified, ATOCA will calculate a
  best-fit value for the Tikhonov factor.

``--soss_width``
  This is a NIRISS-SOSS algorithm-specific parameter; this specifies the aperture
  width used to extract the 1D spectrum from the decontaminated trace. The default
  value is 40.0 pixels.

``--soss_bad_pix``
  This is a NIRISS-SOSS algorithm-specific parameter; this parameter sets the method
  used to handle bad pixels. There are currently two options: "model" will replace
  the bad pixel values with a modeled value, while "masking" will omit those pixels
  from the spectrum. The default value is "model".

``--soss_modelname``
  This is a NIRISS-SOSS algorithm-specific parameter; if set, this will provide
  the optional ATOCA model output of traces and pixel weights, with the filename
  set by this parameter. By default this is set to None and this output is
  not provided.
