Configuration Guide

SMPy uses YAML configuration files to control all aspects of the mass mapping process.

Configuration Structure

The configuration file has four main sections:

general:      # Input/output paths, coordinate system, analysis settings
methods:      # Method-specific parameters (kaiser_squires, aperture_mass, ks_plus)
plotting:     # Visualization settings
snr:          # Signal-to-noise ratio calculation settings

Loading Configuration

Configuration files can be loaded using the Config class:

from smpy.config import Config

# Load from file
config = Config.from_file('my_config.yaml')

# Load defaults for a specific method
config = Config.from_defaults('kaiser_squires')

Parameter Reference

Note

The following tables describe all available configuration parameters. Required parameters are marked with an asterisk (*).

General Settings

Parameter	Type	Default	Description
input_path*	string	“”	Path to input FITS file containing shear catalog
input_hdu	integer	1	FITS extension number to read data from
output_directory	string	“.”	Directory to save output files
output_base_name	string	“smpy_output”	Base name for output files
coordinate_system*	string	“radec”	Coordinate system: ‘radec’ or ‘pixel’
method	string	“kaiser_squires”	Mass mapping method: ‘kaiser_squires’, ‘aperture_mass’, or ‘ks_plus’
g1_col	string	“g1”	Column name for first shear component
g2_col	string	“g2”	Column name for second shear component
weight_col	string/null	null	Column name for weights (null for unit weights)
mode	list	[‘E’]	Modes to compute: [‘E’], [‘B’], or [‘E’, ‘B’]
create_snr	boolean	false	Whether to create signal-to-noise ratio map
create_counts_map	boolean	false	Whether to create and save per-pixel object counts map as PNG
overlay_counts_map	boolean	false	Overlay per-pixel counts as text on the convergence map plots (uses the same grid used for mass maps).
save_fits	boolean	false	Whether to save maps as FITS files
print_timing	boolean	false	Whether to print timing information

RA/Dec Coordinate Settings

Under general.radec:

Parameter	Type	Default	Description
resolution*	float	0.4	Grid resolution in arcminutes (API: pixel_scale)
coord1	string	“ra”	RA column name in catalog
coord2	string	“dec”	Dec column name in catalog

Pixel Coordinate Settings

Under general.pixel:

Parameter	Type	Default	Description
downsample_factor*	integer	1	Grid reduction factor (API: downsample_factor)
coord1	string	“X_IMAGE”	X coordinate column name
coord2	string	“Y_IMAGE”	Y coordinate column name
pixel_axis_reference	string	“catalog”	Which axes to use for pixel plots: ‘catalog’ (input-pixel coordinates) or ‘map’ (map-pixel indices)

Validation Behavior and Error Messages

• Validation is strict only when general.input_path is set to a non-empty value. Loading defaults or inspecting configs without a real input path will not trigger hard errors.

• If coordinate_system='radec' and the required scale is missing, SMPy raises:

  Missing required parameter for coordinate_system='radec'. Provide 'pixel_scale' (API: pixel_scale=..., YAML: general.radec.resolution).

• If coordinate_system='pixel' and the required factor is missing, SMPy raises:

  Missing required parameter for coordinate_system='pixel'. Provide 'downsample_factor' (API: downsample_factor=..., YAML: general.pixel.downsample_factor).

Method-Specific Settings

Kaiser-Squires Settings

Under methods.kaiser_squires:

Parameter	Type	Default	Description
smoothing.type	string/null	“gaussian”	Smoothing type (‘gaussian’ or null)
smoothing.sigma	float	2.0	Gaussian smoothing scale in pixels

Aperture Mass Settings

Under methods.aperture_mass:

Parameter	Type	Default	Description
filter.type*	string	“schirmer”	Filter type: ‘schirmer’ or ‘schneider’
filter.scale*	float	60	Filter scale in pixels
filter.truncation	float	1.0	Truncation radius in units of scale
filter.l	integer	3	Polynomial order for Schneider filter

KS+ Settings

Under methods.ks_plus:

Parameter	Type	Default	Description
inpainting_iterations	integer	100	Number of iterations for inpainting algorithm
reduced_shear_iterations	integer	3	Number of iterations for reduced shear correction
extension_size	string/int	“double”	Field extension: ‘double’ or number of pixels
use_wavelet_constraints	boolean	true	Apply wavelet-based power spectrum constraints
constrain_B	boolean	false	Whether to apply wavelet power matching to B-modes as well (KS+ leaves B free by default)
threshold_schedule	string	“exp”	DCT threshold schedule; currently only ‘exp’ (exponential decay) is supported
threshold_tau	float/null	null	Decay constant in iterations for the exponential schedule. If null, defaults to one quarter of inpainting_iterations.
nscales	integer/null	null	Desired number of starlet scales (detail bands + coarse). If set, the value is clipped to a safe maximum derived from the image size and the B3–spline à trous kernel support. If null, the safe maximum is used automatically.
smoothing.type	string/null	“gaussian”	Smoothing type (‘gaussian’ or null)
smoothing.sigma	float	2.0	Gaussian smoothing scale in pixels

Plotting Settings

Parameter	Type	Default	Description
figsize	list	[12, 8]	Figure size in inches [width, height]
cmap	string	“viridis”	Matplotlib colormap name
fontsize	integer	15	Base font size for axis ticks, labels, title, and colorbar
xlabel	string/null	“auto”	X-axis label (‘auto’, null, or custom string)
ylabel	string/null	“auto”	Y-axis label (‘auto’, null, or custom string)
plot_title	string	“Mass Map”	Plot title (method name will be appended)
gridlines	boolean	true	Whether to show grid lines
vmin	float/null	null	Minimum value for color scale
vmax	float/null	null	Maximum value for color scale
threshold	float/null	null	Peak detection threshold
verbose	boolean/null	null	Print peak information
cluster_center	dict/string/null	null	Center position: null, ‘auto’, or a dictionary. For RA/Dec plots use {ra_center: float, dec_center: float}. For pixel plots use {x_center: float, y_center: float}.
axis_reference	string/null	null	For pixel plots only: overrides which axes are used for plotting (‘catalog’ or ‘map’). If null, defaults to the value of general.pixel.pixel_axis_reference.
scaling	dict/string/null	null	Color scaling configuration. If a string, treated as {type: <string>}.
xray_contours	dict/null	null	Optional DS9 .ctr contour overlay configuration. See x-ray contour settings below.

Scaling configuration

The plotting.scaling setting controls normalization of colormaps. Supported forms:

plotting:
  scaling:
    type: linear   # or 'power' or 'symlog'

Options by type:

• type: linear - Uses linear normalization with optional vmin/vmax.

• type: power - gamma: float (default 1.0). Example:

  plotting:
    scaling:
      type: power
      gamma: 0.5
  

• type: symlog - linthresh: float (default 0.1) - linscale: float (default 1.0) - Optional map-specific overrides under convergence and snr keys:

  plotting:
    scaling:
      type: symlog
      linthresh: 0.1
      linscale: 1.0
      snr:
        linthresh: 1.0
        linscale: 1.0
  

X-ray contour settings

Under plotting.xray_contours:

Parameter	Type	Default	Description
ctr_file	string/null	null	Path to DS9 contour file (.ctr). If null, contour overlay is disabled.
show_on_convergence	boolean	false	Whether to draw contours on convergence plots.
show_on_snr	boolean	false	Whether to draw contours on SNR plots.
color	string	“cyan”	Matplotlib line color for contours.
linewidth	float	0.8	Line width for contour traces.
alpha	float	0.7	Contour opacity in the range [0, 1].

SNR Settings

Parameter	Type	Default	Description
shuffle_type	string	“spatial”	Randomization type: ‘spatial’ or ‘orientation’
num_shuffles	integer	100	Number of random realizations
seed	int/string	0	Random seed (integer or ‘random’ for secure seed)
smoothing.type	string/null	“gaussian”	Smoothing type for SNR maps
smoothing.sigma	float	2.0	Smoothing scale for SNR maps
plot_title	string	“Signal-to-Noise Map”	Title for SNR plots

Example Configuration Files

Basic Kaiser-Squires Example

example_config.yaml

# YAML File for SMPy Configuration

#------General settings------#
general:
  # Input/Output paths
  input_path: "/Users/vassig/research/SMPy/examples/data/forecast_lum_annular.fits"
  input_hdu: 1  # FITS extension number to read data from
  output_directory: "/Users/vassig/research/SMPy/examples/outputs"
  output_base_name: "simulation_testing"

  # Coordinate system settings
  coordinate_system: "radec"  # 'radec' or 'pixel'
  radec:
    resolution: 0.4  # In arcminutes
    coord1: 'ra'    # RA column name
    coord2: 'dec'   # Dec column name
  pixel:
    downsample_factor: 170  # Grid reduction factor
    coord1: 'X_IMAGE_se'    # X column name
    coord2: 'Y_IMAGE_se'    # Y column name
    pixel_axis_reference: 'catalog'  # 'catalog' or 'map' for plotting axes
  
  # Data columns
  g1_col: 'g1_Rinv'
  g2_col: 'g2_Rinv'
  weight_col: 'weight'  # Set to null if no weights
  
  # Analysis settings
  method: "kaiser_squires"  # "kaiser_squires", "aperture_mass", or "ks_plus"
  create_snr: true  # Whether to create SNR map
  create_counts_map: false  # Whether to create and save per-pixel object counts map
  overlay_counts_map: false # Overlay per-pixel counts as text on convergence map plots
  mode: ['E']  # ['E'], ['B'], or ['E', 'B']
  print_timing: true  # Whether to print timing information for map creation
  save_fits: false  # Whether to save maps as FITS files

#------Method Settings------#
methods:
  # Kaiser-Squires settings
  kaiser_squires:
    smoothing:
      type: 'gaussian'  # 'gaussian' or null
      sigma: 2.0        # Smoothing scale

  # Aperture Mass settings
  aperture_mass:
    filter:
      type: 'schirmer'  # Type of aperture filter ('schirmer' or 'schneider')
      scale: 60        # Filter scale (pixels)
      truncation: 1.0  # Truncation radius

      # Schneider filter settings
      l: 3  # Polynomial order for Schneider filter
      
  # KS+ settings
  ks_plus:
    inpainting_iterations: 100  # Number of iterations for inpainting algorithm
    reduced_shear_iterations: 3 # Number of iterations for reduced shear correction
    nscales: null  # (int or null). If set, will be clipped to safe maximum.

    # Advanced settings
    extension_size: 'double'    # Size of field extension to reduce border effects ('double' or number of pixels)
    use_wavelet_constraints: true # Apply wavelet-based power spectrum constraints
    constrain_B: false            # By default, KS+ leaves B-modes unconstrained

    # DCT threshold schedule (stable exponential by default)
    threshold_schedule: 'exp'     # Only 'exp' is supported currently
    threshold_tau: null           # Decay constant in iterations (default: max_iter/4 when null)
    
    smoothing:
      type: 'gaussian'  # 'gaussian' or null
      sigma: 2.0        # Smoothing scale


#------Plot Settings------#
plotting:
  # Basic plotting
  figsize: [20, 10]
  fontsize: 15
  cmap: 'magma'
  xlabel: 'auto'  # 'auto', null, or custom string
  ylabel: 'auto'  # 'auto', null, or custom string
  plot_title: 'Mass Map'  # Method name will be appended
  gridlines: true
  
  # Advanced plotting
  vmax: null
  vmin: null
  threshold: 3    # Peak detection threshold
  verbose: true      # Print peak information
  cluster_center: null  # null, 'auto', or {ra/x_center: float, dec/y_center: float}
  xray_contours:
    ctr_file: null  # Path to DS9 .ctr file; null disables contour loading
    show_on_convergence: false  # Overlay contours on convergence plots
    show_on_snr: false  # Overlay contours on SNR plots
    color: 'cyan'  # Matplotlib line color
    linewidth: 0.8  # Line width for contour traces
    alpha: 0.7  # Opacity in [0, 1]

  # Scaling options
  scaling:
    type: 'linear'        # 'linear', 'power', or 'symlog'
    # Optional parameters (for nonlinear scaling)
    gamma: 2              # For power: Exponent for power law (<1 boosts faint, >1 boosts bright)
    percentile: null      # Set to null for regular or [n, m] to use nth and mth percentiles 

    # Map-specific symlog parameters (optional)
    convergence:          
      linthresh: 0.1      # For symlog: threshold for linear region around zero
      linscale: 1.0       # For symlog: scaling factor for linear region
    snr:                 
      linthresh: 5        # For symlog: threshold for linear region around zero
      linscale: 0.5       # For symlog: scaling factor for linear region

#------SNR Map Settings------#
snr:
  shuffle_type: 'spatial'  # 'spatial' or 'orientation'
  num_shuffles: 100       # Number of random realizations
  seed: 0                 # Random seed (int or 'random' for cryptographically secure seed)
  
  smoothing:
    type: 'gaussian'  # 'gaussian' or null (null not recommended for SNR)
    sigma: 2.0        # Smoothing scale
  
  # SNR plots will use the same settings as defined in plotting section above
  plot_title: 'Signal-to-Noise Map'  # Overrides plotting.plot_title for SNR maps

Full Featured Example

example_config_truth.yaml

# YAML File for SMPy Configuration

#------General settings------#
general:
  # Input/Output paths
  input_path: "/Users/vassig/research/SMPy/examples/data/forecast_lum_truth.fits"
  input_hdu: 1  # FITS extension number to read data from
  output_directory: "/Users/vassig/research/SMPy/examples/outputs"
  output_base_name: "truth_testing"

  # Coordinate system settings
  coordinate_system: "radec"  # 'radec' or 'pixel'
  radec:
    resolution: 0.4  # In arcminutes
    coord1: 'ra'    # RA column name
    coord2: 'dec'   # Dec column name
  pixel:
    downsample_factor: 170  # Grid reduction factor
    coord1: 'X_IMAGE_se'    # X column name
    coord2: 'Y_IMAGE_se'    # Y column name
    pixel_axis_reference: 'catalog'  # 'catalog' or 'map' for plotting axes
  
  # Data columns
  g1_col: 'nfw_g1'
  g2_col: 'nfw_g2'
  weight_col: null  # Set to null if no weights
  
  # Analysis settings
  method: "kaiser_squires"  # "kaiser_squires", "aperture_mass", or "ks_plus"
  create_snr: true  # Whether to create SNR map
  create_counts_map: false  # Whether to create and save per-pixel object counts map
  overlay_counts_map: false # Overlay per-pixel counts as text on convergence map plots
  mode: ['E']  # ['E'], ['B'], or ['E', 'B']
  print_timing: true  # Whether to print timing information for map creation
  save_fits: false  # Whether to save maps as FITS files

#------Method Settings------#
methods:
  # Kaiser-Squires settings
  kaiser_squires:
    smoothing:
      type: 'gaussian'  # 'gaussian' or null
      sigma: 2.0        # Smoothing scale

  # Aperture Mass settings
  aperture_mass:
    filter:
      type: 'schirmer'  # Type of aperture filter ('schirmer' or 'schneider')
      scale: 60        # Filter scale (pixels)
      truncation: 1.0  # Truncation radius

      # Schneider filter settings
      l: 3  # Polynomial order for Schneider filter

  # KS+ settings
  ks_plus:
    inpainting_iterations: 100  # Number of iterations for inpainting algorithm
    reduced_shear_iterations: 3 # Number of iterations for reduced shear correction
    nscales: null  # (int or null). If set, will be clipped to safe maximum.

    # Advanced settings
    extension_size: 'double'    # Size of field extension to reduce border effects ('double' or number of pixels)
    use_wavelet_constraints: true # Apply wavelet-based power spectrum constraints
    constrain_B: false            # By default, KS+ leaves B-modes unconstrained

    # DCT threshold schedule (stable exponential by default)
    threshold_schedule: 'exp'     # Only 'exp' is supported currently
    threshold_tau: null           # Decay constant in iterations (default: max_iter/4 when null)
    
    smoothing:
      type: 'gaussian'  # 'gaussian' or null
      sigma: 2.0        # Smoothing scale

#------Plot Settings------#
plotting:
  # Basic plotting
  figsize: [20, 10]
  fontsize: 15
  cmap: 'magma'
  xlabel: 'auto'  # 'auto', null, or custom string
  ylabel: 'auto'  # 'auto', null, or custom string
  plot_title: 'Mass Map'  # Method name will be appended
  gridlines: true
  
  # Advanced plotting
  vmax: null
  vmin: null
  threshold: null    # Peak detection threshold
  verbose: null      # Print peak information
  cluster_center: null  # null, 'auto', or {ra/x_center: float, dec/y_center: float}
  xray_contours:
    ctr_file: null  # Path to DS9 .ctr file; null disables contour loading
    show_on_convergence: false  # Overlay contours on convergence plots
    show_on_snr: false  # Overlay contours on SNR plots
    color: 'cyan'  # Matplotlib line color
    linewidth: 0.8  # Line width for contour traces
    alpha: 0.7  # Opacity in [0, 1]

  # Scaling options
  scaling:
    type: 'linear'        # 'linear', 'power', or 'symlog'
    # Optional parameters (for nonlinear scaling)
    gamma: 2              # For power: Exponent for power law (<1 boosts faint, >1 boosts bright)
    percentile: null      # Set to null for regular or [n, m] to use nth and mth percentiles 

    # Map-specific symlog parameters (optional)
    convergence:          
      linthresh: 0.1      # For symlog: threshold for linear region around zero
      linscale: 1.0       # For symlog: scaling factor for linear region
    snr:                 
      linthresh: 5        # For symlog: threshold for linear region around zero
      linscale: 0.5       # For symlog: scaling factor for linear region

#------SNR Map Settings------#
snr:
  shuffle_type: 'spatial'  # 'spatial' or 'orientation'
  num_shuffles: 100       # Number of random realizations
  seed: 0                 # Random seed (int or 'random' for cryptographically secure seed)
  
  smoothing:
    type: 'gaussian'  # 'gaussian' or null (null not recommended for SNR)
    sigma: 2.0        # Smoothing scale
  
  # SNR plots will use the same settings as defined in plotting section above
  plot_title: 'Signal-to-Noise Map'  # Overrides plotting.plot_title for SNR maps