build_datacube: A function for making a mock spectral/velocity data cube

In kateharborne/SimSpin: SimSpin - A package for the kinematic analysis of galaxy simulations

A function for making a mock spectral/velocity data cube

Description

The purpose of this function is to generate a mock IFU data cube from a SimSpin file, as generated using the make_simspin_file() function. The data cube produced can be either a spectral cube or a velocity cube.

Usage

build_datacube(
  simspin_file,
  telescope,
  observing_strategy,
  method,
  verbose = F,
  write_fits = F,
  output_location,
  object_name = "GalaxyID_unknown",
  telescope_name = "SimSpin",
  observer_name = "Anonymous",
  split_save = F,
  cores = 1,
  mass_flag = F,
  voronoi_bin = F,
  vorbin_limit = 10
)

Arguments

simspin_file	The path to the location of the SimSpin .Rdata file OR output list from make_simspin_file().
telescope	An object of the telescope class describing the specifications of the observing telescope (i.e. field of view, spatial resolution, wavelength resolution, etc.). See telescope help for more details.
observing_strategy	An object of the observing_strategy class that describes the properties of the observed simulation (i.e. redshift, inclination, seeing conditions). See observing_strategy help for more details.
method	String to describe whether cubes output are "spectral", "gas", "sf gas" or "velocity" (as in SimSpin v1) along the z-axis. Default is "spectral".
verbose	Default is FALSE. If you would like the code to give updates about its progress, change this parameter to TRUE.
write_fits	Default is FALSE. If you would like the code to output a FITS file, change this parameter to TRUE.
output_location	Optional parameter that describes the path and file name of the FITS file output if write_fits = TRUE. If output_location is specified as just a path, the file name will be auto-generated based on the name of the input simspin_file and the observing conditions and written to the specified directory. If write_fits = TRUE and no output_location is specified, the FITS file name will be auto-generated and written to the same directory as the input simspin_file.
object_name	Optional string used in write_simspin_FITS to describe the name of the object observed in FITS header.
telescope_name	Optional string used in write_simspin_FITS to describe the name of the telescope used for observation in FITS header.
observer_name	Optional string used in write_simspin_FITS to describe the name of the person who ran the observation in FITS header.
split_save	Boolean describing whether to split the output from build_datacube() into multiple files while saving to FITS. If TRUE, several FITS files will be saved with file names that reflect their content (i.e."_spectral_cube.FITS", "_velocity_image.FITS", "_flux_images.FITS", etc.). Default option is FALSE.
cores	Float describing the number of cores to run the interpolation and velocity gridding on. Default is 1.
mass_flag	Boolean flag that, when set to TRUE, will compute properties using a mass weighting rather than a luminosity weighting. Default is FALSE.
voronoi_bin	Boolean flag that, when set to TRUE, will bin pixels into voronoi tessellated cells that contain a minimum number of particles per pixel, specified by vorbin_limit. Default is FALSE.
vorbin_limit	Integer float that describes the minimum number of particles per pixel within a given bin, only used if voronoi_bin = T.

Value

Returns a list containing four elements:

1. spectral_cube or velocity_cube - a 3D array containing either a spectral cube or a velocity cube, where the output type is determined by the method selected in the telescope function.

2. observation - a list containing a summary of the details of the observation (i.e. the output from the function observation()).

3. raw_images - a list of 2D arrays, where each 2D array represents a raw particle image gridded as for the observation details.

4. observed_images - NULL or a list of 2D arrays (again, where the output type is determined by the method selected in the telescope function.) containing kinematic images of the collapsed cube. If blur=T, these images will be blurred to the specified amount.

If write_fits = T, a .fits file that contains a the generated cube and relevant header describing the mock observation will also be produced at the specified output_location.

Examples

ss_gadget = system.file("extdata", "SimSpin_example_Gadget_spectra.Rdata",
                        package = "SimSpin")
cube = build_datacube(simspin_file = ss_gadget,
                     telescope = telescope(type="SAMI"),
                     observing_strategy = observing_strategy())

kateharborne/SimSpin documentation built on March 27, 2024, 7:10 a.m.