Visualization Modules

Publication-quality plotting with quality control filtering.

Visualization functions for SPHEREx time-domain data.

spxquery.visualization.plots.calculate_smart_ylimits(y_values: List[float], percentile_range: Tuple[float, float] = (1.0, 99.0), padding_fraction: float = 0.1) → Tuple[float, float]

Calculate smart y-axis limits based on percentiles to exclude extreme outliers.

Parameters:

• y_values (List[float]) – Y-axis values to analyze

• percentile_range (Tuple[float, float]) – Lower and upper percentiles to use for limits (default: 1st to 99th)

• padding_fraction (float) – Fraction of range to add as padding (default: 0.1 = 10%)

Returns:

(ymin, ymax) limits for y-axis

Return type:

Tuple[float, float]

spxquery.visualization.plots.apply_sigma_clipping(photometry_results: List[PhotometryResult], sigma: float = 3.0, maxiters: int = 10) → List[PhotometryResult]

Apply sigma clipping to remove outliers based on flux values.

Parameters:

• photometry_results (List[PhotometryResult]) – Input photometry measurements

• sigma (float) – Number of standard deviations to use for clipping

• maxiters (int) – Maximum number of clipping iterations

Returns:

Filtered photometry results with outliers removed

Return type:

List[PhotometryResult]

spxquery.visualization.plots.create_spectrum_plot(photometry_results: List[PhotometryResult], ax: Axes | None = None, apply_clipping: bool = True, sigma: float = 3.0, apply_quality_filters: bool = True, sigma_threshold: float = 5.0, bad_flags_mask: int | None = None, use_magnitude: bool = False, show_errorbars: bool = True) → Axes

Create spectrum plot (wavelength vs flux), color-coded by observation date.

Parameters:

• photometry_results (List[PhotometryResult]) – Photometry measurements

• ax (plt.Axes, optional) – Axes to plot on. If None, current axes are used.

• apply_clipping (bool) – Whether to apply sigma clipping to remove outliers

• sigma (float) – Number of standard deviations for sigma clipping

• apply_quality_filters (bool) – Whether to classify points as good/rejected based on QC filters

• sigma_threshold (float) – Minimum SNR (flux/flux_err) for quality control

• bad_flags_mask (int, optional) – Integer mask with bad flag bits set (created by create_flag_mask)

• use_magnitude (bool) – If True, plot AB magnitude instead of flux (default: False)

• show_errorbars (bool) – If True, show errorbars (default: True)

Returns:

Axes with spectrum plot

Return type:

plt.Axes

spxquery.visualization.plots.create_lightcurve_plot(photometry_results: List[PhotometryResult], ax: Axes | None = None, apply_clipping: bool = True, sigma: float = 3.0, apply_quality_filters: bool = True, sigma_threshold: float = 5.0, bad_flags_mask: int | None = None, use_magnitude: bool = False, show_errorbars: bool = True) → Axes

Create light curve plot (time vs flux) color-coded by wavelength.

Parameters:

• photometry_results (List[PhotometryResult]) – Photometry measurements

• ax (plt.Axes, optional) – Axes to plot on. If None, current axes are used.

• apply_clipping (bool) – Whether to apply sigma clipping to remove outliers

• sigma (float) – Number of standard deviations for sigma clipping

• apply_quality_filters (bool) – Whether to classify points as good/rejected based on QC filters

• sigma_threshold (float) – Minimum SNR (flux/flux_err) for quality control

• bad_flags_mask (int, optional) – Integer mask with bad flag bits set (created by create_flag_mask)

• use_magnitude (bool) – If True, plot AB magnitude instead of flux (default: False)

• show_errorbars (bool) – If True, show errorbars (default: True)

Returns:

Axes with light curve plot

Return type:

plt.Axes

spxquery.visualization.plots.create_combined_plot(photometry_results: List[PhotometryResult], output_path: Path | None = None, figsize: Tuple[float, float] | None = None, apply_clipping: bool = True, sigma: float | None = None, apply_quality_filters: bool = True, sigma_threshold: float = 5.0, bad_flags: List[int] | None = None, use_magnitude: bool = False, show_errorbars: bool = True, visualization_config: VisualizationConfig | None = None) → Figure

Create combined plot with spectrum and light curve.

Quality control filters classify points as good or rejected: - Good points: plotted normally (filled circles) - Rejected points: plotted as small gray crosses - All points appear in the plot and are saved in CSV output

Parameters:

• photometry_results (List[PhotometryResult]) – Photometry measurements (all points included)

• output_path (Path, optional) – Path to save figure. If None, figure is not saved.

• figsize (Tuple[float, float], optional) – Figure size in inches (overrides visualization_config if provided)

• apply_clipping (bool) – Whether to apply sigma clipping to remove outliers

• sigma (float, optional) – Number of standard deviations for sigma clipping (overrides visualization_config if provided)

• apply_quality_filters (bool) – Whether to apply quality control filters (SNR and flags)

• sigma_threshold (float) – Minimum SNR (flux/flux_err) for quality control (default: 5.0)

• bad_flags (List[int], optional) – List of bad flag bit positions to reject Default: [0, 1, 2, 6, 7, 9, 10, 11, 14, 15, 17, 19]

• use_magnitude (bool) – If True, plot AB magnitude instead of flux (default: False)

• show_errorbars (bool) – If True, show errorbars (default: True)

• visualization_config (VisualizationConfig, optional) – Advanced visualization configuration. If None, uses defaults.

Returns:

Matplotlib figure with both plots

Return type:

Figure

Notes

Priority: explicit parameters > visualization_config > defaults

spxquery.visualization.plots.plot_summary_statistics(photometry_results: List[PhotometryResult], output_path: Path | None = None) → Figure

Create summary statistics plots.

Parameters:

• photometry_results (List[PhotometryResult]) – Photometry measurements

• output_path (Path, optional) – Path to save figure

Returns:

Figure with summary plots

Return type:

Figure