Marvin Tools Reference

Cube

class marvin.tools.cube.Cube(input=None, filename=None, mangaid=None, plateifu=None, mode=None, data=None, release=None, drpall=None, download=None, nsa_source='auto')[source]

Bases: marvin.core.core.MarvinToolsClass, marvin.core.core.NSAMixIn

A class to interface with MaNGA DRP data cubes.

This class represents a fully reduced DRP data cube, initialised either from a file, a database, or remotely via the Marvin API.

See MarvinToolsClass for a list of parameters. In addition to the attributes defined there, the following ones are also defined

Variables:
download()[source]

Downloads the cube using sdss_access - Rsync,

getAperture(coords, radius, mode='pix', weight=True, return_type='mask')[source]

Returns the spaxel in a circular or elliptical aperture.

Returns either a mask of the same shape as the cube with the spaxels within an aperture, or the integrated spaxel from combining the spectra for those spaxels.

The centre of the aperture is defined by coords, which must be a tuple of (x,y) (if mode='pix') or (ra,dec) coordinates (if mode='sky'). radius defines the radius of the circular aperture, or the parameters of the aperture ellipse.

If weight=True, the returned mask indicated the fraction of the spaxel encompassed by the aperture, ranging from 0 for spaxels not included to 1 for pixels totally included in the aperture. This weighting is used to return the integrated spaxel.

Parameters:
  • coords (tuple) – Either the (x,y) or (ra,dec) coordinates of the centre of the aperture.
  • radius (float or tuple) – If a float, the radius of the circular aperture. If mode='pix' it must be the radius in pixels; if mode='sky', radius is in arcsec. To define an elliptical aperture, radius must be a 3-element tuple with the first two elements defining the major and minor semi-axis of the ellipse, and the third one the position angle in degrees from North to East.
  • mode ({'pix', 'sky'}) – Defines whether the values in coords and radius refer to pixels in the cube or angles on the sky.
  • weight (bool) – If True, the returned mask or integrated spaxel will be weighted by the fractional pixels in the aperture.
  • return_type ({'mask', 'mean', 'median', 'sum', 'spaxels'}) – The type of data to be returned.
Returns:

result – If return_type='mask', this methods returns a 2D mask with the shape of the cube indicating the spaxels included in the aperture and, if appliable, their fractional contribution to the aperture. If spaxels, both the mask (flattened to a 1D array) and the Spaxel included in the aperture are returned. mean, median, or sum will allow arithmetic operations with the spaxels in the aperture in the future.

Example

To get the mask for a circular aperture centred in spaxel (5, 7) and with radius 5 spaxels

>>> mask = cube.getAperture((5, 7), 5)
>>> mask.shape
(34, 34)

If you want to get the spaxels associated with that mask

>>> mask, spaxels = cube.getAperture((5, 7), 5, return_type='spaxels')
>>> len(spaxels)
15
getMaps(**kwargs)[source]

Retrieves the DAP Maps for this cube.

If called without additional kwargs, getMaps() will initilise the Maps using the plateifu of this Cube. Otherwise, the kwargs will be passed when initialising the Maps.

getSpaxel(x=None, y=None, ra=None, dec=None, properties=True, models=False, **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 as ra, dec celestial coordinates.

Parameters:
  • x,y (int or array) – The spaxel coordinates relative to xyorig. If x is an array of coordinates, the size of x must much that of y.
  • ra,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 of ra must much that of dec.
  • xyorig ({'center', 'lower'}) – The reference point from which x and y 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 if ra and dec are defined. xyorig defaults to marvin.config.xyorig.
  • properties (bool) – If True, the spaxel will be initiated with the DAP properties from the default Maps matching this cube.
  • models (ModelCube or None or bool) – A ModelCube object representing the DAP modelcube entity. If None, the Spaxel will be returned without model information. Default is False.
Returns:

spaxels (list) – The Spaxel objects for this cube corresponding to the input coordinates. The length of the list is equal to the number of input coordinates.

dispersion

Returns a DataCube object with the dispersion.

dispersion_prepixel

Returns a DataCube object with the prepixel dispersion.

flux

Returns a DataCube object with the flux.

manga_target1

Return MANGA_TARGET1 flag.

manga_target2

Return MANGA_TARGET2 flag.

manga_target3

Return MANGA_TARGET3 flag.

pixmask

Return the DRP3PIXMASK flag.

quality_flag

Return ModelCube DAPQUAL flag.

spectral_resolution

Returns a Spectrum with the spectral dispersion.

spectral_resolution_prepixel

Returns a Spectrum with the prepixel spectral dispersion.

target_flags

Bundle MaNGA targeting flags.

Plate

class marvin.tools.plate.Plate(input=None, filename=None, mangaid=None, plateifu=None, mode=None, data=None, release=None, plate=None, download=None, nocubes=None)[source]

Bases: marvin.core.core.MarvinToolsClass, marvin.utils.general.structs.FuzzyList

A class to interface with MaNGA Plate.

This class represents a Plate, initialised either from a file, a database, or remotely via the Marvin API. The class inherits from Python’s list class, and is defined as a list of Cube objects. As it inherits from list, it can do all the standard Python list operations.

When instanstantiated, Marvin Plate will attempt to discover and load all the Cubes associated with this plate.

Parameters:
  • plate (str) – The plate id of the Plate to load.
  • plateifu (str) – The plate-ifu of the Plate to load
  • filename (str) – The path of the file containing the data cube to load.
  • mode ({'local', 'remote', 'auto'}) – The load mode to use. See Mode secision tree..
  • release (str) – The MPL/DR version of the data to use.
  • nocubes (bool) – Set this to turn off the Cube loading
Variables:
  • cubeXXXX (object) – The Marvin Cube object for the given ifu, e.g. cube1901 refers to the Cube for plateifu 8485-1901
  • plate/plateid (int) – The plate id for this plate
  • cartid (str) – The cart id for this plate
  • designid (int) – The design id for this plate
  • ra (float) – The RA of the plate center
  • dec (float) – The declination of the plate center
  • dateobs (str) – The date of observation for this plate
  • surveymode (str) – The survey mode for this plate
  • isbright (bool) – True if this is a bright time plate
Returns:

plate – An object representing the Plate entity. The object is a list of Cube objects, one for each IFU cube in the Plate entity.

Example

>>> from marvin.tools.plate import Plate
>>> plate = Plate(plate=8485)
>>> print(plate)
>>> <Marvin Plate (plate=8485, n_cubes=17, mode='local', data_origin='db')>
>>>
>>> print('Cubes found in this plate: {0}'.format(len(plate)))
>>> Cubes found in this plate: 4
>>>
>>> # access the plate via index to access the individual cubes
>>> plate[0]
>>> <Marvin Cube (plateifu='8485-12701', mode='local', data_origin='db')>
>>>
>>> # or by name
>>> plate['12702']
>>> <Marvin Cube (plateifu='8485-12702', mode='local', data_origin='db')>
>>>

RSS

class marvin.tools.rss.RSS(*args, **kwargs)[source]

Bases: marvin.core.core.MarvinToolsClass, list

A class to interface with MaNGA RSS data.

This class represents a fully reduced RSS file, initialised either from a file, a database, or remotely via the Marvin API. The class inherits from Python’s list class, and is defined as a list of RSSFiber objects.

Parameters:
  • filename (str) – The path of the file containing the RSS to load.
  • mangaid (str) – The mangaid of the RSS to load.
  • plateifu (str) – The plate-ifu of the RSS to load (either mangaid or plateifu can be used, but not both).
  • mode ({'local', 'remote', 'auto'}) – The load mode to use. See Mode secision tree.
  • nsa_source ({'auto', 'drpall', 'nsa'}) – Defines how the NSA data for this object should loaded when RSS.nsa is first called. If drpall, the drpall file will be used (note that this will only contain a subset of all the NSA information); if nsa, the full set of data from the DB will be retrieved. If the drpall file or a database are not available, a remote API call will be attempted. If nsa_source='auto', the source will depend on how the RSS object has been instantiated. If the cube has RSS.data_origin='file', the drpall file will be used (as it is more likely that the user has that file in their system). Otherwise, nsa_source='nsa' will be assumed. This behaviour can be modified during runtime by modifying the RSS.nsa_mode with one of the valid values.
  • release (str) – The MPL/DR version of the data to use.
Returns:

rss – An object representing the RSS entity. The object is a list of RSSFiber objects, one for each fibre in the RSS entity.

download()[source]

Downloads the cube using sdss_access - Rsync

class marvin.tools.rss.RSSFiber(*args, **kwargs)[source]

Bases: marvin.tools.quantities.spectrum.Spectrum

A class to represent a MaNGA RSS fiber.

This class is basically a subclass of Spectrum with additional functionality. It is not intended to be initialised directly, but via the RSS._initFibers() method.

Parameters:
  • args – Arguments to pass to Spectrum for initialisation.
  • kwargs – Keyword arguments to pass to Spectrum for initialisation.
Returns:

rssfiber – An object representing the RSS fiber entity.

Maps

class marvin.tools.maps.Maps(input=None, filename=None, mangaid=None, plateifu=None, mode=None, data=None, release=None, drpall=None, download=None, nsa_source='auto', bintype=None, template=None, template_kin=None)[source]

Bases: marvin.core.core.MarvinToolsClass, marvin.core.core.NSAMixIn, marvin.core.core.DAPallMixIn

A class that represents a DAP MAPS file.

Provides access to the data stored in a DAP MAPS file. In addition to the parameters and variables defined for MarvinToolsClass, the following parameters and attributes are specific to Maps.

Parameters:
  • bintype (str or None) – The binning type. For MPL-4, one of the following: 'NONE', 'RADIAL', 'STON' (if None defaults to 'NONE'). For MPL-5, one of, 'ALL', 'NRE', 'SPX', 'VOR10' (defaults to 'SPX'). MPL-6 also accepts the 'HYB10' binning schema.
  • template (str or None) – The stellar template used. For MPL-4, one of 'M11-STELIB-ZSOL', 'MILES-THIN', 'MIUSCAT-THIN' (if None, defaults to 'MIUSCAT-THIN'). For MPL-5 and successive, the only option in 'GAU-MILESHC' (None defaults to it).
Variables:
download()[source]

Downloads the maps using sdss_access - Rsync

getCube()[source]

Returns the Cube for with this Maps.

getMap(property_name, channel=None, exact=False)[source]

Retrieves a Map object.

Parameters:
  • property_name (str) – The property of the map to be extractred. It may the name of the channel (e.g. 'emline_gflux_ha_6564') or just the name of the property ('emline_gflux').
  • channel (str or None) – If defined, the name of the channel to be appended to property_name (e.g., 'ha_6564').
  • exact (bool) – If exact=False, fuzzy matching will be used, retrieving the best match for the property name and channel. If True, will check that the name of returned map matched the input value exactly.
getMapRatio(property_name, channel_1, channel_2)[source]

Deprecated, see Enhanced Map. Returns a ratio Map.

For a given property_name, returns a Map which is the ratio of channel_1/channel_2.

Parameters:
  • property_name (str) – The property_name of the map to be extractred. E.g., 'emline_gflux'.
  • channel_1,channel_2 (str) – The channels to use.
getModelCube()[source]

Returns the ModelCube for with this Maps.

getSpaxel(x=None, y=None, ra=None, dec=None, drp=True, model=False, **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 as ra, dec celestial coordinates.

If spectrum=True, the returned Spaxel will be instantiated with the DRP spectrum of the spaxel for the DRP cube associated with this Maps.

Parameters:
  • x,y (int or array) – The spaxel coordinates relative to xyorig. If x is an array of coordinates, the size of x must much that of y.
  • ra,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 of ra must much that of dec.
  • xyorig ({'center', 'lower'}) – The reference point from which x and y are measured. Valid values are 'center' (default), for the centre of the spatial dimensions of the cube, or 'lower' for the lower-left corner. This keyword is ignored if ra and dec are defined.
  • drp (bool) – If True, the Spaxel will be initialised with the corresponding DRP data.
  • model (bool) – If True, the Spaxel will be initialised with the corresponding ModelCube data.
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.

get_binid(binid=None)[source]

Returns a 2D array containing the binid map.

In MPL-6, binid can be used to specify the binid property to return. If binid=None, the default binid is returned.

get_bpt(method='kewley06', snr_min=3, return_figure=True, show_plot=True, use_oi=True, **kwargs)[source]

Returns the BPT diagram for this target.

This method produces the BPT diagram for this target using emission line maps and returns a dictionary of classification masks, that can be used to select spaxels that have been classified as belonging to a certain excitation process. It also provides plotting functionalities.

Extensive documentation can be found in BPT Diagrams.

Parameters:
  • method ({'kewley06'}) – The method used to determine the boundaries between different excitation mechanisms. Currently, the only available method is 'kewley06', based on Kewley et al. (2006). Other methods may be added in the future. For a detailed explanation of the implementation of the method check the BPT documentation.
  • 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 to SNR>=3.
  • 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.
  • show_plot (bool) – If True, interactively display the BPT plot.
  • use_oi (bool) – If True, turns uses the OI diagnostic line in classifying BPT spaxels
Returns:

bpt_returnget_bpt always returns a dictionary of classification masks. These 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 keys of the dictionary, i.e., the classification categories, may change depending on the selected method. Consult the BPT documentation for more details. If return_figure=True, ~.Maps.get_bpt will also return the matplotlib Figure for the generated plot, and a list of axes for each one of the subplots.

Example

>>> cube = Cube(plateifu='8485-1901')
>>> maps = cube.getMaps()
>>> bpt_masks, bpt_figure = maps.get_bpt(snr=5, return_figure=True,
>>>                                      show_plot=False)

Now we can use the masks to select star forming spaxels from the cube

>>> sf_spaxels = cube.flux[bpt_masks['sf']['global']]

And we can save the figure as a PDF

>>> bpt_figure.savefig('8485_1901_bpt.pdf')
get_unbinned()[source]

Returns a version of self corresponding to the unbinned Maps.

is_binned()[source]

Returns True if the Maps is not unbinned.

to_dataframe(columns=None, mask=None)[source]

Converts the maps object into a Pandas dataframe.

Parameters:
  • columns (list) – The properties+channels you want to include. Defaults to all of them.
  • mask (array) – A 2D mask array for filtering your data output
Returns:

df (DataFrame) – A Pandas DataFrame.

manga_target1

Return MANGA_TARGET1 flag.

manga_target2

Return MANGA_TARGET2 flag.

manga_target3

Return MANGA_TARGET3 flag.

quality_flag

Return Maps DAPQUAL flag.

target_flags

Bundle MaNGA targeting flags.

Model Cube

class marvin.tools.modelcube.ModelCube(input=None, filename=None, mangaid=None, plateifu=None, mode=None, data=None, release=None, drpall=None, download=None, nsa_source='auto', bintype=None, template=None, template_kin=None)[source]

Bases: marvin.core.core.MarvinToolsClass, marvin.core.core.NSAMixIn, marvin.core.core.DAPallMixIn

A class to interface with MaNGA DAP model cubes.

This class represents a DAP model cube, initialised either from a file, a database, or remotely via the Marvin API. In addition to the parameters and variables defined for MarvinToolsClass, the following parameters and attributes are specific to Maps.

Parameters:
  • bintype (str or None) – The binning type. For MPL-4, one of the following: 'NONE', 'RADIAL', 'STON' (if None defaults to 'NONE'). For MPL-5, one of, 'ALL', 'NRE', 'SPX', 'VOR10' (defaults to 'SPX'). MPL-6 also accepts the 'HYB10' binning schema.
  • template (str or None) – The stellar template used. For MPL-4, one of 'M11-STELIB-ZSOL', 'MILES-THIN', 'MIUSCAT-THIN' (if None, defaults to 'MIUSCAT-THIN'). For MPL-5 and successive, the only option in 'GAU-MILESHC' (None defaults to it).
Variables:
download()[source]

Downloads the cube using sdss_access - Rsync

getCube()[source]

Returns the associated Cube.

getMaps()[source]

Returns the associated`~marvin.tools.maps.Maps`.

getSpaxel(x=None, y=None, ra=None, dec=None, drp=True, properties=True, **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 as ra, dec celestial coordinates.

If spectrum=True, the returned Spaxel will be instantiated with the DRP spectrum of the spaxel for the DRP cube associated with this ModelCube. The same is true for properties=True for the DAP properties of the spaxel in the Maps associated with these coordinates.

Parameters:
  • x,y (int or array) – The spaxel coordinates relative to xyorig. If x is an array of coordinates, the size of x must much that of y.
  • ra,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 of ra must much that of dec.
  • xyorig ({'center', 'lower'}) – The reference point from which x and y are measured. Valid values are 'center' (default), for the centre of the spatial dimensions of the cube, or 'lower' for the lower-left corner. This keyword is ignored if ra and dec are defined.
  • drpa (bool) – If True, the Spaxel will be initialised with the corresponding DRP data.
  • properties (bool) – If True, the Spaxel will be initialised with the corresponding DAP properties for this spaxel.
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.

get_binid(model=None)[source]

Returns the 2D array for the binid map associated with model.

get_unbinned()[source]

Returns a version of self corresponding to the unbinned ModelCube.

is_binned()[source]

Returns True if the ModelCube is not unbinned.

binned_flux

Returns the binned flux datacube.

emline_fit

Returns the emission line fit.

full_fit

Returns the full fit datacube.

manga_target1

Return MANGA_TARGET1 flag.

manga_target2

Return MANGA_TARGET2 flag.

manga_target3

Return MANGA_TARGET3 flag.

pixmask

Return the DAPSPECMASK flag.

quality_flag

Return ModelCube DAPQUAL flag.

stellarcont_fit

Returns the stellar continuum fit.

target_flags

Bundle MaNGA targeting flags.

Spaxel

class marvin.tools.spaxel.SpaxelBase(x, y, mangaid=None, plateifu=None, cube=True, maps=True, modelcube=True, lazy=False, **kwargs)[source]

Bases: object

A base class that contains information about a spaxel.

This class represents an spaxel with information from the reduced DRP spectrum, the DAP maps properties, and the model spectrum from the DAP logcube. A SpaxelBase can be initialised with all or only part of that information, and either from a file, a database, or remotely via the Marvin API.

The Cube, Maps , and ModelCube quantities for the spaxel are available in cube_quantities, maps_quantities, and modelcube_quantities, respectively. For convenience, the quantities can also be accessed directly from the SpaxelBase itself (e.g., spaxel.emline_gflux_ha_6465).

Parameters:
  • x,y (int) – The x and y coordinates of the spaxel in the cube (0-indexed).
  • mangaid (str) – The mangaid of the cube/maps/modelcube of the spaxel to load.
  • plateifu (str) – The plate-ifu of the cube/maps/modelcube of the spaxel to load (either mangaid or plateifu can be used, but not both).
  • cube (Cube object or path or bool) – If cube is a Cube object, that cube will be used for the SpaxelBase instantiation. This mode is mostly intended for getSpaxel as it significantly improves loading time. Otherwise, cube can be True (default), in which case a cube will be instantiated using the input filename, mangaid, or plateifu. If cube=False, no cube will be used and the cube associated quantities will not be available. cube can also be the path to the DRP cube to use.
  • maps (Maps object or path or bool) – As cube but for the DAP measurements corresponding to the spaxel in the Maps.
  • modelcube (marvin.tools.modelcube.ModelCube object or path or bool) – As maps but for the DAP measurements corresponding to the spaxel in the ModelCube.
  • lazy (bool) – If False, the spaxel data is loaded on instantiation. Otherwise, only the metadata is created. The associated quantities can be then loaded by calling SpaxelBase.load().
  • kwargs (dict) – Arguments to be passed to Cube, Maps, and ModelCube when (and if) they are initialised.
Variables:
  • cube_quantities (FuzzyDict) – A querable dictionary with the Spectrum quantities derived from Cube and matching x, y.
  • datamodel (object) – An object contianing the DRP and DAP datamodels.
  • maps_quantities (FuzzyDict) – A querable dictionary with the AnalysisProperty quantities derived from Maps and matching x, y.
  • model_quantities (FuzzyDict) – A querable dictionary with the Spectrum quantities derived from ModelCube and matching x, y.
  • ra,dec (float) – Right ascension and declination of the spaxel. Not available until the spaxel has been loaded.
getCube()[source]

Returns the associated Cube

getMaps()[source]

Returns the associated Maps

getModelCube()[source]

Returns the associated ModelCube

load(force=None)[source]

Loads the spaxel data.

Loads the spaxel data for cubes/maps/modelcubes. By default attempts to load whatever is specified when spaxels are instantianted from other Marvin Tools. Can manually force load a data type with the force keyword.

Parameters:force ({cube|maps|models}) – Str datatype to force load
classmethod restore(path, delete=False)[source]

Restores a Spaxel object from a pickled file.

If delete=True, the pickled file will be removed after it has been unplickled. Note that, for objects with data_origin='file', the original file must exists and be in the same path as when the object was first created.

save(path, overwrite=False)[source]

Pickles the spaxel to a file.

Parameters:
  • path (str) – The path of the file to which the Spaxel will be saved. Unlike for other Marvin Tools that derive from MarvinToolsClass, path is mandatory for Spaxel.save as there is no default path for a given spaxel.
  • overwrite (bool) – If True, and the path already exists, overwrites it. Otherwise it will fail.
Returns:

path (str) – The realpath to which the file has been saved.

bintype

Returns the bintype.

manga_target1

Return MANGA_TARGET1 flag.

manga_target2

Return MANGA_TARGET2 flag.

manga_target3

Return MANGA_TARGET3 flag.

mangaid

Returns the mangaid.

plateifu

Returns the plateifu.

quality_flags

Bundle Cube DRP3QUAL and Maps DAPQUAL flags.

release

Returns the release.

target_flags

Bundle MaNGA targeting flags.

template

Returns the template.

class marvin.tools.spaxel.Spaxel(*args, **kwargs)[source]

Bases: marvin.tools.spaxel.SpaxelBase

A class representing an unbinned spaxel.

This subclass of SpaxelBase represents an spaxel belonging to an unbinned Maps and ModelCube. If initialised directly, a Spaxel will fail if the input data correspond to a binned maps or modelcube object.

Refer to the documentation of SpaxelBase for information about the valid parameters and methods.

Bin

class marvin.tools.spaxel.Bin(*args, **kwargs)[source]

Bases: marvin.tools.spaxel.SpaxelBase

A class that represents a bin.

load()[source]

Loads quantities and spaxels.

load_all()[source]

Loads all the spaxels.