imaging package

Collection of scripts to launch the proposed imaging pipeline on synthetic or real data.

imaging.imaging(srcName, datasetsNames, dataFilename, effChans2Image, param_solver, param_global, param_nufft, param_precond, param_wproj, dict)

Main function to run any algorithm from the SARA family using the configuration provided in imaging.main_input_imaging. The approaches are Faceted HyperSARA, HyperSARA and SARA.

Parameters

  • srcName (string) – Name of the target source to be reconstructed as specified during data extraction, used to get the data and generate output files.

  • dataSetsNames (cell of string) – Names of the different datasets to be imaged (e.g., in the cases of different acquisition configurations or different observation times), to be set to [] if one data set is imaged and no name tag of the associated MS is given during data extraction.

  • dataFilenames (cell of string) – Function handle taking a channel index as an input and returning the name of the associated data .mat file (one file per frequency channel per dataset), following the nomenclature adopted during data extraction.

  • effChans2Image (cell array) – Cell array containing the ids of the physical (input) channels to be concatenated for each effective (output) channel.

  • param_global (struct) – Global imaging pipeline parameters (see imaging.main_input_imaging()).

  • param_global.im_pixelSize (double) – Pixel-size in arcsec. Set to [] to use the default value corresponding to 2 times the resolution of the observation (given by the longest baseline at the highest frequency).

  • param_global.im_Nx (int) – Image dimension (x axis, dimension 2).

  • param_global.im_Ny (int) – Image dimension (y axis, dimension 1).

  • param_global.adjust_flag_noise (bool) – Flag to activate adaptive estimation of the noise level & paramerter adjustment.

  • param_global.measop_flag_visibility_gridding (bool) – Flag to activate data dimensionality reduction via visibility gridding in the definition of the measurement operator.

  • param_global.data_flag_apply_imaging_weights (bool) – Flag to read and apply imaging weights (e.g. Briggs, uniform) to data.

  • param_global.algo_solver (string ("sara", "hs" or "fhs").) – Selected solver.

  • param_global.facet_subcubeInd (int) – Index of the spectral facet to be reconstructed (set to -1 or 0 to deactivate spectral faceting).

  • param_global.facet_Qc (int) – Number of spectral facets. Active only in "fhs".

  • param_global.facet_Qx (int) – Number of spatial facets along spatial axis x. Active only in "fhs".

  • param_global.facet_Qy (int) – Number of spatial facets along spatial axis y. Active only in "fhs".

  • param_global.facet_overlap_fraction (double[2]) – Fraction of the total size of facet overlapping with a neighbouring facet along each axis (y and x) for the faceted low-rankness prior. Active only in "fhs". Will be reset automatically to [0, 0] if the spatial faceting is not active in "fhs" along at least one dimension(i.e., param_global.facet_Qy = 1 and/or param_global.facet_Qx = 1).

  • param_global.facet_window_type (string ("triangular", "hamming" or "pc" (piecewise-constant))) – Type of apodization window considered for the faceted nuclear norm prior. Active only in "fhs".

  • param_global.reg_gam (double) – Additional multiplicative factor affecting the joint average sparsity regularization term in "fhs" and "hs". Additional multiplicative factor affecting the average sparsity regularization term in "sara".

  • param_global.reg_gam_bar (double) – Additional multiplicative factor affecting low-rankness prior regularization parameter. Active only in "fhs" and "hs".

  • param_global.reg_flag_reweight (int) – Flag to activate re-weighting.

  • param_global.reg_nReweights (int) – Maximum number of reweight.

  • param_global.algo_flag_computeOperatorNorm (bool) – Flag to trigger the computation of the norm of the (preconditionned) measurement operator. Default set to true. If set to false, MATLAB will look for a file where this quantity has been saved (save and computation steps are triggered in imaging.imaging()).

  • param_global.algo_flag_saveOperatorNorm (bool) – Flag to save the norm of the (preconditionned) measurement operator. Default set to false. If set to true, MATLAB will save the quantity in a .mat file.

  • param_global.algo_flag_solveMinimization (bool) – Flag triggering the solver ("fhs", "hs" or "sara").

  • param_global.ncores_data (int) – Number of cores handlig the data fidelity terms (data cores). For Faceted HyperSARA, the total number of cores used is Qx*Qy + ncores_data + 1. For SARA and HyperSARA, represents the number of cores used for the parallelization.

  • param_global.parcluster (string) – Name of the parallel parcluster profile to launch the parpool. By default "local" profile is used. The user should set it to the name of the slurm parcluster profile created on his/her HPC machine, if prefered.

  • param_global.preproc_filename_noise_std (anonymous function) – Function handle, taking the indices of the physical channel, and the and the dataset, returning a string corresponding to the name of a file containing noise statistics obtained from a pre-processing step. Expected vars: sigma: the standard deviation of the noise, RESIDUAL: (optional) the residual visibilities from a pre-processing step. If not used, should be set to [].

  • param_global.preproc_filename_cal_solutions (anonymous function) – Function handle, taking the indices of the physical channel and the dataset, and returning a string corresponding to the name of a file containing DDE/DIE calibration solutions. Expected var: DDEs: complex array if DDE calibration and DIEs: complex vector if DIE calibration . If not used, should be set to [].

  • param_global.preproc_filename_model (anonymous function) – Function handle, taking the indices of the first and last physical channels, associated with an effective (output) channel, and returning the name of a file containing a model image to be used to initialize the reconstruction algorithm. If not used, should be set to [].

Note

  • All the results will be stored in a directory of th

  • Examples to set the input (physical) and output (effective) channels IDs:

%% Name of the dataset to be imaged
% example a: one dataset -name tag is not compulsory:
datasetNames = {''};
% example b: two data sets from two configurations of the VLA
datasetNames = {'CYGA-ConfigA','CYGA-ConfigC'};

%% Indices of the 'physical' channels to be concatenated
% example a: two effective channels, containing two 'physical'
% channels each
effChans2Image = {[1,2], [3,4]};
% example b: one channel effective channel with one physical channel
effChans2Image = {[1]};

Deprecated fields

param_global.reg_flag_homotopyint

Flag to activate homotopy strategy in the re-weighting scheme.

imaging.main_generate_cyga_cubes

Main script to generate the reference synthetic wideband image cubes used in [Thouvenin2021]. Requires the S_DDE_MODEL.fits image file associated with [Dabbech2021], which can be retrieved as follows from a unix (MAC, Linux, Windows WSL or MinGw) terminal.

# if on MAC:
# brew install wget
cd path/to/Faceted-HyperSARA
mkdir data && cd data
wget -P . https://researchportal.hw.ac.uk/files/43645966/S_DDE_MODEL.fits

Note

Cubes and additional informations for the synthetic data experiments are saved by default in the folder Faceted-HyperSARA/data/.

imaging.main_generate_data(json_filename, srcName, ncores_data, coverage_path, exp_type, superresolution_factor, isnr, flag_visibility_gridding, parcluster, flag_generateCoverage)

Generate a .mat synthetic dataset compatible with the requirements from the imaging interface specified in imaging.main_input_imaging.

Parameters

  • json_filename (string) – Name of the input .json configuration file specifying the value of the algorithm parameters (PDFB, reweighting, ellipsoid, projection, preconditioning, …).

  • srcName (string) – Name of the image cube to be reconstructed.

  • ncores_data (int) – Number of CPU cores allocated to the data generation process.

  • coverage_path (string) – Path to a pre-generated coverage file (a single .mat file containing a 3 column array uvw, each corresponding to the u, v and w coordinates). The \(uv\)-coverage used in [Thouvenin2021] is provided in Faceted-HyperSARA/data/msSpecs.mat.

  • exp_type (string) – Type of experiment considered, reproducing those of the associated publication. Possible value is spatial (respectively spectral) to generate the \(1024 \times 2048 \times 20\) (resp. \(256 \times 512 \times 100\)) CygA cube adopted for the spatial (resp. spectral) faceting experiment in [Thouvenin2021].

  • superresolution_factor (double) – Base super-resolution factor used to define the pixelSize (by default, twice the nominal resolution of the instrument).

  • isnr (double) – Input SNR of the generated data.

  • flag_visibility_gridding (bool) – Flag to activate dimensionality reduction via visibility gridding (not active at the moment).

  • parcluster (string) – Name of the parcluster profile used to launch parpool, default "local".

  • flag_generateCoverage (bool) – Flag to generate a custom coverage. Otherwise, load a pre-defined coverage file.

Note

The two datasets used in [Thouvenin2021] can be generated by running the following MATLAB commands

% generate data for the spatial faceting experiment
main_generate_data('default_parameters.json', 'cygA', 4, ...
'../data/msSpecs.mat', 'spatial', 2, 40, false, ...
"local", false)

% generate data for the spectral faceting experiment
main_generate_data('default_parameters.json', 'cygA', 4, ...
'../data/msSpecs.mat', 'spectral', 2, 40, false, ...
"local", false)

Important

  • The synthetic data .mat files are saved by default in the directory Faceted-HyperSARA/data/<srcName>/<exp_type>, with <srcName> and <exp_type> replaced by the value selected when calling the function.

  • The resulting .mat files (one for each frequency) are composed of the following variables

y (complex[:])

Noisy visibility vector.

l2bounds (double)

\(\ell_2\) bounds to be used in the data fidelity constraints.

sigma_noise (double)

Standard deviation of the additive white complex Gaussian noise affecting the clean data y0.

u (double[:])

\(u\) coordinate, expressed in units of the wavelength.

v (double[:])

\(v\) coordinate, expressed in units of the wavelength.

w (double[:])

\(w\) component, expressed in units of the wavelength.

frequency (double)

Acquisition frequency (in Hz).

maxProjBaseline (double)

Maximum projected baseline, expressed in units of the wavelength.

nW (double[:])

Inverse noise whitening vector (1/sigma_noise).