Map (marvin.tools.quantities.Map)

Introduction

Map is a single map for a single galaxy. The main data that it contains are the value, ivar, and mask arrays of the map. It also has some meta data and convenience functions, such as plot(), which wraps the marvin.utils.plot.map.plot() method.

Getting Started

To get a map, we first need to create a marvin.tools.maps.Maps object, which contains all of the maps for a galaxy.

from marvin.tools.maps import Maps
maps = Maps(plateifu='8485-1901')

By default, Maps returns the unbinned maps SPX, but we can also choose from additional bintypes (see the Technical Reference Manual for a more complete description of each bintype and the associated usage warnings):

  • SPX - spaxels are unbinned,
  • VOR10 - spaxels are Voronoi binned to a minimum continuum SNR of 10,
  • NRE - spaxels are binned into two radial bins, binning all spectra from 0-1 and 1-2 (elliptical Petrosian) effective radii, and
  • ALL - all spectra binned together.
maps = Maps(mangaid='1-209232', bintype='VOR10')

Once we have a Maps object, we can “slice” it to get the H\(\alpha\) (Gaussian-fitted) flux map.

ha = maps['emline_gflux_ha_6564']
ha.plot()
../_images/quick_map_plot.png

Here maps['emline_gflux_ha_6564'] is shorthand for maps.getMap('emline_gflux', channel='ha_6564'), where the property and channel are joined by an underscore (“_”). For properties without channels, such as stellar velocity, just use the property name like maps['stellar_vel'].

ha = maps.getMap('emline_gflux', channel='ha_6564')   # == maps['emline_gflux_ha_6564']
stvel = maps.getMap('stellar_vel')                    # == maps['stellar_vel']

New in 2.2.0: You can guess at the map property name (and channel), and Marvin will return the map if there is a unique (and valid) property and channel.

maps['gflux ha']        # == maps['emline_gflux_ha_6564']
maps['gvel oiii 5008']  # == maps[emline_gvel_oiii_5008]
maps['stellar sig']     # == maps['stellar_sigma']

# There are several properties of the Halpha line (velocity, sigma, etc.).
maps['ha']  # ValueError

# There are two [O III] lines.
maps['gflux oiii']  # ValueError

The values, inverse variances, and bitmasks of the map can be accessed via the value, ivar, and mask attributes, respectively.

Important: These arrays are ordered as [row, column] with the origin in the lower left, which corresponds to [y, x].

ha.value  # (34, 34) array
ha.ivar   # (34, 34) array
ha.mask   # (34, 34) array --- same as ha.pixmask.mask

ha.value[17]  # get the middle row (i.e., "y")
# array([  0.        ,   0.        ,   0.        ,   0.        ,
#          0.        ,   0.        ,   0.03650022,   0.03789879,
#          0.0838113 ,   0.16109767,   0.57484451,   1.42108019,
#          2.98873795,   7.47787753,  14.08300415,  21.61707138,
#         28.37593542,  31.47541953,  28.29092958,  20.82737156,
#         13.33138178,   6.90730005,   3.70062335,   1.54131387,
#          0.55510055,   0.34234428,   0.21906664,   0.18621548,
#          0.1745672 ,   0.        ,   0.        ,   0.        ,
#          0.        ,   0.        ])

The masked attribute is a numpy masked array. The data attribute is the value array and the mask attribute is a boolean array. mask is True for a given spaxel if any of the recommended bad data flags (NOCOV, UNRELIABLE, and DONOTUSE) are set (New in 2.2.0; previously, spaxels with any flags set were masked—i.e., where ha.mask > 0).

ha.masked[17]
# masked_array(data = [-- -- -- -- -- -- -- 0.03789878599602308 0.08381129696903318
#                      0.1610976667261473 0.5748445110902572 1.421080190438372 2.988737954927168
#                      7.477877525388817 14.083004151791611 21.61707138246288 28.37593542372677
#                      31.475419531155 28.290929579722462 20.827371557790272 13.331381776434451
#                      6.907300050577721 3.7006233506234203 1.5413138678320422 0.5551005467482618
#                      0.3423442819444342 0.2190666373241594 0.18621548081774594
#                      0.17456719770757587 -- -- -- -- --],
#              mask = [ True  True  True  True  True  True  True False False False False False
#                       False False False False False False False False False False False False
#                       False False False False False  True  True  True  True  True],
#              fill_value = 1e+20)

New in 2.2.0: For more fine-grained data quality control, you can select spaxels using pixmask, which contains the mask values, knows the MANGA_DAPPIXMASK schema, and has convenience methods for converting between mask values, bit values, and labels.

See Maskbit (marvin.utils.general.maskbit.Maskbit) for details.

ha.pixmask
# <Maskbit 'MANGA_DAPPIXMASK'
#
#     bit         label                                        description
# 0     0         NOCOV                         No coverage in this spaxel
# 1     1        LOWCOV                        Low coverage in this spaxel
# 2     2     DEADFIBER                   Major contributing fiber is dead
# 3     3      FORESTAR                                    Foreground star
# 4     4       NOVALUE  Spaxel was not fit because it did not meet sel...
# 5     5    UNRELIABLE  Value is deemed unreliable; see TRM for defini...
# 6     6     MATHERROR              Mathematical error in computing value
# 7     7     FITFAILED                  Attempted fit for property failed
# 8     8     NEARBOUND  Fitted value is too near an imposed boundary; ...
# 9     9  NOCORRECTION               Appropriate correction not available
# 10   10     MULTICOMP          Multi-component velocity features present
# 11   30      DONOTUSE                 Do not use this spaxel for science>

ha.pixmask.mask    # == ha.mask
ha.pixmask.bits    # bits corresponding to mask array
ha.pixmask.labels  # labels corresponding to mask array

Note: For MPL-5+, DONOTUSE is a consolidation of the flags NOCOV, LOWCOV, DEADFIBER, FORESTAR, NOVALUE, MATHERROR, FITFAILED, and NEARBOUND. For MPL-4, the MANGA_DAPPIXMASK flag is simply 0 = good and 1 = bad (which roughly corresponds to DONOTUSE).

Using Map

For more in-depth discussion of using Map, please see the following sections:

Map Arithmetic

New in 2.2.0 Map objects can be added, subtracted, multiplied, divided, or raised to a power.

ha = maps['emline_gflux_ha_6564']
nii = maps['emline_gflux_nii_6585']

sum_ = nii + ha
diff = nii - ha
prod = nii * ha
quot = nii / ha
pow_ = ha**0.5

prod
# <Marvin EnhancedMap>
# array([[ 0.,  0.,  0., ...,  0.,  0.,  0.],
#        [ 0.,  0.,  0., ...,  0.,  0.,  0.],
#        [ 0.,  0.,  0., ...,  0.,  0.,  0.],
#        ...,
#        [ 0.,  0.,  0., ...,  0.,  0.,  0.],
#        [ 0.,  0.,  0., ...,  0.,  0.,  0.],
#        [ 0.,  0.,  0., ...,  0.,  0.,  0.]]) 'erg2 / (cm4 s2 spaxel2)'

In addition to performing the arithmetic operation on the value, the resulting EnhancedMap has correctly propagated ivar, mask, pixmask, unit, and scale.

Accessing the Parent Maps Object

One of the most useful features of Marvin is the tight integration of the Tools. From a Map object we can access its parent Maps object via the maps attribute and meta data about the Property via the property attribute.

ha.maps == maps  # True

ha.property
# <Property 'emline_gflux', release='2.0.2', channel='ha_6564', unit='erg / (cm2 s spaxel)'>

Saving and Restoring a Map

Finally, we can save() our Map object as a MaNGA pickle file (*.mpf) and then restore() it.

from marvin.tools.quantities import Map
ha.save(path='/path/to/save/directory/ha_8485-1901.mpf')
zombie_ha = Map.restore(path='/path/to/save/directory/ha_8485-1901.mpf')

Common Masking

# Spaxels not covered by the IFU
nocov = ha.pixmask.get_mask('NOCOV')

# Spaxels flagged as bad data
bad_data = ha.pixmask.get_mask(['UNRELIABLE', 'DONOTUSE'])

# Custom mask (flag data as DONOTUSE to hide in plotting)
custom_mask = (ha.value < 1e-17) * ha.pixmask.labels_to_value('DONOTUSE')

# Combine masks
my_mask = nocov | custom_mask

Reference/API

Class Inheritance Diagram

Inheritance diagram of marvin.tools.quantities.Map

Class

marvin.tools.quantities.Map Describes 2D array object with addtional features.

Methods

marvin.tools.quantities.Map.error Computes the standard deviation of the measurement.
marvin.tools.quantities.Map.inst_sigma_correction() Correct for instrumental broadening.
marvin.tools.quantities.Map.masked Return a masked array using the recommended masks.
marvin.tools.quantities.Map.pixmask Maskbit instance for the MANGA_DAPPIXMASK flag.
marvin.tools.quantities.Map.plot(*args, **kwargs) Make single panel map or one panel of multi-panel map plot.
marvin.tools.quantities.Map.restore(path[, …]) Restore a Map object from a pickled file.
marvin.tools.quantities.Map.save(path[, …]) Pickle the map to a file.
marvin.tools.quantities.Map.snr Return the signal-to-noise ratio for each spaxel in the map.