firestudio.studios.star_studio.StarStudio

class firestudio.studios.star_studio.StarStudio(datadir: str, snapnum: int, sim_name: str, cache_file_name: Optional[str] = None, gas_snapdict: Optional[dict] = None, star_snapdict: Optional[dict] = None, galaxy_kwargs: Optional[dict] = None, master_loud: bool = True, setup_id_append: str = '', **kwargs)[source]

Bases: firestudio.studios.studio.Studio

Studio class for making mock hubble images with attenuation along the line of sight.

__init__(datadir: str, snapnum: int, sim_name: str, cache_file_name: Optional[str] = None, gas_snapdict: Optional[dict] = None, star_snapdict: Optional[dict] = None, galaxy_kwargs: Optional[dict] = None, master_loud: bool = True, setup_id_append: str = '', **kwargs)

Base class that handles camera manipulation and data caching.

Parameters

datadir (str) – directory to put intermediate and output files, 'firestudio' is appended if the directory contains sim_name
snapnum (int) – snapshot number (feel free to lie if you aren’t using FIRE_studio to open a snapshot, it is needed for cache file name though)
sim_name (str) – name of the simulation, i.e. 'm12i_res7100'. prepends the cache_file_name if the sim_name isn’t already in the path to disambiguate caches.
cache_file_name (str, optional) – the name of the file to save maps to, if None 'proj_maps_%03d.hdf5'%snapnum, defaults to None
gas_snapdict (dict, optional) – a dictionary containing SPH data, defaults to None
star_snapdict (dict, optional) – a dictionary containing collisionless particle data, defaults to None
galaxy_kwargs (dict, optional) – dictionary that contains kwargs that should be passed to the opened abg_python.galaxy.Galaxy instance that is used to load snapshot data from disk, defaults to None
master_loud (bool, optional) – flag for enabling/disabling all print statements, defaults to True
setup_id_append (str, optional) – suffix to append to the setup_id in the cache file, defaults to ‘’

Methods

`__init__`(datadir, snapnum, sim_name[, ...])	Base class that handles camera manipulation and data caching.
`addScaleBar`(image)	_summary_
`addText`(ax)	_summary_
`computeFrameBoundaries`()	Uses the camera to calculate the minimum and maximum x, y, and z limits as well as the physical resolution of the image.
`cullFrameIndices`(Coordinates)	boolean mask of those particles within the volume defined by Xmin-Xmax, Ymin-Ymax, and Zmin-Zmax
`drawCoordinateAxes`(ax[, spacing, length, colors])	_summary_
`get_HSML`(snapdict_name[, use_metadata, ...])	Compute smoothing lengths for particles that don't have them, typically collisionless particles (like stars).
`get_mockHubbleImage`([use_metadata, ...])	Projects starlight and approximates attenuatation along line of sight into SDSS u, g, and r bands.
`gradientBlendImages`(image_1[, image_2, ...])	_summary_
`load_SnapshotData`([gas_mask, star_mask])	Binds simulation output to `self.gas_snapdict` and `self.star_snapdict`.
`plotImage`(ax, final_image, **kwargs)	Base method for overlaying artists on top of projected image.
`plotParameterGrid`([dynrange_init, ...])	Plots a grid of images that steps in maxden and dynrange to help the user decide what values to use, based on their aesthetic preference.
`predictParameters`([left_percentile, ...])	Guesses what the "best" values for maxden and dynrange are from the distribution of surface brightnesses in the current image.
`prepareCoordinates`([lums, nu_effs, BAND_IDS])	Reads snapshot data from self.snapdict and self.star_snapdict in the imaging volume defined by self.Xmin,`self.Xmax`,`self.Ymin`,`self.Ymax`,`self.Zmin`,`self.Zmax`.
`print_ImageParams`()	Prints current image setup to console.
`produceImage`([quick])	Generates a mock hubble image, along with any annotations/scale bars, using the stored image parameters.
`quick_get_mockHubbleImage`([lums, nu_effs, ...])	Approximate the ~firestudio.studios.StarStudio.get_mockHubbleImage routine using a 2d histogram.
`render`([ax])	Generates an image with the produceImage method and then plots it with the plotImage method.
`renormalizeTransposeImage`(image, min_val, ...)	_summary_
`saveFigure`(fig[, image_name])	_summary_
`set_CacheFile`()	Creates the cache hdf5 file.
`set_ImageParams`([use_defaults, loud])	Changes the parameters of the image.

Attributes

required_snapdict_keys

these are minimum required keys for render() function to run.

addScaleBar(image: numpy.ndarray)

_summary_

Parameters: image (np.ndarray) – array of RGB image pixel values
Returns: image
Return type: np.ndarray

addText(ax: matplotlib.axes._axes.Axes)

_summary_

Parameters: ax (plt.Axes) – _description_

computeFrameBoundaries()

Uses the camera to calculate the minimum and maximum x, y, and z limits as well as the physical resolution of the image.

Sets following attributes: self.Xmin, self.Xmax – self.Ymin, self.Ymax – self.Zmin, self.Zmax – self.npix_x, self.npix_y – self.Acell –

cullFrameIndices(Coordinates: numpy.ndarray)

boolean mask of those particles within the volume defined by Xmin-Xmax, Ymin-Ymax, and Zmin-Zmax

Parameters: Coordinates (np.ndarray) – array of particle coordinates
Returns: a boolean mask which is True for particles in the extraction volume and False outside.
Return type: bool np.ndarray

drawCoordinateAxes(ax: matplotlib.axes._axes.Axes, spacing: float = 1, length: float = 10, colors: Optional[list] = None)

_summary_

Parameters

ax (plt.Axes) – _description_
spacing (float, optional) – _description_, defaults to 1
length (float, optional) – _description_, defaults to 10
colors (list, optional) – _description_, defaults to None

Returns

_description_

Return type

_type_

get_HSML(snapdict_name: str, use_metadata: bool = True, save_meta: bool = True, assert_cached: bool = False, loud: bool = True, **kwargs)

Compute smoothing lengths for particles that don’t have them, typically collisionless particles (like stars).

Parameters

snapdict_name (str) – string identifying which snapdict should be used to compute smoothing lengths, either 'gas' or 'star'
use_metadata (bool, optional) – flag for whether a cached result should be used (if it exists), defaults to True
save_meta (bool, optional) – flag to save the result in the cache, defaults to True
assert_cached (bool, optional) – flag to require a cache hit and raise an exception otherwise, defaults to False
loud (bool, optional) – flag for whether cache hits/misses should be announced to the console, defaults to True

Returns

estimated smoothing lengths

Return type

np.float32 np.ndarray

get_mockHubbleImage(use_metadata: bool = True, save_meta: bool = True, assert_cached: bool = False, loud: bool = True, **kwargs)[source]

Projects starlight and approximates attenuatation along line of sight into SDSS u, g, and r bands.

BAND_IDS indexes the following list:

lambda_eff = np.array([
    ## Bolometric (?)
            1.e-5,  
    ## SDSS u       g       r      i      z
            3551. , 4686. , 6165., 7481., 8931.,
    ##      U       B       V      R
            3600. , 4400. , 5556., 6940., 
    ##      I      J       H       K
            8700., 12150., 16540., 21790.])

Parameters

use_metadata (bool, optional) – flag for whether a cached result should be used (if it exists), defaults to True
save_meta (bool, optional) – flag to save the result in the cache, defaults to True
assert_cached (bool, optional) – flag to require a cache hit and raise an exception otherwise, defaults to False
loud (bool, optional) – flag for whether cache hits/misses should be announced to the console, defaults to True

Kwargs

lums (np.ndarray, optional) – array of luminosities for each star particle. If None then luminosities are calculated in the bands specified by BAND_IDS, defaults to None
nu_effs (list, optional) – list of effective frequencies corresponding to the bands of luminosities provides in the lums. If None, uses the frequencies corresponding to the specified BAND_IDS, defaults to None
BAND_IDS (list, optional) – List of indices that identify which bands to model stellar emission in. If None uses Sloan UGR bands (1,2,3), defaults to None

Returns

metal_mass_map - 2d map of metal mass used to attenuate luminosities along LOS in pixel, in Msun/kpc^2
out_0 - 2d map of luminosities in first band in Lsun/kpc^2
out_1 - 2d map of luminosities in second band in Lsun/kpc^2
out_2 - 2d map of luminosities in third band in Lsun/kpc^2

Return type

np.ndarray, np.ndarray, np.ndarray, np.ndarray

gradientBlendImages(image_1: numpy.ndarray, image_2: Optional[numpy.ndarray] = None, gradient_width_percent: float = 0.1, angle: Optional[float] = None, **kwargs)

_summary_

Parameters

image_1 (np.ndarray) – _description_
image_2 (np.ndarray, optional) – _description_, defaults to None
gradient_width_percent (float, optional) – _description_, defaults to 0.1
angle (float, optional) – _description_, defaults to None

Returns

_description_

Return type

_type_

load_SnapshotData(gas_mask: Optional[numpy.ndarray] = None, star_mask: Optional[numpy.ndarray] = None, **kwargs)

Binds simulation output to self.gas_snapdict and self.star_snapdict.

Parameters

gas_mask (np.ndarray, optional) – boolean mask that should be applied to the galaxy.sub_snap, defaults to None
star_mask (np.ndarray, optional) – boolean mask that should be applied to the galaxy.sub_star_snap, defaults to None

Kwargs

fuse_saved_subsnapshots (bool, optional) – save/load subsnapshots, uncompressed copies of the snapshot oriented on the main disk with particles within the virial radius. This can take up lots of disk space, defaults to False
del_galaxy (bool, optional) – flag for whether the abg_python.galaxy.gal_utils.Galaxy object should be deleted after being used to get the snapshot dictionaries, defaults to True

Returns

abg_python.galaxy.Galaxy if del_galaxy == False, otherwise returns None

Return type

None/abg_python.galaxy.Galaxy object

plotImage(ax: matplotlib.axes._axes.Axes, final_image: numpy.ndarray, **kwargs)

Base method for overlaying artists on top of projected image.

if self.scale_bar: overlays a scale bar by filling the RGB pixel values with white if self.noaxis: removes the coordinate axes, labels, and ticks

Will also add self.figure_label as text to the image. See set_ImageParams() for details.

Parameters

ax (plt.Axes) – axis to plot image to
final_image (np.ndarray) – array of RGB image pixel values

plotParameterGrid(dynrange_init: float = 100.0, maxden_init: float = 0.01, dynrange_step: Optional[float] = None, maxden_step: Optional[float] = None, nsteps: int = 4, **kwargs)[source]

Plots a grid of images that steps in maxden and dynrange to help the user decide what values to use, based on their aesthetic preference. Step is applied multiplicatively. Accepts keyword arguments for set_ImageParams()

Parameters

dynrange_init (float, optional) – initial value in top left corner of grid, defaults to 1e2
maxden_init (float, optional) – initial value in top left corner of grid, defaults to 1e-2
dynrange_step (float, optional) – step between grid thumbnails, defaults to sqrt(10), defaults to None
maxden_step (float, optional) – step between grid thumbnails, defaults to sqrt(10), defaults to None
nsteps (int, optional) – number of steps in (square) thumbnail grid, defaults to 4

Returns

fig - the matplotlib figure drawn to

axs - the matplotlib axes in the grid

Return type

plt.figure, list of plt.Axes

Example usage

starStudio.plotParameterGrid(
    dynrange_init=1e3,
    maxden_init=1,
    dynrange_step=.1,
    maxden_step=.1,
    nsteps=2,
    use_colorscheme_nasa=False)

predictParameters(left_percentile: float = 0.1, right_percentile: float = 0.99, L_sfc_densities: Optional[numpy.ndarray] = None, ax: Optional[matplotlib.axes._axes.Axes] = None, quick: bool = False)[source]

Guesses what the “best” values for maxden and dynrange are from the distribution of surface brightnesses in the current image. Looks for the left_percentile and right_percentile and returns right_percentile and the distance between it and left_percentile (in log space).

Parameters

left_percentile (float, optional) – lower bound on image surface brightness percentile, defaults to 0.1
right_percentile (float, optional) – upper bound on image surface brightness percentile, defaults to 0.99
L_sfc_densities (np.ndarray, optional) – surface densities to find the percentiles of. If None uses get_mockHubbleImage() to retrieve the surface densities of the projected mock hubble image, defaults to None
ax (plt.Axes, optional) – axis to plot distribution of surface brightnesses with overlay of percentiles and such to, defaults to None
quick (bool, optional) – flag to use ~firestudio.studios.star_studio.StarStudio.quick_get_mockHubbleImage, defaults to False

Returns

maxden - maximum surface brightness of the image

dynrange - distance between maximum and minimum surface brightness in log space.

Return type

float, float

prepareCoordinates(lums: Optional[numpy.ndarray] = None, nu_effs: Optional[list] = None, BAND_IDS: Optional[list] = None)[source]

Reads snapshot data from self.snapdict and self.star_snapdict in the imaging volume defined by self.Xmin,`self.Xmax`,`self.Ymin`,`self.Ymax`,`self.Zmin`,`self.Zmax`. Unpacks necessary arrays and provides them to the calling imaging routine.

BAND_IDS indexes the following list:

lambda_eff = np.array([
    ## Bolometric (?)
            1.e-5,  
    ## SDSS u       g       r      i      z
            3551. , 4686. , 6165., 7481., 8931.,
    ##      U       B       V      R
            3600. , 4400. , 5556., 6940., 
    ##      I      J       H       K
            8700., 12150., 16540., 21790.])

Parameters

lums (np.ndarray, optional) – array of luminosities for each star particle. If None then luminosities are calculated in the bands specified by BAND_IDS, defaults to None
nu_effs (list, optional) – list of effective frequencies corresponding to the bands of luminosities provides in the lums. If None, uses the frequencies corresponding to the specified BAND_IDS, defaults to None
BAND_IDS (list, optional) – List of indices that identify which bands to model stellar emission in. If None uses Sloan UGR bands (1,2,3), defaults to None

Returns

kappas - array of effective cross sections in each band
lums -  array of luminosities in each band
star_pos - coordinate data for emitting stars in kpc 
h_star - effective smoothing length/radius for each star particle in kpc
gas_pos - coordinate data for attenuating gas in kpc
mgas - mass data for attenuating gas in 10^10 Msun
gas_metals - total metal mass fraction for each gas particle
h_gas - smoothing length/radius for each gas particle in kpc

Return type

np.ndarray(3), np.ndarray(Nstar,3), np.ndarray(Nstar,3), np.ndarray(Ngas), np.ndarray(Ngas,3), np.ndarray(Ngas), np.ndarray(Ngas), np.ndarray(Ngas)

print_ImageParams()[source]: Prints current image setup to console.

produceImage(quick: bool = False, **kwargs)[source]

Generates a mock hubble image, along with any annotations/scale bars, using the stored image parameters.

Parameters: quick (bool, optional) – flag to use a simple 2d histogram (for comparison or for quick iteration as you choose image parameters), defaults to False
Returns: RGB pixel array of the produced image
Return type: np.ndarray(npix_x,npix_y,3)

quick_get_mockHubbleImage(lums: Optional[numpy.ndarray] = None, nu_effs: Optional[list] = None, BAND_IDS: Optional[list] = None, **kwargs)[source]

Approximate the ~firestudio.studios.StarStudio.get_mockHubbleImage routine using a 2d histogram.

BAND_IDS indexes the following list:

lambda_eff = np.array([
    ## Bolometric (?)
            1.e-5,  
    ## SDSS u       g       r      i      z
            3551. , 4686. , 6165., 7481., 8931.,
    ##      U       B       V      R
            3600. , 4400. , 5556., 6940., 
    ##      I      J       H       K
            8700., 12150., 16540., 21790.])

Parameters

lums (np.ndarray, optional) – array of luminosities for each star particle. If None then luminosities are calculated in the bands specified by BAND_IDS, defaults to None
nu_effs (list, optional) – list of effective frequencies corresponding to the bands of luminosities provides in the lums. If None, uses the frequencies corresponding to the specified BAND_IDS, defaults to None
BAND_IDS (list, optional) – List of indices that identify which bands to model stellar emission in. If None uses Sloan UGR bands (1,2,3), defaults to None

Returns

metal_mass_map - 2d map of metal mass used to attenuate luminosities along LOS in pixel, in Msun/kpc^2
out_0 - 2d map of luminosities in first band in Lsun/kpc^2
out_1 - 2d map of luminosities in second band in Lsun/kpc^2
out_2 - 2d map of luminosities in third band in Lsun/kpc^2

Return type

np.ndarray, np.ndarray, np.ndarray, np.ndarray

render(ax: Optional[matplotlib.axes._axes.Axes] = None, **kwargs)

Generates an image with the produceImage method and then plots it with the plotImage method.

Parameters: ax (plt.Axes, optional) – axis to plot image to, if None will create a new figure, defaults to None
Returns: ax – the axis the image was plotted to final_image – Npixels x Npixels x 3 RGB pixel array
Return type: plt.Axes, np.ndarray

renormalizeTransposeImage(image: numpy.ndarray, min_val: float, max_val: float, quantity_name: str)

_summary_

Parameters

image (np.ndarray) – _description_
min_val (float) – _description_
max_val (float) – _description_
quantity_name (str) – _description_

Returns

_description_

Return type

_type_

required_snapdict_keys = ['Masses', 'Coordinates', 'SmoothingLength', 'Temperature', 'AgeGyr', 'Metallicity']: these are minimum required keys for render() function to run.

saveFigure(fig, image_name: Optional[str] = None, **savefig_args)

_summary_

Parameters

fig (_type_) – _description_
image_name (str, optional) – _description_, defaults to None

set_CacheFile()

Creates the cache hdf5 file. Requires self.snapnum and sim_name be set.

Raises: IOError – if self.snapnum and self.sim_name are not set to disambiguate the cache file
Returns: cache file for storing image maps
Return type: abg_python.galaxy.metadata_utils.Metadata

set_ImageParams(use_defaults: bool = False, loud: bool = True, **kwargs)[source]

Changes the parameters of the image. Also calls Studio’s set_ImageParams(), passing along any unmatched kwargs.

Parameters

use_defaults (bool, optional) – If True then default values of the parameters will be set (potentially overwriting any previously specified parameters). If False adjust only the keywords passed, defaults to False
loud (bool, optional) – flag to print which parameters are being set/updated, defaults to True

Kwargs

maxden (float, optional) – controls the saturation of the image, sets the upper limit of the “colorbar” if None uses the 99 %’ile of the image surface brightness, defaults to None
dynrange (float, optional) – controls the saturation of the image, sets the lower limit of the “colorbar” with respect to maxden, if None uses the dynamic range between maxden and the 10th %’ile of the image surface brightness, defaults to None
nodust (bool, optional) – flag for whether dust attenuantion should be ignored, defaults to False
age_max_gyr (float, optional) – maximum age in Gyr to show stellar emission from. If None then emission from all star particles is considered, defaults to None
color_scheme_nasa (bool, optional) – flag for switching between Hubble vs. SDSS false color remapping, defaults to True

Example usage

starStudio.set_ImageParams(
    maxden=0.1,
    dynrange=10,
    figure_label='Hubble')