VISION User Tutorial

Welcome to VISION (Versatile Integrated Simulator for Inquiry into Observational Needs). This tutorial will guide you through the full workflow: from parameter input to result analysis and further data usage.

1. Overview

VISION provides two independent modules:

Mass Completeness: Estimates the stellar mass completeness limit of a given survey as a function of redshift.
Photo-z Performance: Predicts photometric redshift accuracy (σ_NMAD, bias, outlier fraction) for a chosen filter set and observing strategy.

Both modules generate mock catalogs (FITS), diagnostic plots, and simulated sky images.

2. Input Parameters

2.1 Common Parameters (both modules)

RA range / Dec range: Right Ascension and Declination limits of the target field (in degrees). Used to define the survey geometry.
Selection band: The band used to define the limiting magnitude (e.g., csst-r, jwst-f444w). Must be chosen from the right‑hand filter list.
Maglim: Limiting magnitude (AB) in the selection band. Galaxies fainter than this are not generated.
SNR band: The band used for signal‑to‑noise ratio cut (e.g., the same as selection band or another).
SNR threshold: Sources with SNR below this value are removed from the sample.
Observing parameters file (params.txt): A text file containing the detector and exposure parameters for the SNR band (and for all bands in the photo‑z module). Format described below.

2.2 Mass Completeness‑specific parameters

Completeness limits (%): Desired completeness threshold (e.g., 80%). The module outputs the mass limit at which this completeness is reached.

2.3 Photo‑z Performance‑specific parameters

Redshift range (zmin, zmax): Redshift interval for the simulation.
Bands list: Comma‑separated list of filters (e.g., csst-u,csst-g,csst-r,csst-i,csst-z). Must match the order of rows in params.txt.

3. Uploading Observing Parameters (`params.txt`)

The file must be named params.txt and follow one of two formats:

For Mass Completeness: Single line with key‑value pairs (one band only). Example:

exp_time = 250        # single exposure time (s)
n_read = 8            # number of exposures
backsky = 0.2         # sky background (e-/pixel/s)
psf_fwhm = 0.2        # PSF FWHM (arcsec)
diameter = 2.0        # telescope diameter (m)
pixel_size = 0.074    # pixel scale (arcsec/pixel)
dark_current = 0.02   # dark current (e-/pixel/s)
readout_noise = 5     # readout noise (e-)

For Photo‑z Performance: Tab‑separated table with one header row and one data row per band (order same as bands_list). Example:
```
exp_time n_read backsky psf_fwhm diameter pixel_size dark_current readout_noise
250 8 0.018 0.177 2.0 0.074 0.02 5
250 8 0.156 0.177 2.0 0.074 0.02 5
250 8 0.200 0.177 2.0 0.074 0.02 5
```
Important – band ordering: In the Photo-z module, the bands you add are automatically sorted by wavelength and displayed in that order in the Bands list field. Each data row in params.txt must follow this sorted band order: the first row corresponds to the shortest-wavelength band shown, the second row to the next, and so on. Filling rows in the order you originally typed the bands (rather than the sorted order shown) will assign the wrong parameters to each band.

Note: Units are indicated in comments (e.g., exp_time in seconds, psf_fwhm in arcseconds). The file can be uploaded by clicking/dragging into the upload area.

4. Running a Simulation

Fill in all required fields on the respective module page.
Upload your params.txt (if not provided, default values may be used – but strongly recommended to upload your own).
Click Submit. The calculation may take several minutes depending on field size and filters.
Watch the real‑time output log in the console area.

Stopping a run: While a job is running, a red Stop button is available. Clicking it terminates the task immediately, including all of its child processes.
Runs continue in the background: Simulations run on the server in the background. You may close or refresh the browser tab without interrupting the job – when you return to the page, its running or completed state is automatically restored, so you can keep watching the log or download the results.

5. Understanding the Results

5.1 Mass Completeness Outputs

Completeness Heatmap: 2D plot (redshift vs. stellar mass) showing the number density of galaxies before SNR cut (colormap), with the user‑defined completeness limit overplotted as a red line. The parent mock (deep JWST/F444W) is shown as grey background points.
Downloadable folder (ZIP) contains:
- catalog.fits – raw mock catalog (after area correction and SNR cut).
- list_*.txt – extracted ID, redshift, mass columns.
- *_completeness.png – the completeness plot.
- picture/ – simulated sky image (FITS + PNG) of a 0.01 deg² sub‑field.
- Various completeness data files (*_count.txt, All_Completeness_*.txt, 80Completeness_*.txt).

5.2 Photo‑z Performance Outputs

Redshift Comparison Plot: Scatter plot of z_phot vs z_true (or z_spec) with outliers highlighted. Metrics (σ_NMAD, bias, outlier fraction) are displayed.
Boxplot with Density: Distribution of Δz/(1+z) in redshift bins, showing median, mean, and 3σ_NMAD lines.
Performance Metrics (saved as metric_data.txt): σ_NMAD, bias, outlier count/ratio.
Simulated sky images (one per band) generated with SkyMaker, showing realistic galaxy morphologies and noise.
Full folder ZIP includes: EAZY input/output files (.cat, .zout.fits, .h5), extracted catalogs, and configuration files.

6. Downloading Data

After successful completion, a “Download Entire Folder (ZIP)” button appears. Click it to download all generated files. You can also directly download individual images via the “View Full Size” or “Download” links under each plot.

7. Further Analysis of Downloaded Data

The downloaded FITS files can be used for custom analyses:

Mock catalogs (FITS format) can be read with astropy.io.fits or fitsio in Python. Columns include positions, redshifts, stellar masses, fluxes, and morphological parameters (bulge/disk radii, axis ratios, etc.).
Simulated images (FITS) are ideal for testing source extraction (e.g., SExtractor), adding PSF convolution, or injecting additional noise. The images currently contain only Poisson and sky background noise; you can add instrumental PSF, flat‑field errors, cosmic rays, etc.
EAZY output (.zout.fits and .h5) provides full redshift probability distributions for further photo‑z studies.
Completeness data files (e.g., 80Completeness_*.txt) give the mass limit per redshift bin, ready for plotting or comparison with observations.

Pro tip: To add a PSF to the simulated images, you can use astropy.convolution with a Moffat or Gaussian kernel. For realistic noise, inject dark current, readout noise, and flat‑field uncertainties using the parameters from your params.txt.

8. Troubleshooting

“File not found” errors: Ensure params.txt is correctly named and uploaded.
Long waiting times: Large areas or many bands increase runtime. Consider reducing area (e.g., 0.1 deg²) for quick tests.
Missing plots: Check the output log for warnings. Insufficient galaxies after SNR cut may lead to empty plots.

9. References

For detailed methodology, please refer to the VISION paper (Wang et al., in prep) and the documentation of EGG, EAZY, and SkyMaker.

Happy surveying! – VISION Team