Parameter Configuration

SPXQuery uses a flexible parameter system that separates basic pipeline parameters from advanced configuration options.

Parameter Organization

Parameters are organized into two categories:

Basic Parameters

These are commonly used pipeline parameters passed directly to functions:

  • Source parameters: ra, dec, source_name

  • Pipeline control: output_dir, bands

  • Download control: cutout_size, max_download_workers, skip_existing_downloads

Example:

from spxquery.core.pipeline import run_pipeline

run_pipeline(
    ra=213.94,
    dec=11.50,
    output_dir="output",
    cutout_size="200px"
)

Advanced Parameters

These are less frequently modified parameters organized into three configuration classes:

  1. PhotometryConfig - Aperture photometry and background estimation

  2. VisualizationConfig - Plot appearance and layout

  3. DownloadConfig - HTTP download behavior

Advanced parameters are configured via YAML files (see YAML Configuration below).

Three-Tier Priority System

SPXQuery uses a priority hierarchy to determine parameter values:

Priority Order (Highest → Lowest)

  1. Explicit function arguments - Parameters passed directly

  2. YAML configuration file - Loaded via advanced_params_file

  3. Built-in defaults - Default values in the code

Example

# Scenario 1: Use defaults
config = QueryConfig(source=source, output_dir="output")
# Result: Uses all built-in defaults

# Scenario 2: Override with YAML
config = QueryConfig(
    source=source,
    output_dir="output",
    advanced_params_file="my_params.yaml"  # Contains custom values
)
# Result: Uses YAML values, falls back to defaults if not specified

# Scenario 3: Explicit override
config = QueryConfig(
    source=source,
    output_dir="output",
    advanced_params_file="my_params.yaml",
    aperture_diameter=5.0  # Explicit override
)
# Result: Uses aperture_diameter=5.0, ignores YAML value for this parameter

Configuration Classes

PhotometryConfig

Controls aperture photometry and background estimation.

Key parameters:

Parameter

Default

Description

aperture_method

“fixed”

Aperture sizing method: ‘fixed’ (constant diameter) or ‘fwhm’ (adaptive based on PSF)

aperture_diameter

3.0

Aperture diameter in pixels (fixed method) OR fallback value (fwhm method)

fwhm_multiplier

2.5

Multiplier for FWHM-based apertures (aperture = FWHM × multiplier)

background_method

“annulus”

Background estimation: ‘annulus’ (ring around source) or ‘window’ (rectangular region)

annulus_inner_offset

1.414

Gap between aperture and background annulus (in aperture radii)

min_annulus_area

10

Minimum usable pixels in background annulus

window_size

50

Window size for window background (int for square, tuple for rectangular)

bg_sigma_clip_sigma

3.0

Sigma threshold for background sigma clipping

bg_sigma_clip_maxiters

3

Maximum iterations for sigma clipping

subtract_zodi

True

Subtract zodiacal background from IMAGE extension

pixel_scale_fallback

6.2

Fallback pixel scale (arcsec/pixel) when WCS unavailable

max_annulus_attempts

5

Maximum attempts to find valid background annulus

annulus_expansion_step

0.5

Annulus expansion step (in aperture radii)

When to customize:

  • FWHM apertures: Set aperture_method='fwhm' for adaptive sizing based on seeing conditions

  • Crowded fields: Use background_method='window' for better background estimation

  • Non-standard geometries: Adjust annulus sizing or window dimensions

  • Stricter/looser background: Modify sigma clipping parameters

VisualizationConfig

Controls plot appearance, layout, and quality filtering.

Key parameters:

Parameter

Default

Description

sigma_threshold

5.0

Minimum SNR (flux/flux_err) for “good” measurements in plots

use_magnitude

False

Plot magnitudes (True) or fluxes (False)

show_errorbars

True

Show error bars on plots

wavelength_cmap

“rainbow”

Colormap for wavelength coding

date_cmap

“viridis”

Colormap for observation date coding

figsize

(10, 8)

Figure dimensions (width, height) in inches

dpi

150

Resolution for saved figures

marker_size_good

1.5

Marker size for good measurements

marker_size_rejected

2.0

Marker size for rejected measurements

marker_alpha

0.9

Marker transparency (0-1)

errorbar_alpha

0.2

Error bar transparency (0-1)

When to customize:

  • Quality filtering: Adjust sigma_threshold for stricter/looser quality control in plots

  • Publication requirements: Modify DPI, figure size, or colormap choices

  • Color vision accessibility: Use alternative colormaps (e.g., viridis, cividis)

  • Visual emphasis: Adjust marker sizes and transparency

DownloadConfig

Controls HTTP download behavior.

Key parameters:

Parameter

Default

Description

chunk_size

8192

Download chunk size (bytes)

timeout

300

HTTP timeout (seconds)

max_retries

3

Maximum retry attempts on failure

retry_delay

5

Delay between retries (seconds)

user_agent

“SPXQuery/0.2.0”

HTTP User-Agent header

When to customize:

  • Slow networks (increase timeout, reduce chunk size)

  • Unreliable connections (increase retries/delay)

  • Rate limiting issues (adjust retry delay)

YAML Configuration

Export Default Template

Create a YAML template with all default values:

from spxquery.utils.params import export_default_parameters

params_file = export_default_parameters(
    output_dir="config",
    filename="my_params.yaml"
)

This creates a file like:

# Photometry configuration
photometry:
  aperture_method: fixed
  aperture_diameter: 3.0
  fwhm_multiplier: 2.5
  background_method: annulus
  annulus_inner_offset: 1.414
  min_annulus_area: 10
  window_size: 50
  bg_sigma_clip_sigma: 3.0
  bg_sigma_clip_maxiters: 3
  subtract_zodi: true
  # ... additional parameters

# Visualization configuration
visualization:
  sigma_threshold: 5.0
  use_magnitude: false
  show_errorbars: true
  wavelength_cmap: rainbow
  date_cmap: viridis
  figsize: [10, 8]
  dpi: 150
  # ... additional parameters

# Download configuration
download:
  chunk_size: 8192
  timeout: 300
  max_retries: 3
  # ... additional parameters

Customize Parameters

Edit the YAML file to change specific values:

# Custom photometry settings
photometry:
  aperture_method: fwhm  # Use adaptive FWHM-based apertures
  fwhm_multiplier: 3.0   # Larger apertures (3×FWHM)
  background_method: window  # Use window instead of annulus
  window_size: 100       # 100×100 pixel window

# Custom visualization settings
visualization:
  sigma_threshold: 3.0   # More lenient quality threshold
  dpi: 300               # Higher resolution for publication
  figsize: [7.5, 6]      # Custom figure size
  wavelength_cmap: plasma

You only need to specify parameters you want to change - omitted parameters use defaults.

Load Custom Configuration

Use the YAML file in your pipeline:

Method 1: run_pipeline() function

from spxquery.core.pipeline import run_pipeline

run_pipeline(
    ra=213.94,
    dec=11.50,
    output_dir="output",
    advanced_params_file="config/my_params.yaml"
)

Method 2: QueryConfig class

from spxquery import SPXQueryPipeline, Source, QueryConfig

source = Source(ra=213.94, dec=11.50, name="my_source")
config = QueryConfig(
    source=source,
    output_dir="output",
    advanced_params_file="config/my_params.yaml"
)

pipeline = SPXQueryPipeline(config)
pipeline.run_full_pipeline()

Parameter Validation

SPXQuery validates parameters at configuration time:

  • Type checking: Parameters must match expected types

  • Range validation: Values must be within valid ranges (e.g., DPI > 0)

  • Dependency checking: Related parameters are checked for consistency

Invalid configurations raise ValueError with descriptive error messages.

See Also