Configuration Reference

pyKOSMOS++ uses YAML configuration files to customize pipeline behavior. This page documents all available configuration parameters.

Configuration File Format

Configuration files use YAML syntax with nested sections:

# config/custom_config.yaml
detector:
  gain: 1.4
  readnoise: 3.7

wavelength:
  max_order: 7

# Comments supported

Loading Configuration

From command line:

kosmos-reduce --input-dir data/ --output-dir reduced/ --config custom_config.yaml

From Python:

from pykosmospp.io.config import PipelineConfig
config = PipelineConfig.from_yaml('custom_config.yaml')

Default Configuration

If no custom config is provided, the pipeline uses config/kosmos_defaults.yaml with parameters optimized for the APO-KOSMOS spectrograph.

Parameter Reference

Detector Section

Physical detector properties and data characteristics.

detector.gain (float)

CCD gain in electrons per ADU.

Default: 1.4
Units: e⁻/ADU
Range: 0.5 - 5.0
Notes: Check instrument manual for your detector

detector.readnoise (float)

CCD read noise in electrons.

Default: 3.7
Units: e⁻
Range: 1.0 - 10.0
Notes: From detector spec sheet

detector.saturate (int)

Saturation level in ADU.

Default: 58982
Units: ADU
Range: 10000 - 65535
Notes: Pixels above this value are flagged

detector.dark_current (float, optional)

Dark current in electrons per pixel per second.

Default: 0.0 (negligible for KOSMOS)
Units: e⁻/pixel/s

Calibration Section

Parameters for master calibration creation.

calibration.method (string)

Combination method for bias and flat frames.

Default: median
Options: median, mean
Notes: Median is robust to outliers, mean is faster

calibration.sigma_clip (float)

Sigma-clipping threshold for combining frames.

Default: 3.0
Units: sigma
Range: 2.0 - 5.0

calibration.min_frames (dict)

Minimum number of frames required for each type.

calibration:
  min_frames:
    bias: 3
    flat: 3
    arc: 1

Default: {bias: 3, flat: 3, arc: 1}

calibration.flat_norm_region (list, optional)

Spatial region [start, end] for flat normalization.

Default: null (uses central 50%)
Units: pixels
Example: [200, 1800]

Wavelength Section

Wavelength calibration parameters.

wavelength.max_order (int)

Maximum polynomial order for wavelength fit.

Default: 7
Range: 3 - 10
Notes: Higher orders risk overfitting

wavelength.initial_dispersion (float)

Approximate dispersion in Angstroms per pixel.

Default: 1.0
Units: Å/pixel
Range: 0.1 - 10.0
Notes: Used for initial line matching

wavelength.wavelength_range (list)

Wavelength range [min, max] to search for arc lines.

Default: [3500, 7500] (KOSMOS range)
Units: Angstroms
Example: [4000, 7000] for limited range

wavelength.rms_threshold (float)

Maximum acceptable RMS residual for wavelength solution.

Default: 0.1
Units: Angstroms
Range: 0.01 - 0.5
Notes: Solutions with RMS > threshold are flagged

wavelength.min_lines (int)

Minimum identified arc lines required for fit.

Default: 20
Range: 10 - 100
Notes: More lines improve robustness

wavelength.match_tolerance (float)

Tolerance for matching detected lines to catalog.

Default: 2.0
Units: Angstroms
Range: 0.5 - 5.0

wavelength.sigma_clip (float)

Sigma-clipping threshold for iterative wavelength fit.

Default: 3.0
Units: sigma
Range: 2.0 - 5.0

wavelength.max_iterations (int)

Maximum sigma-clipping iterations.

Default: 5
Range: 1 - 10

Trace Detection Section

Parameters for spectral trace identification.

trace_detection.expected_fwhm (float)

Expected trace FWHM in spatial direction.

Default: 4.0
Units: pixels
Range: 2.0 - 20.0
Notes: Depends on seeing and slit width

trace_detection.min_snr (float)

Minimum signal-to-noise ratio for trace detection.

Default: 3.0
Range: 1.0 - 10.0
Notes: Lower values detect fainter traces but increase false positives

trace_detection.min_separation (int)

Minimum pixel separation between distinct traces.

Default: 20
Units: pixels
Range: 5 - 100
Notes: Prevents duplicate detections

trace_detection.detection_threshold (float)

Threshold for arc line detection in cross-correlation.

Default: 5.0
Units: sigma above background
Range: 3.0 - 10.0

Extraction Section

Spectral extraction parameters.

extraction.method (string)

Extraction method.

Default: optimal
Options: optimal, boxcar
Notes: Optimal uses Horne 1986 variance weighting

extraction.aperture_width (int)

Extraction aperture width in spatial direction.

Default: 10
Units: pixels
Range: 5 - 50
Notes: Should encompass trace profile

extraction.sky_buffer (int)

Distance from trace center to start sky estimation.

Default: 30
Units: pixels
Range: 10 - 100
Notes: Larger values avoid contamination from trace wings

extraction.sky_width (int, optional)

Width of sky region on each side of trace.

Default: 50 pixels
Units: pixels
Range: 20 - 200

extraction.profile_type (string)

Spatial profile model.

Default: Gaussian
Options: Gaussian, Moffat, empirical

Cosmic Ray Section

Cosmic ray detection parameters (L.A.Cosmic algorithm).

cosmic_ray.enabled (bool)

Enable cosmic ray detection and cleaning.

Default: true

cosmic_ray.sigma_clip (float)

Detection threshold in sigma.

Default: 5.0
Range: 3.0 - 10.0

cosmic_ray.contrast (float)

Contrast threshold for neighbor comparison.

Default: 3.0
Range: 1.0 - 5.0

cosmic_ray.max_iterations (int)

Maximum cleaning iterations.

Default: 5
Range: 1 - 10

Quality Section

Quality assessment thresholds.

quality.min_snr (float)

Minimum acceptable median SNR for “Good” grade.

Default: 5.0
Range: 1.0 - 20.0

quality.excellent_snr (float)

Minimum SNR for “Excellent” grade.

Default: 20.0

quality.max_wavelength_rms (float)

Maximum wavelength RMS for “Good” grade.

Default: 0.2
Units: Angstroms

quality.excellent_wavelength_rms (float)

Maximum wavelength RMS for “Excellent” grade.

Default: 0.1
Units: Angstroms

quality.max_bad_pixel_fraction (float)

Maximum fraction of bad pixels in flat field.

Default: 0.05 (5%)
Range: 0.0 - 0.2

quality.max_cosmic_ray_fraction (float)

Maximum fraction of pixels flagged as cosmic rays.

Default: 0.01 (1%)
Range: 0.0 - 0.1

Binning Section (Optional)

Spatial and spectral binning options.

binning.spatial.enabled (bool)

Enable spatial binning before extraction.

Default: false
Notes: Useful for faint sources to boost SNR

binning.spatial.factor (int)

Spatial binning factor.

Default: 2
Range: 2 - 8

binning.spectral.enabled (bool)

Enable spectral binning after extraction.

Default: false

binning.spectral.width_angstrom (float)

Spectral bin width.

Default: 2.0
Units: Angstroms

AB Subtraction Section (Optional)

Parameters for nod-and-shuffle observations.

ab_subtraction.enabled (bool)

Enable AB pair subtraction for sky removal.

Default: false

ab_subtraction.nod_tolerance (float)

Maximum time difference to match A/B pairs.

Default: 600.0 (10 minutes)
Units: seconds

ab_subtraction.max_iterations (int)

Maximum iterations for iterative sky estimation.

Default: 5

Example Configurations

Faint Galaxy Configuration

Optimized for low surface brightness extended sources:

# faint_galaxy_config.yaml
trace_detection:
  expected_fwhm: 5.0      # Slightly extended seeing
  min_snr: 2.0            # Lower threshold

extraction:
  aperture_width: 15      # Wider to capture all flux
  sky_buffer: 40          # Extra buffer from wings

binning:
  spatial:
    enabled: true
    factor: 2             # 2x2 spatial binning

quality:
  min_snr: 3.0            # Accept lower SNR

High-Resolution Wavelength Config

For precision wavelength calibration:

# precision_wavelength_config.yaml
wavelength:
  max_order: 9            # Higher order fit
  rms_threshold: 0.05     # Stricter RMS requirement
  min_lines: 40           # More lines for robustness
  sigma_clip: 2.5         # Tighter outlier rejection

quality:
  excellent_wavelength_rms: 0.05
  max_wavelength_rms: 0.1

Multi-Slit Configuration

For multi-object spectroscopy:

# multi_slit_config.yaml
trace_detection:
  min_separation: 50      # Objects well-separated
  min_snr: 3.0

extraction:
  aperture_width: 8       # Narrower for slit width
  sky_buffer: 20          # Sky regions between slits

Configuration Validation

The pipeline validates configuration on load:

from pykosmospp.io.config import PipelineConfig

try:
    config = PipelineConfig.from_yaml('config.yaml')
    config.validate()  # Checks for required sections and valid ranges
except ValueError as e:
    print(f"Invalid configuration: {e}")

Validation checks:

All required sections present
Numeric values in valid ranges
String options match allowed values
No conflicting parameters