The STIPS Configuration File ============================ .. note:: Although the configuration file is the recommended general way of setting STIPS options, it is also possible to set many of these options with dictionary keys or by specifying keyword arguments to classes or functions at runtime. Configuration File Format ------------------------- STIPS configuration files are formatted as `YAML files `_. The configuration files included in the internal STIPS data directory (or the downloadable ``stips_data`` directory) include comments describing how the keywords are used, and what values they can have. This commentary is optional. Configuration File Strategy --------------------------- When the ``stips.utilities.SelectParameter()`` function is used to look for a configuration parameter, STIPS follows the following strategy to find that parameter (and will take whichever value it finds first). As such, if the user wishes to override only some STIPS configuration values, they can put a configuration file with only those values specified into the directory where STIPS is being run. Any other configuration will fall back to other files. The STIPS configuration hierarchy is: #. Keyword arguments provided when creating a STIPS class. #. Any configuration file (or directory containing a file named ``stips_config.yaml``) provided directly to ``stips.utilities.SelectParameter()``. #. A file named ``stips_config.yaml`` in the same directory as STIPS is being run. #. A file (or a directory containing a file named ``stips_config.yaml``) named in the environment variable ``stips_config``. #. A file named ``stips_config.yaml`` located in the ``stips_data`` directory. #. The ``stips_config.yaml`` file in the internal STIPS data directory. .. note:: The internal ``stips_config.yaml`` file should not be edited, as it contains default values that should not be changed directly. The appropriate way for a user to change the STIPS configuration is to use any of methods 1-5 above. General Configuration Keywords ------------------------------ input_location (default *$CWD*) If classes are given an input file name which is not a fully-qualified path, they will look for that file in this directory. ``$CWD`` is a special value that is replaced at runtime with the directory from which STIPS is being run. If used as a keyword argument, ``cat_path`` can be used instead of ``input_location`` as a variable name for historical reasons. output_location (default *$CWD$*) If classes produce any output files, they will be placed in this directory. ``$CWD`` is a special value that is replaced at runtime with the directory from which STIPS is being run. If used as a keyword argument, ``out_path`` can be used instead of ``output_location`` for historical reasons. catalogue_type (default *fits*) This is the format in which catalogue files will be written, and from which they will be read by default. Currently the only supported values for this keyword are ``ascii.ipac`` and ``fits``. If used as a keyword argument, ``cat_type`` can be used instead of ``catalogue_type`` for historical reasons. log_level (default *INFO*) This is the default log level for the internal STIPS logger. Any value that can be obtained from the logging module using ``getattr(logging, VALUE)`` and then passed to ``logging.logger.setLevel()`` can be used here. random_seed (default *1234*) The seed value to be passed to ``numpy.random.RandomState(seed=seed)``. A value of "-1" means that seed will be treated as None (and so will use /dev/urandom or the system clock). If used as a keyword argument, ``seed`` can be used instead of ``random_seed`` for historical reasons. Observation Keywords -------------------- observation_default_background (default *0.0*) The default sky background in counts/s/detector pixel. Currently this keyword can be set to: * any integer or floating point value, in which case that value will be used directly. The default value is 0. * any of the string values 'none', 'low', 'avg', or 'high'. In this case, 'none' is always treated as zero, and for any other keyword if the value is defined for the instrument/detector selected, that value will be used. If no such value can be found, the background will be set to 0. * the string value 'pandeia', which will use Pandeia to calculate the total background for the active filter. Pandeia calculates backgrounds in electrons/s, so STIPS converts the value to counts/s for consistency. The conversion assumes a quantum yield of 1, where photons are equivalent to electrons. Outside of a configuration file (e.g., as a keyword argument to a STIPS Python object), ``background`` should be used instead of ``observation_default_background`` for historical reasons. observation_distortion_enable (default *false*) Whether co-ordinate distortion information should be included in the observation. Note that this is not yet available for Roman. If used as a keyword argument, ``distortion`` can be used instead of ``observation_distortion_enable`` for historical reasons. PSF Convolution Configuration ----------------------------- psf_cache_enable (default *true*) Whether PSF grids created by STPSF should be cached after creation for potential re-use. psf_cache_location (default *$DATA*) Where PSF grids should be cached if caching in enabled. The special value ``$DATA`` indicates the stips_data directory. psf_cache_directory (default *psf_cache*) The name of the directory inside ``psf_cache_location`` where PSF grids should be cached (again, if caching is enabled). psf_convolution_max_size (default *8192*) The maximum data array size to create for convolutions. Note that this value should be a power of two. If it isn't, the largest power of two that is less than ``psf_convolution_max_size`` will be used. If used as a keyword argument, ``convolve_size`` can be used instead of ``psf_convolution_max_size`` for historical reasons. The side length of the PSF grid created by STIPS was formerly editable with a PSF convolution configuration option called ``psf_grid_size``. **It is now fixed at 3.** Error Residual Configuration ---------------------------- residual_convolve_psf (default *true*) Whether PSF convolution should be performed when adding error. If used as a keyword argument, ``convolve`` may be used instead of ``residual_convolve_psf`` for historical reasons. residual_poisson (default *true*) Whether Poisson noise should be added when adding error. residual_readnoise (default *true*) Whether Readnoise should be added when adding error. residual_flat (default *true*) Whether a flatfield removal residual should be added when adding error. residual_dark (default *true*) Whether a dark current removal residual should be added when adding error. residual_cosmic (default *true*) Whether cosmic ray removal residuals should be added when adding error.