SMART User Parameters

Setting User Parameters

The SMART User Parameters are a set of parameters used by SMART in processing data.
Default values are supplied for all of them, however indivdual users may change them if necessary.

The User Parameters window is invoked from the "Calibration" ==> "Set User Parameters" option on the Project Manager window. Initially it looks like this :

The top box displays :

"Initial User Parameter Selection" followed by one of :

1. "SYSTEM"
   If the SMART system defaults are being used.
2. "USER"
   If a non-default combination of parameters are being used.

Some parameters are digital, they have "either/or" selections. Click on the relevant buttons to set them.
Other parameters are analogue and one or more relevant values may be entered in the appropriate boxes.

|NOTE : |ALWAYS press "Enter" after changing one value before changing the next.
(IE. While the cursor is still in the text field you are changing.)
Failure to do this will result in SMART ignoring the change. |

If incorrect User Parameters are entered an error message will appear of the type :

Click "Return" to continue and enter a valid value.

Once the relevant user parameter values have been set exit by clicking on one of the buttons at the foot of the box.
Multiple selections of User Parameters may be selected at any one time.
New Parameters are set on exit from the window. The clickable buttons at the foot of the window determine what happens on exit :

Exit with this :	Sets the User Parameters to whatever selection has been made in the window.
Exit with SYS :	Sets the User Parameters to the system supplied values.

|Exit with initial user : |Sets the User Parameters to the most recent set of prior user selections.
If there are no prior user selections then the User Parameters are set to the system supplied values. |

Cancel :

Exits with no change at all, the User Parameters remain as they were.

Use of the User Parameters during extraction is documented by the following output FITS header keywords :

Keyword

Function

|S_PRM0 |Value = "Parm file setting"
Comment contains the string :
"sys" - System defaults for settable Parameters.
"user" - User selected values for settable Parameters. | |S_PRMxxx |xx = 1-999
Value = "Parameter used"
Comment contains the string : Name of Parameter and value. |

The User Parameters are listed below :

sm_fwhmfactor

Values : -1.0 or range 0.1 - 30.0

System Default : -1.0

To select the system default value (-1.0) click the "SYS DEFAULT -1.0" radio button.

To select any other value click the "Range 0.1 - 30.0" radio button.
Then enter the selected value in the input field next to the "Range 0.1 - 30.0" radio button.
The entered value must be in the range 0.1 - 30.0.
NOTE : When the system default is selected this field will display "-1.0".
Choosing a value outside the range 0.1 - 30.0 will display the error :

Click "Return" to continue and enter a value in the valid range.

If a value is selected for sm_fwhmfactor which is between 0.1 and 0.99999 a warning message will appear :

Click "OK" to continue. The entered value will be accepted and used by SMART for extraction.
Values between 0.1 and 0.99999 are valid.
However they can be the cause of artifacts in extracted data.
Please exercise caution when using sm_fwhmfactor values between 0.1 and 0.99999.

The sm_fwhmfactor is used during extraction. Its effect is different for different extraction types :

1. Full Extraction - No effect.
2. Gaussian Extraction :
   
   
   1. Set to -1.0 (default value) :
      The full width half maximum (fwhm) factor for Gaussian fitting of each order/wavelength during extraction is taken directly from the relevant module "psf-fov" file.
      These files are listed and can be viewed/set from the "wave" functional group in Calibration Selection.
   2. Set to any positive value (range 0.1 - 30.0) the following occurs :
      
      1. The full width half maximum (fwhm) factor for Gaussian fitting of each order/wavelength during extraction
         is taken from the "S_OXPXA" and "S_OXPXB" FITS Header Keywords.
         These are set automatically during automatic extraction or manually with the Manual Source Finder.
      2. The full width half maximum (fwhm) values from the "S_OXPXA" and "S_OXPXB" FITS header keywords are then multiplied by the value of "!sm_fwhmfactor".
      3. To use exactly the full width half maximum (fwhm) values from the "S_OXPXA" and "S_OXPXB" FITS header keywords set "!sm_fwhmfactor" equal to 1.0.
      4. NOTE for High Resoloution Data :
         If an attempt is made to extract high resoloution (SH or LH) data while "!sm_fwhmfactor" is set equal to -1.0 (negative)
         then on an order by order basis it will be overridden to 1.0 (positive) just for the high resoloution data.
         Using any value for sm_fwhmfactor in the range 0.1 - 30.0 will result in high resoloution data being extracted
         in exactly the same way as low resoloution data described above.

3. Tapered Column Extraction :
   
   
   1. Set to -1.0 : (default value)
      The width of the tapered extraction column of each order/wavelength during extraction is taken directly from the relevant module "psf-fov" file.
      These files are listed and can be viewed/set from the "wave" functional group in Calibration Selection.
   2. Set to any positive value (range 0.1 - 30.0) the following occurs :
      
      1. The width of the tapered extraction column of each order/wavelength during extraction is taken from the "S_OXPXA" and "S_OXPXB" FITS Header Keywords.
         These are set automatically during automatic extraction or manually with the Manual Source Finder.
      2. The full width half maximum (fwhm) values from the "S_OXPXA" and "S_OXPXB" FITS header keywords are then multiplied by the value of "!sm_fwhmfactor".
      3. To use exactly the full width half maximum (fwhm) values from the "S_OXPXA" and "S_OXPXB" FITS header keywords set "!sm_fwhmfactor" equal to 1.0.
      4. NOTE for High Resoloution Data :
         If an attempt is made to extract high resoloution (SH or LH) data while "!sm_fwhmfactor" is set equal to -1.0 (negative)
         then on an order by order basis it will be overridden to 1.0 (positive) just for the high resoloution data.
         Using any value for sm_fwhmfactor in the range 0.1 - 30.0 will result in high resoloution data being extracted
         in exactly the same way as low resoloution data described above.

4. Fixed Column Extractions :
   
   
   1. Set to -1.0 : (default value)
      The width of the fixed extraction column of each order/wavelength during extraction is taken directly from the relevant module "psf-fov" file.
      These files are listed and can be viewed/set from the "wave" functional group in Calibration Selection.
   2. Set to any positive value (range 0.1 - 30.0) the following occurs :
      
      1. The width of the fixed extraction column of each order/wavelength during extraction is taken from the "S_OXPXA" and "S_OXPXB" FITS Header Keywords.
         These are set automatically during automatic extraction or manually with the Manual Source Finder.
      2. The full width half maximum (fwhm) values from the "S_OXPXA" and "S_OXPXB" FITS header keywords are then multiplied by the value of "!sm_fwhmfactor".
      3. To use exactly the full width half maximum (fwhm) values from the "S_OXPXA" and "S_OXPXB" FITS header keywords set "!sm_fwhmfactor" equal to 1.0.
      4. NOTE for High Resoloution Data :
         If an attempt is made to extract high resoloution (SH or LH) data while "!sm_fwhmfactor" is set equal to -1.0 (negative)
         then on an order by order basis it will be overridden to 1.0 (positive) just for the high resoloution data.
         Using any value for sm_fwhmfactor in the range 0.1 - 30.0 will result in high resoloution data being extracted
         in exactly the same way as low resoloution data described above.

Use of the sm_fwhmfactor user parameter during extraction is documented by the following output FITS header keywords :

Keyword	Function
S_FWHM	Value of "!sm_fwhmfactor" at time of extraction.

|S_FWORxx |Value = "WARNING"
Comment = "Override : sm_fwhmfactor = 1.0 for order xx"

Denotes sm_fwhmfactor was overridden from -1.0 to 1.0
for the processing of order xx.
Done because sm_fwhmfactor = -1.0 requires SMART to use "psf-fov" files for extraction. There are no "psf-fov" files for high resoloution data.

xx = 11-20 (IE. Relevant order number, high resoloution ONLY.)

EG. Keyword "S_FWOR12" denotes sm_fwhmfactor = 1.0 override for order 12

NOTE : xx = 30 if SMART cannot ascertain relevant order number.
If so, comment = "Override : sm_fwhmfactor = 1.0 for unknown order". | |S_PRM0 |Value = "Parm file setting"
Comment contains the string :
"sys" - System defaults for settable Parameters.
"user" - User selected values for settable Parameters. | |S_PRMxxx |xx = 1-999
Value = "Parameter used"
Comment contains the string : Name of Parameter and value. |

sm_mergetype

Values :

• 0 - "RA/DEC"
• 1 - "RA/DEC/PA"
• 2 - "Name"
• 3 - "None"

System Default : "None"

This is used during extraction. If two or more BCD's (images) are selected for extraction together they are combined according to the value of sm_mergetype.
NOTE : When two or more BCD's are combined using any value other than "Name" the resultant dataset is given the default name of the first input BCD.

sm_posfactor

Values :

1. "decimal number, decimal number, decimal number". (RA value, DEC value, PA value - in degrees.)

System Default : "0.003, 0.003, 0.003"

This is used during extraction. It works with "sm_mergetype" (above).
Each of the three decimal values corresponds to the margin (in degrees) within which two similar but not identical values of RA, DEC and PA
will be regarded as the same and merged.
EG. If two images have RA values different by less than the first numeric value then they will be treated as the same
and the images will be merged for extraction if RA is set as a "merge" criteria in "sm_mergetype" above.

sm_fitfreeze

Values :

1. "Height"
2. "Center"
3. "Width"
4. "Constant (offset)"

System Default : "OFF, OFF, OFF, OFF"

This is used during extraction.
"sm_fitfreeze" allows the user to choose which fitting parameters to freeze as SMART fits a curve (EG. Gaussian) to the source.

0 = "ON" = Freeze
1 = "OFF" = Allow to vary with itteration

sm_source_plot

Values : "Show Source Finder Plot"

System Default : OFF

During automatic source finding for Tapered Column, Gaussian and Fixed Column extractions SMART attempts to find the source(s) in the data.
Setting "Show Source Finder Plot" to "ON" displays the source finding as step by step plots.
NOTE : With "Show Source Finder Plot" switched to "ON" any given extraction will run more slowly.
Set "Show Source Finder Plot" to "OFF" to reduce run time when running SMART scripts.
For more information about automatic source finding see : Automatic Source Finder

sm_ext_plot

Values : "Show Extraction Plot"

System Default : OFF

During Gaussian/Tapered Column/Fixed Column extraction SMART makes Gaussian/Tapered Column/Fixed Column fits to data.
Setting "Show Extraction Plot" to "ON" displays the Gaussian/Tapered Column/Fixed Column fitting as step by step plots.
NOTE : With "Show Extraction Plot" switched to "ON" any given extraction will run more slowly.
Set "Show Extraction Plot" to "OFF" to reduce run time when running SMART scripts.
For more information about extraction types see : Spectral Extraction Types

sm_eplane

Values :

• 0 - "SMART Constructed Error Plane"
• 1 - "SSC Error Plane"

System Default : "SSC Error Plane"

If 1-plane data is being used then the setting of this parameters is irrelevant.

A SMART internally generated error plane will always be used because there is nothing else available.
If 3-plane data is being used the results are dependent on the "sm_eplane" parameter setting :

• 0 - SMART Constructed Error Plane - an initial error plane with all error values equal to zero is used.
  When using SMART Image Operations SMART generated error plane values are the statistical variance of the corresponding flux values.
  For more information see : SMART Error and BMASK during Image Operations?.

• 1 - SSC Error Plane - the SSC supplied error (noise) plane is used.
  For more information see : SMART Error and BMASK during Image Operations?.

NOTE : For explanation of 1-plane and 3-plane type data in SMART see : Error and BMASK Plane Processing

BMASK Value Selection Display

Values : ON or OFF for each of 14 radio buttons

System Default : OFF for each

This is used during extraction. Each indivdual pixel can be included or ommited from extraction depending on its corresponding BMASK value.

Decimal	Power	Hex Value	Description
2	2^1	hex 2	Latent-image flag
4	2^2	hex 4	Digital saturation detected in sample(s) along ramp
8	2^3	hex 8	Radhit detection along ramp in sample(s) along ramp
16	2^4	hex 10	Non-linearity correction could not be computed in sample(s) along ramp
32	2^5	hex 20	Data bad (initial dmask; radhit checks this bit) in sample(s) along ramp
64	2^6	hex 40	Droop or rowdroop removed using questionable value in sample(s) along ramp
128	2^7	hex 80	Flat field applied using questionable value (flatap)
256	2^8	hex 100	Flat field could not be applied (flatap)
512	2^9	hex 200	Stray-light removal or crosstalk correction not applied
1024	2^10	hex 400	Saturated - beyond correctable non-linearity in sample(s) along ramp
2048	2^11	hex 800	Data missing in downlink in sample(s) along ramp
4096	2^12	hex 1000	Only one usable plane
8192	2^13	hex 2000	No usable planes
16384	2^14	hex 4000	Pixel masked in pmask

sm_ext_name

Values :

• 0 - "Target + module + nod"
• 1 - "Input File + Ext. Type + "spect""

System Default : "Target + module + nod"

This is used during extraction.
Once data is extracted by SMART it is presented in the IDEA Main Window and listed in the IDEA Stored Data Sets display.
The extracted data will be presented with one of of two possible naming conventions. The user can select either naming convention for their own use.
Both naming conventions are completely equal in all SMART processing :

• 0 - "Target + module + nod"

  EG. : HR_7341_SL2_1st
  
  NOTE :
  Using "Target + module + nod" can result in having two or more output extracted spectra with the same name.
  This can cause confusion.
  Further, if care is not taken when the data is written out of SMART it is possible that identically named data sets can overwrite each other.

• 1 - "Input File + Ext. Type + "spect""

  EG. : IRS_S0_16477184_0002_0000_3_bcd_Auto_Tapered_Column_spect
  
  NOTE :
  "Auto" designates automatic source finder extraction(s).
  When the Manual Source Finder is being used the extraction type in the file name will be of the form "...Manual_Gaussian_spec", etc.,
  where the extraction type is taken from the one set in the Manual Source Finder.
  The extraction type (automatic or manual) is taken from the one REQUESTED by the user when extraction commences.
  This is not necessarilly the extraction type SMART will use for one or more of the orders in the source being extracted.
  In some circumstances SMART will default from the requested extraction type to another extraction type.
  (See Spectral Extraction Automatic Defaulting - Source and Spectral Extraction Automatic Defaulting - Module for full details.)
  If this occurs it is possible to have a file named with one extraction type containg data extracted with a different extraction type.

NOTE :
Any dataset can be renamed within SMART at any time using the "Change Name" function of the IDEA Stored Data Sets display
or the "Rename File" function of the Dataset Manager.

sm_off_nod

Values : "Output "off nod" data"

System Default : OFF ("off-nod" extracted data is not produced.)

This is used during extraction.
When a low resoloution (SL or LL) dataset is extracted there is (usually) one slit of the SL or LL detector which does not have a (the) source visible in it.
This is called the "off-nod" slit.
SMART automatically extracts whatever happens to be in this "off-nod" slit (often background and/or noise).
Extracted "off-nod" data is then presented in the IDEA Main Window and listed in the IDEA Stored Data Sets display.

The extracted "off-nod" data has the same name as the extracted actual source data appended "_nod1" or "_nod2" depending which slit (1 or 2) was "off" the source at observation time.
Frequently the "off-nod" extraction is of limited use.
Setting "sm_off_nod" to "off" will prevent the outputting of the "off-nod" extracted data.

sm_cfo_auto

Values : Automatically Check For Overrides

System Default : ON (Check For Overrides is automatically performed.)

This is used during extraction.
Sometimes, during extraction, SMART will override user requesed extraction parameters and extract data in a different way.
For a full explanation of how and when this happens see Spectral Extraction Automatic Defaulting - Source and Spectral Extraction Automatic Defaulting - Module.
At all times extraction overrides can be displayed using the "CFO" Check For Overrides button on the IDEA Main Window.
Setting sm_cfo_auto to "on" will also perform a Check For Overrides during extraction.
If sm_cfo_auto is set to "on" and one or more overrides is applied during extraction the following message will appear :

Click "OK" to continue.
The Check For Overrides button can then be used to display a list of overrides.

sm_sky_sub_display

Values : Display sky subtraction during extraction

System Default : OFF (Sky subtracion is not displayed during extraction.)

SMART allows Sky Subtraction During Extraction.
However subtracting sky during extraction is not necessary for extractions to be performed.
Sky subtraction can be performed in other ways, for example with Image Operations.
If sm_sky_sub_display is set to "OFF" then no sky subtraction of any sort whatsoever is performed during extraction.
If sm_sky_sub_display is set to "ON" then during extraction the "Sky Subtraction" window appears
and different types of sky subtraction may be performed on some or all of the data being extracted.
For a full explanation of the operations possilbe see Sky Subtraction During Extraction.