Utilities¶
General Utilities¶
- marvin.utils.general.general.check_versions(version1, version2)[source]¶
Compate two version ids against each other
Checks if version1 is greater than or equal to version2.
- marvin.utils.general.general.convertCoords(coords, mode='sky', wcs=None, xyorig='center', shape=None)[source]¶
Convert input coordinates to array indices.
Converts input positions in x, y or RA, Dec coordinates to array indices (in Numpy style) or spaxel extraction. In case of pixel coordinates, the origin of reference (either the center of the cube or the lower left corner) can be specified via
xyorig
.If
shape
is defined (mandatory formode='pix'
, optional formode='sky'
) and one or more of the resulting indices are outside the size of the input shape, an error is raised.This functions is mostly intended for internal use.
- Parameters
coords (array) – The input coordinates, as an array of shape Nx2.
({'sky' (mode) – The type of input coordinates, either
'sky'
for celestial coordinates (in the format defined in the WCS header information), or'pix'
for pixel coordinates.'pix'} – The type of input coordinates, either
'sky'
for celestial coordinates (in the format defined in the WCS header information), or'pix'
for pixel coordinates.wcs (None or
astropy.wcs.WCS
object) – Ifmode='sky'
, the WCS solution from which the cube coordinates can be derived.xyorig (str) – If
mode='pix'
, the reference point from which the coordinates are measured. Valid values are'center'
, for the centre of the spatial dimensions of the cube, or'lower'
for the lower-left corner.shape (None or array) – If
mode='pix'
, the shape of the spatial dimensions of the cube, so that the central position can be calculated.
- Returns
result (Numpy array) – An array with the same shape as
coords
, containing the cube index positions for the input coordinates, in Numpy style (i.e., the first element being the row and the second the column).
- marvin.utils.general.general.convertImgCoords(coords, image, to_pix=None, to_radec=None)[source]¶
Transform the WCS info in an image.
Convert image pixel coordinates to RA/Dec based on PNG image metadata or vice_versa
- Parameters
- Returns
newcoords (tuple) – Tuple of either (x, y) pixel coordinates or (RA, Dec) coordinates
- marvin.utils.general.general.downloadList(inputlist, dltype='cube', **kwargs)[source]¶
Download a list of MaNGA objects.
Uses sdss_access to download a list of objects via rsync. Places them in your local sas path mimicing the Utah SAS.
i.e. $SAS_BASE_DIR/mangawork/manga/spectro/redux
Can download cubes, rss files, maps, modelcubes, mastar cubes, png images, default maps, or the entire plate directory. dltype=`dap` is a special keyword that downloads all DAP files. It sets binmode and daptype to ‘*’
- Parameters
inputlist (list) – Required. A list of objects to download. Must be a list of plate IDs, plate-IFUs, or manga-ids
dltype ({'cube', 'maps', 'modelcube', 'dap', image', 'rss', 'mastar', 'default', 'plate'}) – Indicated type of object to download. Can be any of plate, cube, image, mastar, rss, map, modelcube, or default (default map). If not specified, the dltype defaults to cube.
release (str) – The MPL/DR version of the data to download. Defaults to Marvin config.release.
bintype (str) – The bin type of the DAP maps to download. Defaults to *
binmode (str) – The bin mode of the DAP maps to download. Defaults to *
n (int) – The plan id number [1-12] of the DAP maps to download. Defaults to *
daptype (str) – The daptype of the default map to grab. Defaults to *
dir3d (str) – The directory where the images are located. Either ‘stack’ or ‘mastar’. Defaults to *
verbose (bool) – Turns on verbosity during rsync
limit (int) – A limit to the number of items to download
test (bool) – If True, tests the download path construction but does not download
- Returns
If test=True, returns the list of full filepaths that will be downloaded
- marvin.utils.general.general.findClosestVector(point, arr_shape=None, pixel_shape=None, xyorig=None)[source]¶
Find the closest array coordinates from pixel coordinates.
Find the closest vector of array coordinates (x, y) from an input vector of pixel coordinates (x, y).
- Parameters
point – tuple Original point of interest in pixel units, order of (x,y)
arr_shape – tuple Shape of data array in (x,y) order
pixel_shape – tuple Shape of image in pixels in (x,y) order
xyorig – str Indicates the origin point of coordinates. Set to “relative” switches to an array coordinate system relative to galaxy center. Default is absolute array coordinates (x=0, y=0) = upper left corner
- Returns
minind –
- tuple
A tuple of array coordinates in x, y order
- marvin.utils.general.general.getDapRedux(release=None)[source]¶
Retrieve SAS url link to the DAP redux directory.
- Parameters
release (str) – The release version of the data to download. Defaults to Marvin config.release.
- Returns
dapredux (str) – The full redux path to the DAP MAPS
- marvin.utils.general.general.getDefaultMapPath(**kwargs)[source]¶
Retrieve the default Maps path.
Uses sdss_access Path to generate a url download link to the default MAPS file for a given MPL.
- Parameters
release (str) – The release version of the data to download. Defaults to Marvin config.release.
plate (int) – The plate id
ifu (int) – The ifu number
mode (str) – The bintype of the default file to grab, i.e. MAPS or LOGCUBE. Defaults to MAPS
daptype (str) – The daptype of the default map to grab. Defaults to SPX-GAU-MILESHC
- Returns
maplink (str) – The sas url to download the default maps file
- marvin.utils.general.general.getKeywordArgs(func)[source]¶
Gets the keyword arguments from a function or method
- Parameters
func (func) – The function or method to inspect
- Returns
A list of keyword arguments
Example
>>> import matplotlib.pyplot as plt >>> getKeywordArgs(plt.scatter) >>> ['edgecolors', 'c', 'vmin', 'linewidths', 'marker', 's', 'cmap', >>> 'verts', 'vmax', 'alpha', 'hold', 'data', 'norm']
- marvin.utils.general.general.getRequiredArgs(func)[source]¶
Gets the required arguments from a function or method
Uses this difference between arguments and defaults to indicate required versus optional arguments
- Parameters
func (func) – The function or method to inspect
- Returns
A list of required arguments
Example
>>> import matplotlib.pyplot as plt >>> getRequiredArgs(plt.scatter) >>> ['x', 'y']
- marvin.utils.general.general.getSpaxel(cube=True, maps=True, modelcube=True, x=None, y=None, ra=None, dec=None, xyorig=None, **kwargs)[source]¶
Returns the
Spaxel
matching certain coordinates.The coordinates of the spaxel to return can be input as
x, y
pixels relative to``xyorig`` in the cube, or asra, dec
celestial coordinates.This function is intended to be called by
getSpaxel()
orgetSpaxel()
, and provides shared code for both of them.- Parameters
cube (
Cube
or None or bool) – ACube
object with the DRP cube data from which the spaxel spectrum will be extracted. If None, theSpaxel
object(s) returned won’t contain spectral information.maps (
Maps
or None or bool) – Ascube
but for theMaps
object representing the DAP maps entity. If None, theSpaxel
will be returned without DAP information.modelcube (
ModelCube
or None or bool) – Ascube
but for theModelCube
object representing the DAP modelcube entity. If None, theSpaxel
will be returned without model information.x (int or array) – The spaxel coordinates relative to
xyorig
. Ifx
is an array of coordinates, the size ofx
must much that ofy
.y (int or array) – The spaxel coordinates relative to
xyorig
. Ifx
is an array of coordinates, the size ofx
must much that ofy
.ra (float or array) – The coordinates of the spaxel to return. The closest spaxel to those coordinates will be returned. If
ra
is an array of coordinates, the size ofra
must much that ofdec
.dec (float or array) – The coordinates of the spaxel to return. The closest spaxel to those coordinates will be returned. If
ra
is an array of coordinates, the size ofra
must much that ofdec
.xyorig ({'center', 'lower'}) – The reference point from which
x
andy
are measured. Valid values are'center'
, for the centre of the spatial dimensions of the cube, or'lower'
for the lower-left corner. This keyword is ignored ifra
anddec
are defined.xyorig
defaults tomarvin.config.xyorig.
kwargs (dict) – Arguments to be passed to
SpaxelBase
.
- Returns
spaxels (list) – The
Spaxel
objects for this cube/maps corresponding to the input coordinates. The length of the list is equal to the number of input coordinates.
- marvin.utils.general.general.getSpaxelXY(cube, plateifu, x, y)[source]¶
Get a spaxel from a cube in the DB.
This function is mostly intended for internal use.
- Parameters
- Returns
spaxel (SQLAlchemy object) – The SQLAlchemy spaxel with coordinates
(x, y)
.
- marvin.utils.general.general.getWCSFromPng(filename=None, image=None)[source]¶
Extract any WCS info from the metadata of a PNG image.
Extracts the WCS metadata info from the PNG optical image of the galaxy using PIL (Python Imaging Library). Converts it to an Astropy WCS object.
- marvin.utils.general.general.get_dapall_file(drpver=None, dapver=None, dapall=None)[source]¶
Check for/download the dapall file
Checks for existence of a local dapall file for the current release set. If not found, uses sdss_access to download it.
- marvin.utils.general.general.get_dapall_path(drpver, dapver)[source]¶
Returns the path to the DAPall file for
(drpver, dapver)
.
- marvin.utils.general.general.get_dapall_table(drpver=None, dapver=None, dapall=None)[source]¶
Gets the dapall table
Gets the dapall table either from cache or loads it. For releases of MPL-6 and up.
- marvin.utils.general.general.get_drpall_file(drpver=None, drpall=None)[source]¶
Check for/download the drpall file
Checks for existence of a local drpall file for the current release set. If not found, uses sdss_access to download it.
- marvin.utils.general.general.get_drpall_path(drpver)[source]¶
Returns the path to the DRPall file for
(drpver, dapver)
.
- marvin.utils.general.general.get_drpall_row(plateifu, drpver=None, drpall=None)[source]¶
Returns a dictionary from drpall matching the plateifu.
- marvin.utils.general.general.get_drpall_table(drpver=None, drpall=None, hdu='MANGA')[source]¶
Gets the drpall table
Gets the drpall table either from cache or loads it. For releases of MPL-8 and up, galaxies are in the MANGA extension, and mastar targets are in the MASTAR extension, specified with the hdu keyword. For MPLs 1-7, there is only one data extension, which is read.
- marvin.utils.general.general.get_manga_image(cube=None, drpver=None, plate=None, ifu=None, dir3d=None, local=None, public=None)[source]¶
Get a MaNGA IFU optical PNG image
- marvin.utils.general.general.get_nsa_data(mangaid, source='nsa', mode='auto', drpver=None, drpall=None)[source]¶
Returns a dictionary of NSA data from the DB or from the drpall file.
- Parameters
mangaid (str) – The mangaid of the target for which the NSA information will be returned.
source ({'nsa', 'drpall'}) – The data source. If
source='nsa'
, the full NSA catalogue from the DB will be used. Ifsource='drpall'
, the subset of NSA columns included in the drpall file will be returned.mode ({'auto', 'local', 'remote'}) – See Mode Decision Tree.
drpver (str or None) – The version of the DRP to use, if
source='drpall'
. IfNone
, uses the version set bymarvin.config.release
.drpall (str or None) – A path to the drpall file to use if
source='drpall'
. If not defined, the default drpall file matchingdrpver
will be used.
- Returns
nsa_data (dict) – A dictionary containing the columns and values from the NSA catalogue for
mangaid
.
- marvin.utils.general.general.get_plates(drpver=None, drpall=None, release=None)[source]¶
Get a list of unique plates from the drpall file
- marvin.utils.general.general.invalidArgs(func, argdict)[source]¶
Return invalid arguments from an input dictionary
- Parameters
func (func) – The function or method to inspect
argdict (dict) – The argument dictionary to test against
- Returns
A list of invalid arguments
Example
>>> import matplotlib.pyplot as plt >>> testdict = {'edgecolors': 'black', 'c': 'r', 'xlim': 5, 'xlabel': 9, 'ylabel': 'y', 'ylim': 6} >>> # test for invalid args >>> invalidArgs(plt.scatter, testdict) >>> {'xlabel', 'xlim', 'ylabel', 'ylim'}
- marvin.utils.general.general.isCallableWithArgs(func, argdict, arg_type='opt', strict=False)[source]¶
Test if the function is callable with the an input dictionary
- Parameters
func (func) – The function or method to inspect
argdict (dict) – The argument dictionary to test against
arg_type (str) – The type of arguments to test. Either (args|kwargs|req|opt). Default is required.
strict (bool) – If True, validates input dictionary against both missing and invalid keyword arguments. Default is False
- Returns
Boolean indicating whether the function is callable
Example
>>> import matplotlib.pyplot as plt >>> testdict = {'edgecolors': 'black', 'c': 'r', 'xlim': 5, 'xlabel': 9, 'ylabel': 'y', 'ylim': 6} >>> # test for invalid args >>> isCallableWithArgs(plt.scatter, testdict) >>> False
- marvin.utils.general.general.mangaid2plateifu(mangaid, mode='auto', drpall=None, drpver=None)[source]¶
Return the plate-ifu for a certain mangaid.
Uses either the DB or the drpall file to determine the plate-ifu for a mangaid. If more than one plate-ifu are available for a certain ifu, and
mode='drpall'
, the one with the higher SN2 (calculated as the sum of redSN2 and blueSN2) will be used. Ifmode='db'
, the most recent one will be used.- Parameters
mangaid (str) – The mangaid for which the plate-ifu will be returned.
mode ({'auto', 'drpall', 'db', 'remote'}) – If
'drpall'
or'db'
, the drpall file or the local database, respectively, will be used. If'remote'
, a request to the API will be issued. If'auto'
, the local modes will be tried before the remote mode.drpall (str or None) – The path to the drpall file to use. If None, the file in
config.drpall
will be used.drpver (str or None) – The DRP version to use. If None, the one in
config.drpver
will be used. Ifdrpall
is defined, this value is ignored.
- Returns
plateifu (str) – The plate-ifu string for the input
mangaid
.
- marvin.utils.general.general.map_bins_to_column(column, indices)[source]¶
Maps a dictionary of array indices to column data
Takes a given data column and a dictionary of indices (see the indices key from output of the histgram data in
marvin.utils.plot.scatter.hist()
), and produces a dictionary with the data values from column mapped in individual bins.- Parameters
- Returns
A dictionary containing, for each binid, a list of column data in that bin.
Example
>>> >>> # provide a list of data in each bin of an output histogram >>> x = np.random.random(10)*10 >>> hdata = hist(x, bins=3, return_fig=False) >>> inds = hdata['indices'] >>> pmap = map_bins_to_column(x, inds) >>> OrderedDict([(1, >>> [2.5092488009906235, >>> 1.7494530589363955, >>> 2.5070840461208754, >>> 2.188355400587354, >>> 2.6987990403658992, >>> 1.6023553861428441]), >>> (3, [7.9214280403215875, 7.488908995456573, 7.190598204420587]), >>> (4, [8.533028236560906])])
- marvin.utils.general.general.map_dapall(header, row)[source]¶
Retrieves a dictionary of DAPall db column names
For a given row in the DAPall file, returns a dictionary of corresponding DAPall database columns names with the appropriate values.
- Parameters
header (Astropy header) – The primary header of the DAPall file
row (recarray) – A row of the DAPall binary table data
- Returns
A dictionary with db column names as keys and row data as values
Example
>>> hdu = fits.open('dapall-v2_3_1-2.1.1.fits') >>> header = hdu[0].header >>> row = hdu[1].data[0] >>> dbdict = map_dapall(header, row)
- marvin.utils.general.general.memory_usage(where)[source]¶
Print out a basic summary of memory usage.
- Parameters
where (str) – A string description of where in the code you are summarizing memory usage
- marvin.utils.general.general.missingArgs(func, argdict, arg_type='args')[source]¶
Return missing arguments from an input dictionary
- Parameters
- Returns
A list of missing arguments
Example
>>> import matplotlib.pyplot as plt >>> testdict = {'edgecolors': 'black', 'c': 'r', 'xlim': 5, 'xlabel': 9, 'ylabel': 'y', 'ylim': 6} >>> # test for missing required args >>> missginArgs(plt.scatter, testdict) >>> {'x', 'y'} >>> # test for missing optional args >>> missingArgs(plt.scatter, testdict, arg_type='opt') >>> ['vmin', 'linewidths', 'marker', 's', 'cmap', 'verts', 'vmax', 'alpha', 'hold', 'data', 'norm']
- marvin.utils.general.general.parseIdentifier(galid)[source]¶
Determine if a string input is a plate, plateifu, or manga-id.
Parses a string object id and determines whether it is a plate ID, a plate-IFU, or MaNGA-ID designation.
- Parameters
galid (str) – The string of an id name to parse
- Returns
idtype (str) – String indicating either plate, plateifu, mangaid, or None
- marvin.utils.general.general.target_is_mastar(plateifu, drpver=None, drpall=None)[source]¶
Check if a target is bright-time MaStar target
Uses the local drpall file to check if a plateifu is a MaStar target
- marvin.utils.general.general.target_is_observed(mangaid, mode='auto', source='nsa', drpall=None, drpver=None)[source]¶
Check if a MaNGA target has been observed or not
See
target_status()
for full documentation.- Returns
True if the target has been observed.
- marvin.utils.general.general.target_status(mangaid, mode='auto', source='nsa', drpall=None, drpver=None)[source]¶
Check the status of a MaNGA target
Given a mangaid, checks the status of a target. Will check if target exists in the NSA catalog (i.e. is a proper target) and checks if target has a corresponding plate-IFU designation (i.e. has been observed).
Returns a string status indicating if a target has been observed, has not yet been observed, or is not a valid MaNGA target.
- Parameters
mangaid (str) – The mangaid of the target to check for observed status
mode ({'auto', 'drpall', 'db', 'remote', 'local'}) – See mode in
mangaid2plateifu()
andget_nsa_data()
.source ({'nsa', 'drpall'}) – The NSA catalog data source. See source in
get_nsa_data()
.drpall (str or None) – The drpall file to use. See drpall in
mangaid2plateifu()
andget_nsa_data()
.drpver (str or None) – The DRP version to use. See drpver in
mangaid2plateifu()
andget_nsa_data()
.
- Returns
A status of “observed”, “not yet observed”, or “not valid target”
- marvin.utils.general.general.temp_setattr(ob, attrs, new_values)[source]¶
Temporarily set attributed on an object
Temporarily set an attribute on an object for the duration of the context manager.
- Parameters
Example
>>> c = Cube(plateifu='8485-1901') >>> print('before', c.mangaid) >>> with temp_setattr(c, 'mangaid', None): >>> # do stuff >>> print('new', c.mangaid) >>> print('after' c.mangaid) >>> >>> # Output >>> before '1-209232' >>> new None >>> after '1-209232' >>>
- marvin.utils.general.general.turn_off_ion(show_plot=True)[source]¶
Turns off the Matplotlib plt interactive mode
Context manager to temporarily disable the interactive Matplotlib plotting functionality. Useful for only returning Figure and Axes objects
- Parameters
show_plot (bool) – If True, turns off the plotting
Example
>>> >>> with turn_off_ion(show_plot=False): >>> do_some_stuff >>>
BPT Diagrams¶
- marvin.utils.dap.bpt.bpt_kewley06(maps, snr_min=3, return_figure=True, use_oi=True, **kwargs)[source]¶
Returns a classification of ionisation regions, as defined in Kewley+06.
Makes use of the classification system defined by Kewley et al. (2006) to return classification masks for different ionisation mechanisms. If
return_figure=True
, produces and returns a matplotlib figure with the classification plots (based on Kewley+06 Fig. 4) and the 2D spatial distribution of classified spaxels (i.e., a map of the galaxy in which each spaxel is colour-coded based on its emission mechanism).While it is possible to call this function directly, its normal use will be via the
get_bpt()
method.- Parameters
maps (a Marvin
Maps
object) – The Marvin Maps object that contains the emission line maps to be used to determine the BPT classification.snr_min (float or dict) – The signal-to-noise cutoff value for the emission lines used to generate the BPT diagram. If
snr_min
is a single value, that signal-to-noise will be used for all the lines. Alternatively, a dictionary of signal-to-noise values, with the emission line channels as keys, can be used. E.g.,snr_min={'ha': 5, 'nii': 3, 'oi': 1}
. If some values are not provided, they will default toSNR>=3
. Note that the valuesii
will be applied to both[SII 6718]
and[SII 6732]
.return_figure (bool) – If
True
, it also returns the matplotlib figure_ of the BPT diagram plot, which can be used to modify the style of the plot.use_oi (bool) – If
True
, uses the OI diagnostic diagram for spaxel classification.
- Returns
bpt_return –
bpt_kewley06
returns a dictionary of dictionaries of classification masks. The classification masks (not to be confused with bitmasks) are boolean arrays with the same shape as the Maps or Cube (without the spectral dimension) that can be used to select spaxels belonging to a certain excitation process (e.g., star forming). The returned dictionary has the following keys:'sf'
(star forming),'comp'
(composite),'agn'
,'seyfert'
,'liner'
,'invalid'
(spaxels that are masked out at the DAP level), and'ambiguous'
(good spaxels that do not fall in any classification or fall in more than one). Each key provides access to a new dictionary with keys'nii'
(for the constraints in the diagram NII/Halpha vs OIII/Hbeta),'sii'
(SII/Halpha vs OIII/Hbeta),'oi'
(OI/Halpha vs OIII/Hbeta; only ifuse_oi=True
), and'global'
, which applies all the previous constraints at once. The'ambiguous'
mask only contains the'global'
subclassification, while the'comp'
dictionary only contains'nii'
.'nii'
is not available for'seyfert'
and'liner'
. All the global masks are unique (a spaxel can only belong to one of them) with the exception of'agn'
, which intersects with'seyfert'
and'liner'
. Additionally, ifreturn_figure=True
,bpt_kewley06
will also return the matplotlib figure for the generated plot, and a list of axes for each one of the subplots.
Example
>>> maps_8485_1901 = Maps(plateifu='8485-1901') >>> bpt_masks, fig, axes = bpt_kewley06(maps_8485_1901)
Gets the global mask for star forming spaxels
>>> sf = bpt_masks['sf']['global']
Gets the seyfert mask based only on the SII/Halpha vs OIII/Hbeta diagnostics
>>> seyfert_sii = bpt_masks['seyfert']['sii']
- marvin.utils.dap.bpt.kewley_sf_nii(log_nii_ha)[source]¶
Star forming classification line for log([NII]/Ha).
- marvin.utils.dap.bpt.kewley_sf_sii(log_sii_ha)[source]¶
Star forming classification line for log([SII]/Ha).
- marvin.utils.dap.bpt.kewley_sf_oi(log_oi_ha)[source]¶
Star forming classification line for log([OI]/Ha).
- marvin.utils.dap.bpt.kewley_comp_nii(log_nii_ha)[source]¶
Composite classification line for log([NII]/Ha).
Image Utilities¶
- marvin.utils.general.images.getImagesByList(inputlist, download=False, mode=None, as_url=None, verbose=None, release=None)[source]¶
Get all images from a list of ids
Deprecated since version 2.3.0: Use
marvin.utils.general.images.get_images_by_list
instead.Retrieve a list of images from either your local filesystem SAS or the Utah SAS. Optionally can download the images by rsync using sdss_access.
When as_url is False, both local and remote modes will allow you to access the full path to the images in your local SAS. WHen as_url is True, local mode generates the Utah SAS url links, while remote mode generates the Utah SAS rsync links.
Auto mode defaults to remote.
- Parameters
inputlist (list) – A list of plate-ifus or mangaids for the images you want to retrieve. Required.
download (bool) – Set to download the images from the SAS. Only works in remote mode.
mode ({'local', 'remote', 'auto'}) – The load mode to use. See Mode secision tree. the cube exists.
as_url (bool) – Convert the list of images to use the SAS url (mode=local) or the SAS rsync url (mode=remote)
verbose (bool) – Turns on verbosity during rsync
release (str) – The release version of the images to return
- Returns
listofimages (list) – The list of images you have requested
- marvin.utils.general.images.getImagesByPlate(plateid, download=False, mode=None, as_url=None, verbose=None, release=None)[source]¶
Get all images belonging to a given plate ID
Deprecated since version 2.3.0: Use
marvin.utils.general.images.get_images_by_plate
instead.Retrieve all images belonging to a given plate ID from either your local filesystem SAS or the Utah SAS. Optionally can download the images by rsync using sdss_access.
When as_url is False, both local and remote modes will allow you to access the full path to the images in your local SAS. WHen as_url is True, local mode generates the Utah SAS url links, while remote mode generates the Utah SAS rsync links.
Auto mode defaults to remote.
- Parameters
plateid (int) – The plate ID to retrieve the images for. Required.
download (bool) – Set to download the images from the SAS
mode ({'local', 'remote', 'auto'}) – The load mode to use. See Mode secision tree. the cube exists.
as_url (bool) – Convert the list of images to use the SAS url (mode=local) or the SAS rsync url (mode=remote)
verbose (bool) – Turns on verbosity during rsync
release (str) – The release version of the images to return
- Returns
listofimages (list) – The list of images
- marvin.utils.general.images.getRandomImages(num=10, download=False, mode=None, as_url=None, verbose=None, release=None)[source]¶
Get a list of N random images from SAS
Deprecated since version 2.3.0: Use
marvin.utils.general.images.get_random_images
instead.Retrieve a random set of images from either your local filesystem SAS or the Utah SAS. Optionally can download the images by rsync using sdss_access.
When as_url is False, both local and remote modes will allow you to access the full path to the images in your local SAS. WHen as_url is True, local mode generates the Utah SAS url links, while remote mode generates the Utah SAS rsync links.
Auto mode defaults to remote.
- Parameters
num (int) – The number of images to retrieve
download (bool) – Set to download the images from the SAS
mode ({'local', 'remote', 'auto'}) – The load mode to use. See Mode secision tree. the cube exists.
as_url (bool) – Convert the list of images to use the SAS url (mode=local) or the SAS rsync url (mode=remote)
verbose (bool) – Turns on verbosity during rsync
release (str) – The release version of the images to return
- Returns
listofimages (list) – The list of images
- marvin.utils.general.images.get_images_by_list(inputlist, release=None, download=None)[source]¶
Get Images by List
Gets Marvin Images by an input list. Optionally can download them in bulk.
- marvin.utils.general.images.get_images_by_plate(plateid, download=None, release=None)[source]¶
Get Images by Plate
Gets Marvin Images by a plate id. Optionally can download them in bulk.
- marvin.utils.general.images.get_random_images(num, release=None, download=None)[source]¶
Get a random set of Images
Gets a random set of Marvin Images. Optionally can download them in bulk.
- marvin.utils.general.images.showImage(path=None, plateifu=None, release=None, return_image=True, show_image=True, mode=None)[source]¶
Crudely and coarsely show a galaxy image that has been downloaded
Deprecated since version 2.3.0: Use
marvin.tools.image.Image
orshow_image()
instead.This utility function quickly allows you to display a PNG IFU image that is located in your local SAS or from the remote Utah SAS. A PIL Image object is also returned which allows you to manipulate the image after the fact. See Displaying Images for example usage.
Either the path or plateifu keyword is required.
- Parameters
path (str) – A string filepath to a local IFU image
plateifu (str) – A plateifu designation used to look for the IFU image in your local SAS
return_image (bool) – If
True
, returns the PIL Image object for image manipulation. Default isTrue
.show_image (bool) – If
True
, shows the requested image that is opened internallymode ({'local', 'remote', 'auto'}) – The load mode to use. See Mode secision tree.
release (str) – The release version of the images to return
- Returns
image (PIL Image or None) – If return_image is set, returns a PIL Image object to allow for image manipulation, else returns None.
- marvin.utils.general.images.show_image(input, **kwargs)[source]¶
Shows a Marvin Image
This is a thin wrapper for
marvin.tools.image.Image.show()
Seemarvin.tools.image.Image
for a full list of inputs and keywords. This is meant to replace showImage
DAP DataModel Utilities¶
Map Plotting Utilities¶
- marvin.utils.plot.map.mask_low_snr(value, ivar, snr_min)[source]¶
Mask spaxels with a signal-to-noise ratio below some threshold.
- Parameters
value (array) – Value for image.
ivar (array) – Inverse variance of value.
snr_min (float) – Minimum signal-to-noise for keeping a valid measurement.
- Returns
array – Boolean array for mask (i.e., True corresponds to value to be masked out).
- marvin.utils.plot.map.mask_neg_values(value)[source]¶
Mask spaxels with negative values.
This method is primarily for using a logarithmic colorbar.
- Parameters
value (array) – Value for image.
- Returns
array – Boolean array for mask (i.e., True corresponds to value to be masked out).
- marvin.utils.plot.map.plot(*args, **kwargs)[source]¶
Make single panel map or one panel of multi-panel map plot.
Please see the Plotting Tutorial for examples.
- Parameters
dapmap (marvin.tools.quantities.Map) – Marvin Map object. Default is
None
.value (array) – Data array. Default is
None
.ivar (array) – Inverse variance array. Default is
None
.mask (array) – Mask array. Default is
None
.cmap (str) – Colormap (see Default Plotting Parameters for defaults).
percentile_clip (tuple-like) – Percentile clip (see Default Plotting Parameters for defaults).
sigma_clip (float) – Sigma clip. Default is
False
.cbrange (tuple-like) – If
None
, set automatically. Default isNone
.symmetric (bool) – Draw a colorbar that is symmetric around zero (see Default Plotting Parameters for default).
snr_min (float) – Minimum signal-to-noise for keeping a valid measurement (see Default Plotting Parameters for default).
log_cb (bool) – Draw a log normalized colorbar. Default is
False
.title (str) – If
None
, set automatically from property (and channel) name(s). For no title, set to ‘’. Default isNone
.title_mode (str) – The mode to generate a title automatically, if
title
is not set. Usually'string'
or'latex'
. Default is'string'
. Seeto_string()
for details.cblabel (str) – If
None
, set automatically from unit. For no colorbar label, set to ‘’. Default isNone
.sky_coords (bool) – If
True
, show plot in sky coordinates (i.e., arcsec), otherwise show in spaxel coordinates. Default isFalse
.use_masks (bool, str, list) – Use DAP bitmasks. If
True
, use the recommended DAP masks. Otherwise provide a mask name as a string or multiple mask names as a list of strings. Default isTrue
.plt_style (str) – Matplotlib style sheet to use. Default is ‘seaborn-darkgrid’.
fig (matplotlib Figure object) – Use if creating subplot of a multi-panel plot. Default is
None
.ax (matplotlib Axis object) – Use if creating subplot of a multi-panel plot. Default is
None
.patch_kws (dict) – Keyword args to pass to matplotlib.patches.Rectangle. Default is
None
.imshow_kws (dict) – Keyword args to pass to ax.imshow. Default is
None
.cb_kws (dict) – Keyword args to set and draw colorbar. Default is
None
.return_cb (bool) – Return colorbar axis. Default is
False
.return_cbrange (bool) – Return colorbar range without drawing plot. Default is
False
.
- Returns
fig, ax (tuple) – matplotlib.figure, matplotlib.axes
Example
>>> import marvin.utils.plot.map as mapplot >>> maps = Maps(plateifu='8485-1901') >>> ha = maps['emline_gflux_ha_6564'] >>> fig, ax = mapplot.plot(dapmap=ha)
Colorbar Plotting Utilities¶
Functions for colorbars.
- marvin.utils.plot.colorbar.linearlab()[source]¶
Make linearlab color map.
Description of linearlab palatte.
- Returns
cm, cm_r (tuple) – matplotlib.cm object and reversed matplotlib.cm object
Maskbit Utilities¶
- class marvin.utils.general.maskbit.Maskbit(name, schema=None, description=None)[source]¶
Bases:
object
A class representing a maskbit.
- Parameters
- get_mask(labels, mask=None, dtype=<class 'int'>)[source]¶
Create mask from a list of labels.
If
dtype
isint
, thenget_mask
can effectively perform an OR or AND operation. However, ifdtype
isbool
, thenget_mask
does an OR.- Parameters
- Returns
array – Mask for given labels.
Example
>>> maps = Maps(plateifu='8485-1901') >>> ha = maps['emline_gflux_ha_6564'] >>> ha.pixmask.get_mask(['NOCOV', 'LOWCOV']) array([[3, 3, 3, ..., 3, 3, 3], ..., [3, 3, 3, ..., 3, 3, 3]])
>>> ha.pixmask.get_mask(['NOCOV', 'LOWCOV'], dtype=bool) array([[ True, True, True, ..., True, True, True], ..., [ True, True, True, ..., True, True, True]], dtype=bool)
- labels_to_bits(labels)[source]¶
Convert bit labels into bits.
- Parameters
- Returns
list – Bits that correspond to the labels.
Example
>>> maps = Maps(plateifu='8485-1901') >>> ha = maps['emline_gflux_ha_6564'] >>> ha.pixmask.labels_to_bits('DONOTUSE') [30]
>>> ha.pixmask.labels_to_value(['NOCOV', 'LOWCOV']) [0, 1]
- labels_to_value(labels)[source]¶
Convert bit labels into a bit value.
Example
>>> maps = Maps(plateifu='8485-1901') >>> ha = maps['emline_gflux_ha_6564'] >>> ha.pixmask._labels_to_value('DONOTUSE') 1073741824
>>> ha.pixmask._labels_to_value(['NOCOV', 'LOWCOV']) 3
- values_to_bits(values=None)[source]¶
Convert mask values to a list of bits set.
- Parameters
values (int or array) – Mask values. If
None
, apply to entireMaskbit.mask
array. Default isNone
.- Returns
list – Bits that are set.
Example
>>> maps = Maps(plateifu='8485-1901') >>> ha = maps['emline_gflux_ha_6564'] >>> ha.pixmask.values_to_bits() [[[0, 1, 4, 30], [0, 1, 4, 30], ... [0, 1, 4, 30]]]
- values_to_labels(values=None)[source]¶
Convert mask values to a list of the labels of bits set.
- Parameters
values (int or array) – Mask values. If
None
, apply to entireMaskbit.mask
array. Default isNone
.- Returns
list – Bits that are set.
Example
>>> maps = Maps(plateifu='8485-1901') >>> ha = maps['emline_gflux_ha_6564'] >>> ha.pixmask.values_to_labels() [[['NOCOV', 'LOWCOV', 'NOVALUE', 'DONOTUSE'], ['NOCOV', 'LOWCOV', 'NOVALUE', 'DONOTUSE'], ... ['NOCOV', 'LOWCOV', 'NOVALUE', 'DONOTUSE']]]
- property bits¶
- property labels¶
Scatter/Histogram Plotting Utilities¶
- marvin.utils.plot.scatter.compute_stats(data)[source]¶
Compute some statistics given a data array
Computes some basic statistics given a data array, excluding NaN values. Computes and returns the following Numpy statistics: mean, standard deviation, median, and the 10th, 25th, 75th, and 90th percentiles.
- Parameters
data (list|ndarray) – A list or Numpy array of data
- Returns
A dictionary of statistics values
- marvin.utils.plot.scatter.hist(arr, mask=None, fig=None, ax=None, bins=None, **kwargs)[source]¶
Create a histogram of an array
Plots a histogram of an input column of data. Input can be a list or a Numpy array. Converts the input into a Numpy MaskedArray, applying the optional mask. If no mask is supplied, it masks any NaN values. This uses Astropy’s enhanced hist function under the hood. Accepts all the same keyword arguments as matplotlib hist method.
- Parameters
arr (list|ndarray) – An array of data to plot with. Required.
mask (ndarray) – A mask to use on the data, applied to the data in a Numpy Masked Array.
fig (plt.fig) – An optional matplotlib figure object
ax (plt.ax) – An optional matplotlib axis object
bins (int) – The number of bins to use. Default is a scott binning scheme.
xlabel (str|Marvin Column) – The x axis label or a Marvin DataModel Property or QueryParameter to use for display
ylabel (str) – The y axis label
title (str) – The plot title
rotate_title (bool) – If True, moves the title text to the right y-axis during a horizontal histogram. Default is False.
return_figure (bool) – If True, return the figure and axis object. Default is True.
kwargs (dict) – Any other keyword arguments to be passed to matplotlib.pyplot.hist.
- Returns
tuple – histogram data, matplotlib figure, and axis objects.
The histogram data returned is a dictionary containing:
{ 'bins': The number of bins used, 'counts': A list of the count of objects within each bin, 'binedges': A list of the left binedge used in defining each bin, 'binids': An array of the same shape as input data, containing the binid of each element, 'indices': A dictionary of a list of array indices within each bin }
Example
>>> # histogram some random data >>> from marvin.utils.plot.scatter import hist >>> import numpy as np >>> x = np.random.random(100) >>> hist_data, fig, ax = hist(x)
- marvin.utils.plot.scatter.plot(x, y, **kwargs)[source]¶
Create a scatter plot given two columns of data
Creates a Matplotlib plot using two input arrays of data. Creates either a Matplotlib scatter plot, hexbin plot, or scatter density plot depending on the size of the input data. For data with < 1000 values, creates a scatter plot. For data with values between 1000 and 500,000, creates a hexbin plot. For data with > 500,000 values, creates a scatter density plot.
By default, will also create and display histograms for the x and y data. This can be disabled setting the “with_hist” keyword to False, or “x”, or “y” for displaying only that column. Accepts all the same keyword arguments as matplotlib scatter, hexbin, and hist methods.
See scatter-density See matplotlib.pyplot.scatter See matplotlib.pyplot.hexbin
- Parameters
data (Pandas dataframe) – Optional Pandas Dataframe. x, y specify string column names in the dataframe
xmask (ndarray) – A mask to apply to the x-array of data
ymask (ndarray) – A mask to apply to the y-array of data
with_hist (bool|str) – If True, creates the plot with both x,y histograms. False, disables it. If ‘x’ or ‘y’, only creates that histogram. Default is True.
hist_axes_visible (bool) – If True, disables the x-axis ticks for each histogram. Default is True.
xlim (tuple) – A tuple limited the range of the x-axis
ylim (tuple) – A tuple limited the range of the y-axis
xlabel (str|Marvin column) – The x axis label or a Marvin DataModel Property or QueryParameter to use for display
ylabel (str|Marvin column) – The y axis label or a Marvin DataModel Property or QueryParameter to use for display
bins (int|tuple) – A number or tuple specifying the number of bins to use in the histogram. Default is 50. An integer number is adopted for both x and y bins. A tuple is used to customize per axis.
return_figure (bool) – If True, return the figure and axis object. Default is True.
kwargs (dict) –
Any other keyword arguments to be passed to matplotlib.pyplot.scatter or matplotlib.pyplot.hist or matplotlib.pyplot.hexbin.
- Returns
A tuple of the matplotlib figure, axes, and histogram data (if returned)
Example
>>> # create a scatter plot >>> import numpy as np >>> from marvin.utils.scatter import plot >>> x = np.random.random(100) >>> y = np.random.random(100) >>> plot(x, y)
Bundle Utilities¶
- class marvin.utils.general.bundle.Bundle(ra, dec, size=127, use_envelope=True, local=None, plateifu=None, **kwargs)[source]¶
Bases:
object
The location, size, and shape of a MaNGA IFU bundle.
A bundle of a given size at the RA/Dec coordinates.
Setting envelope creates the hexagon at the outer boundry of the fibers, otherwise the hexagon runs through the centers of the outer fibers.
- Parameters
ra (float) – The Right Ascension of the target
dec (float) – The Declination of the target
size (int) – The fiber size of the IFU, e.g. 19 or 127
plateifu (str) – The plateifu of the target
use_envelope (bool) – Expands the hexagon area to include an envelope surrounding the hex border
local (bool) – If True, grabs the fiducial metrology file from a local MANGACORE
- Variables
fibers (ndarray) – An Nx3 array of IFU fiber coordinates
skies (ndarray) – An Nx2 array of sky fiber coordinates. Default is unloaded. Use
get_sky_coordinates()
to load.hexagon (ndarray) – An Nx2 array of coordinates defining the hexagon vertices
- create_DS9_regions(outputFile=None)[source]¶
Writes out the bundle positions into a DS9 region file
- Parameters
outputFile (str) – The output filename
- get_fiber_coordinates(size=None)[source]¶
Returns the RA, Dec coordinates for each fiber.
- Parameters
size (int) – The IFU size. This extracts only the fibers for the given size
- Returns
An Nx3 numpy array, each row containing [fiberid, RA, Dec]
- class marvin.utils.general.bundle.Cutout(ra, dec, width, height, scale=None, **kwargs)[source]¶
Bases:
object
A Generic SDSS Cutout Image
Tool which allows to generate an image using the SDSS Skyserver Image Cutout service. See http://skyserver.sdss.org/public/en/help/docs/api.aspx#imgcutout for details.
- Parameters
ra (float) – The central Right Ascension of the cutout
dec (float) – The central Declination of the cutout
width (int) – width of cutout in arcsec
height (int) – height in cutout in arcsec
scale (float) – pixel scale in arcsec/pixel. Default is 0.198 “/pix.
kwargs –
Allowed boolean keyword arguments to the SDSS Image Cutout Service. Set desired keyword parameters to True to enable.
- Available kwargs are:
’photo’: PhotoObjs
’bound’: BoundingBox
’masks’: Masks
’grid’: Grid
’outline’: Outline
’target’: TargetObjs
’fields’: Fields
’invert’: Invert Image
’spectra’: SpecObjs
’label’: Label
’plates’: Plates
- Variables