dustmap modules

bayestar (Green et al. 2015)

class dustmaps.bayestar.BayestarQuery(map_fname=None, max_samples=None)[source]

Bases: dustmaps.map_base.DustMap

Queries the Bayestar 3D dust maps, including Green, Schlafly & Finkbeiner (2015). The maps cover the Pan-STARRS 1 footprint, Dec > -30 deg, amounting to three-quarters of the sky.

__init__(map_fname=None, max_samples=None)[source]
Parameters:
  • map_fname (Optional[str]) – Filename of the Bayestar map. Defaults to None, meaning that the default location is used.
  • max_samples (Optional[int]) – Maximum number of samples of the map to load. Use a lower number in order to decrease memory usage. Defaults to None, meaning that all samples will be loaded.
distances

Returns the distance bins that the map uses. The return type is astropy.units.Quantity, which stores unit-full quantities.

query(coords, **kwargs)[source]

Returns E(B-V) at the requested coordinates. There are several different query modes, which handle the probabilistic nature of the map differently.

Parameters:
  • coords (astropy.coordinates.SkyCoord) – The coordinates to query.
  • mode (Optional[str]) – Five different query modes are available: ‘random_sample’, ‘random_sample_per_pix’ ‘samples’, ‘median’ and ‘mean’. The mode determines how the output will reflect the probabilistic nature of the Bayestar dust maps.
Returns:

Reddening at the specified coordinates, in mags of E(B-V). The shape of the output depends on the mode, and on whether coords contains distances.

If coords does not specify distance(s), then the shape of the output begins with coords.shape. If coords does specify distance(s), then the shape of the output begins with coords.shape + ([number of distance bins],).

If mode is ‘random_sample’, then at each coordinate/distance, a random sample of reddening is given.

If mode is ‘random_sample_per_pix’, then the sample chosen for each angular pixel of the map will be consistent. For example, if two query coordinates lie in the same map pixel, then the same random sample will be chosen from the map for both query coordinates.

If mode is ‘median’, then at each coordinate/distance, the median reddening is returned.

If mode is ‘mean’, then at each coordinate/distance, the mean reddening is returned.

Finally, if mode is ‘samples’, then all at each coordinate/distance, all samples are returned.

dustmaps.bayestar.fetch()[source]

Downloads the Bayestar dust map of Green, Schlafly, Finkbeiner et al. (2015).

dustmaps.bayestar.lb2pix(nside, l, b, nest=True)[source]

Converts Galactic (l, b) to HEALPix pixel index.

Parameters:
  • nside (int) – The HEALPix nside parameter.
  • l (float, or array of floats) – Galactic longitude, in degrees.
  • b (float, or array of floats) – Galactic latitude, in degrees.
  • nest (Optional[bool]) – If True (the default), nested pixel ordering will be used. If False, ring ordering will be used.
Returns:

The HEALPix pixel index or indices. Has the same shape as the input l and b.

bh (Burstein & Heiles 1982)

class dustmaps.bh.BHQuery(bh_dir=None)[source]

Bases: dustmaps.map_base.DustMap

Queries the Burstein & Heiles (1982) reddening map.

__init__(bh_dir=None)[source]
Parameters:bh_dir (Optional[str]) – The directory containing the Burstein & Heiles dust map. Defaults to None, meaning that the default directory is used.
query(coords, **kwargs)[source]

Returns E(B-V) at the specified location(s) on the sky.

Parameters:coords (astropy.coordinates.SkyCoord) – The coordinates to query.
Returns:A float array of reddening, in units of E(B-V), at the given coordinates. The shape of the output is the same as the shape of the coordinates stored by coords.
dustmaps.bh.ascii2h5(bh_dir=None)[source]

Convert the Burstein & Heiles (1982) dust map from ASCII to HDF5.

chen2014 (Chen et al. 2014)

class dustmaps.chen2014.Chen2014Query(map_fname=None)[source]

Bases: dustmaps.unstructured_map.UnstructuredDustMap

The 3D dust map of Chen et al. (2014), based on stellar photometry from the Xuyi Schmidt Telescope Photometric Survey of the Galactic Anticentre. The map covers 140 deg < l < 240 deg, -60 deg < b < 40 deg.

__init__(map_fname=None)[source]
Parameters:map_fname (Optional[str]) – Filename at which the map is stored. Defaults to None, meaning that the default filename is used.
distances

Returns the distance bins that the map uses. The return type is astropy.units.Quantity, which stores unit-full quantities.

query(coords, **kwargs)[source]

Returns r-band extinction, A_r, at the given coordinates. Can also return uncertainties.

Parameters:
  • coords (astropy.coordinates.SkyCoord) – The coordinates to query.
  • return_sigma (Optional[bool]) – If True, returns the uncertainty in extinction as well. Defaults to False.
Returns:

Extinction in the r-band at the specified coordinates, in mags. The shape of the output depends on whether coords contains distances.

If coords does not specify distance(s), then the shape of the output begins with coords.shape. If coords does specify distance(s), then the shape of the output begins with coords.shape + ([number of distance bins],).

dustmaps.chen2014.ascii2h5(dat_fname, h5_fname)[source]

Converts from the original ASCII format of the Chen+ (2014) 3D dust map to the HDF5 format.

Parameters:
  • dat_fname (str) – Filename of the original ASCII .dat file.
  • h5_fname (str) – Output filename to write the resulting HDF5 file to.
dustmaps.chen2014.fetch(clobber=False)[source]

Downloads the Chen et al. (2014) dust map.

Parameters:clobber (Optional[bool]) – If True, any existing file will be overwritten, even if it appears to match. If False (the default), fetch() will attempt to determine if the dataset already exists. This determination is not 100% robust against data corruption.

iphas (Sale et al. 2014)

class dustmaps.iphas.IPHASQuery(map_fname=None)[source]

Bases: dustmaps.unstructured_map.UnstructuredDustMap

The 3D dust map of Sale et al. (2014), based on IPHAS imaging in the Galactic plane. The map covers 30 deg < l < 115 deg, -5 deg < b < 5 deg.

__init__(map_fname=None)[source]
Parameters:map_fname (Optional[str]) – Filename at which the map is stored. Defaults to None, meaning that the default filename is used.
distances

Returns the distance bins that the map uses. The return type is astropy.units.Quantity, which stores unit-full quantities.

query(coords, **kwargs)[source]

Returns A0 at the given coordinates. There are several different query modes, which handle the probabilistic nature of the map differently.

Parameters:
  • coords (astropy.coordinates.SkyCoord) – The coordinates to query.
  • mode (Optional[str]) – Five different query modes are available: ‘random_sample’, ‘random_sample_per_pix’ ‘samples’, ‘median’ and ‘mean’. The mode determines how the output will reflect the probabilistic nature of the IPHAS dust map.
Returns:

Monochromatic extinction, A0, at the specified coordinates, in mags. The shape of the output depends on the mode, and on whether coords contains distances.

If coords does not specify distance(s), then the shape of the output begins with coords.shape. If coords does specify distance(s), then the shape of the output begins with coords.shape + ([number of distance bins],).

If mode is ‘random_sample’, then at each coordinate/distance, a random sample of reddening is given.

If mode is ‘random_sample_per_pix’, then the sample chosen for each angular pixel of the map will be consistent. For example, if two query coordinates lie in the same map pixel, then the same random sample will be chosen from the map for both query coordinates.

If mode is ‘median’, then at each coordinate/distance, the median reddening is returned.

If mode is ‘mean’, then at each coordinate/distance, the mean reddening is returned.

Finally, if mode is ‘samples’, then all at each coordinate/distance, all samples are returned.

dustmaps.iphas.ascii2h5(dirname, output_fname)[source]

Converts from a directory of tarballed ASCII ”.samp” files to a single HDF5 file. Essentially, converts from the original release format to a single HDF5 file.

dustmaps.iphas.fetch(clobber=False)[source]

Downloads the IPHAS 3D dust map of Sale et al. (2014).

Parameters:clobber (Optional[bool]) – If True, any existing file will be overwritten, even if it appears to match. If False (the default), fetch() will attempt to determine if the dataset already exists. This determination is not 100% robust against data corruption.

marshall (Marshall et al. 2006)

class dustmaps.marshall.MarshallQuery(map_fname=None)[source]

Bases: dustmaps.map_base.DustMap

Galactic-plane 3D dust map of Marshall et al. (2006), based on 2MASS photometry.

__init__(map_fname=None)[source]
Parameters:map_fname (Optional[str]) – Filename at which the map is stored. Defaults to None, meaning that the default filename is used.
query(coords, **kwargs)[source]

Returns 2MASS Ks-band extinction at the given coordinates.

Parameters:
  • coords (astropy.coordinates.SkyCoord) – The coordinates to query. Must contain distances.
  • return_sigma (Optional[bool]) – If True, returns the uncertainty in extinction as well. Defaults to False.
Returns:

Extinction at the specified coordinates, in mags of 2MASS Ks-band extinction. If return_sigma is True, then the uncertainty in reddening is also returned, so that the output is (A, sigma_A), where both A and sigma_A have the same shape as the input coordinates.

dustmaps.marshall.dat2hdf5(table_dir)[source]

Convert the Marshall et al. (2006) map from *.dat.gz to *.hdf5.

dustmaps.marshall.fetch(clobber=False)[source]

Downloads the Marshall et al. (2006) dust map, which is based on 2MASS stellar photometry.

Parameters:clobber (Optional[bool]) – If True, any existing file will be overwritten, even if it appears to match. If False (the default), fetch() will attempt to determine if the dataset already exists. This determination is not 100% robust against data corruption.

planck (Planck Collaboration 2013)

class dustmaps.planck.PlanckQuery(map_fname=None, component='extragalactic')[source]

Bases: dustmaps.healpix_map.HEALPixFITSQuery

Queries the Planck Collaboration (2013) dust map.

__init__(map_fname=None, component='extragalactic')[source]
Parameters:
  • map_fname (Optional[str]) – Filename of the Planck map. Defaults to `None, meaning that the default location is used.
  • component (Optional[str]) – Which measure of reddening to use. There are seven valid components. Three denote reddening measures: ‘extragalactic’, ‘tau’ and ‘radiance’. Four refer to dust properties: ‘temperature’, ‘beta’, ‘err_temp’ and ‘err_beta’. Defaults to ‘extragalactic’.
query(coords, **kwargs)[source]

Returns E(B-V) (or a different Planck dust inference, depending on how the class was intialized) at the specified location(s) on the sky.

Parameters:coords (astropy.coordinates.SkyCoord) – The coordinates to query.
Returns:A float array of the selected Planck component, at the given coordinates. The shape of the output is the same as the shape of the coordinates stored by coords. If extragalactic E(B-V), tau_353 or radiance was chosen, then the output has units of magnitudes of E(B-V). If the selected Planck component is temperature (or temperature error), then an astropy.Quantity is returned, with units of Kelvin. If beta (or beta error) was chosen, then the output is unitless.
dustmaps.planck.fetch()[source]

Downloads the Planck Collaboration (2013) dust map, placing it in the default `dustmaps data directory.

sfd (Schlegel, Finkbeiner & Davis 1998)

class dustmaps.sfd.SFDQuery(map_dir=None)[source]

Bases: dustmaps.map_base.DustMap

Queries the Schlegel, Finbeiner & Davis (1998) dust reddening map.

__init__(map_dir=None)[source]
Parameters:map_dir (Optional[str]) – The directory containing the SFD map. Defaults to None, which means that dustmaps will look in its default data directory.
query(coords, **kwargs)[source]

Returns E(B-V) at the specified location(s) on the sky. See Table 6 of Schlafly & Finkbeiner (2011) for instructions on how to convert this quantity to extinction in various passbands.

Parameters:
  • coords (astropy.coordinates.SkyCoord) – The coordinates to query.
  • order (Optional[int]) – Interpolation order to use. Defaults to 1, for linear interpolation.
Returns:

A float array containing the SFD E(B-V) at every input coordinate. The shape of the output will be the same as the shape of the coordinates stored by coords.

dustmaps.sfd.fetch()[source]

Downloads the Schlegel, Finkbeiner & Davis (1998) dust map, placing it in the data directory for dustmap.

fetch_utils

exception dustmaps.fetch_utils.DownloadError[source]

Bases: dustmaps.fetch_utils.Error

An exception that occurs while trying to download a file.

dustmaps.fetch_utils.dataverse_download_doi(doi, local_fname=None, file_requirements={}, clobber=False)[source]

Downloads a file from the Dataverse, using a DOI and set of metadata parameters to locate the file.

Parameters:
  • doi (str) – Digital Object Identifier (DOI) containing the file.
  • local_fname (Optional[str]) – Local filename to download the file to. If None, then use the filename provided by the Dataverse. Defaults to None.
  • file_requirements (Optional[dict]) – Select the file containing the given metadata entries. If multiple files meet these requirements, only the first in downloaded. Defaults to {}, corresponding to no requirements.
Raises:
  • DownloadError – Either no matching file was found under the given DOI, or the MD5 sum of the file was not as expected.
  • requests.exceptions.HTTPError – The given DOI does not exist, or there was a problem connecting to the Dataverse.
dustmaps.fetch_utils.dataverse_search_doi(doi)[source]

Fetches metadata pertaining to a Digital Object Identifier (DOI) in the Harvard Dataverse.

Parameters:doi (str) – The Digital Object Identifier (DOI) of the entry in the Dataverse.
Raises:requests.exceptions.HTTPError – The given DOI does not exist, or there was a problem connecting to the Dataverse.
dustmaps.fetch_utils.download(url, fname=None)[source]

Downloads a file.

Parameters:
  • url (str) – The URL to download.
  • fname (Optional[str]) – The filename to store the downloaded file in. If None, take the filename from the URL. Defaults to None.
Returns:

The filename the URL was downloaded to.

Raises:

requests.exceptions.HTTPError – There was a problem connecting to the URL.

dustmaps.fetch_utils.download_and_verify(url, md5sum, fname=None, chunk_size=1024, clobber=False)[source]

Download a file and verify the MD5 sum.

Parameters:
  • url (str) – The URL to download.
  • md5sum (str) – The expected MD5 sum.
  • fname (Optional[str]) – The filename to store the downloaded file in. If None, infer the filename from the URL. Defaults to None.
  • chunk_size (Optional[int]) – Process in chunks of this size (in Bytes). Defaults to 1024.
  • clobber (Optional[bool]) – If True, any existing, identical file will be overwritten. If False, the MD5 sum of any existing file with the destination filename will be checked. If the MD5 sum does not match, the existing file will be overwritten. Defaults to False.
Returns:

The filename the URL was downloaded to.

Raises:
  • DownloadError – The MD5 sum of the downloaded file does not match md5sum.
  • requests.exceptions.HTTPError – There was a problem connecting to the URL.
dustmaps.fetch_utils.get_md5sum(fname, chunk_size=1024)[source]

Returns the MD5 checksum of a file.

Parameters:
  • fname (str) – Filename
  • chunk_size (Optional[int]) – Size (in Bytes) of the chunks that should be read in at once. Increasing chunk size reduces the number of reads required, but increases the memory usage. Defaults to 1024.
Returns:

The MD5 checksum of the file, which is a string.

dustmaps.fetch_utils.h5_file_exists(fname, size_guess=None, rtol=0.1, atol=1.0, dsets={})[source]

Returns True if an HDF5 file exists, has the expected file size, and contains (at least) the given datasets, with the correct shapes.

Parameters:
  • fname (str) – Filename to check.
  • size_guess (Optional[int]) – Expected size (in Bytes) of the file. If None (the default), then filesize is not checked.
  • rtol (Optional[float]) – Relative tolerance for filesize.
  • atol (Optional[float]) – Absolute tolerance (in Bytes) for filesize.
  • dsets (Optional[dict]) – Dictionary specifying expected datasets. Each key is the name of a dataset, while each value is the expected shape of the dataset. Defaults to {}, meaning that no datasets are checked.
Returns:

True if the file matches by all given criteria.

map_base

class dustmaps.map_base.DustMap[source]

Bases: object

Base class for querying dust maps. For each individual dust map, a different subclass should be written, implementing the query function.

__call__(coords, **kwargs)[source]

An alias for DustMap.query.

query(coords, **kwargs)[source]

Query the map at a set of coordinates.

Parameters:coords (astropy.coordinates.SkyCoord) – The coordinates at which to query the map.
Raises:NotImplementedError – This function must be defined by derived classes.
query_equ(ra, dec, d=None, frame='icrs', **kwargs)[source]

Query using Equatorial coordinates. By default, the ICRS frame is used, although other frames implemented by astropy.coordinates may also be specified.

Parameters:
  • ra (float, scalar or array-like) – Galactic longitude, in degrees.
  • dec (float, scalar or array-like) – Galactic latitude, in degrees.
  • d (Optinal[float, scalar or array-like]) – Distance from the Solar System. Defaults to None, meaning no distance is specified.
  • frame (Optional[icrs]) – The coordinate system. Can be ‘icrs’ (the default), ‘fk5’, ‘fk4’ or ‘fk4noeterms’.
  • **kwargs – Any additional keyword arguments accepted by derived classes.
Returns:

The results of the query, which must be implemented by derived classes.

query_gal(l, b, d=None, **kwargs)[source]

Query using Galactic coordinates.

Parameters:
  • l (float, scalar or array-like) – Galactic longitude, in degrees.
  • b (float, scalar or array-like) – Galactic latitude, in degrees.
  • d (Optinal[float, scalar or array-like]) – Distance from the Solar System. Defaults to None, meaning no distance is specified.
  • **kwargs – Any additional keyword arguments accepted by derived classes.
Returns:

The results of the query, which must be implemented by derived classes.

dustmaps.map_base.coord2healpix(coords, frame, nside, nest=True)[source]

Calculate HEALPix indices from an astropy SkyCoord. Assume the HEALPix system is defined on the coordinate frame frame.

Parameters:
  • coords (astropy.coordinates.SkyCoord) – The input coordinates.
  • frame (str) – The frame in which the HEALPix system is defined.
  • nside (int) – The HEALPix nside parameter to use. Must be a power of 2.
  • nest (Optional[bool]) – True (the default) if nested HEALPix ordering is desired. False for ring ordering.
Returns:

An array of pixel indices (integers), with the same shape as the input SkyCoord coordinates (coords.shape).

Raises:

dustexceptions.CoordFrameError – If the specified frame is not supported.

dustmaps.map_base.ensure_coord_type(f)[source]

A decorator for class methods of the form

Class.method(self, coords, **kwargs)

where coords is an astropy.coordinates.SkyCoord object.

The decorator raises a TypeError if the coords that gets passed to Class.method is not an astropy.coordinates.SkyCoord instance.

Parameters:f (class method) – A function with the signature (self, coords, **kwargs), where coords is a SkyCoord object containing an array.
Returns:
A function that raises a TypeError if coord is not an
astropy.coordinates.SkyCoord object, but which otherwise behaves the same as the decorated function.
dustmaps.map_base.ensure_flat_galactic(f)[source]

A decorator for class methods of the form

Class.method(self, coords, **kwargs)

where coords is an astropy.coordinates.SkyCoord object.

The decorator ensures that the coords that gets passed to Class.method is a flat array of Galactic coordinates. It also reshapes the output of Class.method to have the same shape (possibly scalar) as the input coords. If the output of Class.method is a tuple or list (instead of an array), each element in the output is reshaped instead.

Parameters:f (class method) – A function with the signature (self, coords, **kwargs), where coords is a SkyCoord object containing an array.
Returns:A function that takes SkyCoord input with any shape (including scalar).

healpix_map

class dustmaps.healpix_map.HEALPixFITSQuery(fname, coord_frame, hdu=0, field=0, dtype='f8')[source]

Bases: dustmaps.healpix_map.HEALPixQuery

A HEALPix map class that is initialized from a FITS file.

__init__(fname, coord_frame, hdu=0, field=0, dtype='f8')[source]
Parameters:
  • fname (str, HDUList, TableHDU or BinTableHDU) – The filename, HDUList or HDU from which the map should be loaded.
  • coord_frame (str) – The coordinate system in which the HEALPix map is defined. Must be a coordinate frame which astropy understands.
  • hdu (Optional[int or str]) – Specifies which HDU to load the map from. Defaults to 0.
  • field (Optional[int or str]) – Specifies which field (column) to load the map from. Defaults to 0.
  • dtype (Optional[str or type]) – The data will be coerced to this datatype. Can be any type specification that numpy understands. Defaults to ‘f8’, for IEEE754 double precision.
class dustmaps.healpix_map.HEALPixQuery(pix_val, nest, coord_frame)[source]

Bases: dustmaps.map_base.DustMap

A class for querying HEALPix maps.

__init__(pix_val, nest, coord_frame)[source]
Parameters:
  • pix_val (array) – Value of the map in every pixel. The length of the array must be of the form 12 * nside**2, where nside is a power of two.
  • nest (bool) – True if the map uses nested ordering. False if ring ordering is used.
  • coord_frame (str) – The coordinate system that the HEALPix map is in. Should be one of the frames supported by astropy.coordinates.
query(coords)[source]
Parameters:coords (astropy.coordinates.SkyCoord) – The coordinates to query.
Returns:A float array of the value of the map at the given coordinates. The shape of the output is the same as the shape of the coordinates stored by coords.

unstructured_map

class dustmaps.unstructured_map.UnstructuredDustMap(pix_coords, max_pix_scale, metric_p=2, frame=None)[source]

Bases: dustmaps.map_base.DustMap

A class for querying dust maps with unstructured pixels. Sky coordinates are assigned to the nearest pixel.

__init__(pix_coords, max_pix_scale, metric_p=2, frame=None)[source]
Parameters:
  • pix_coords (array-like astropy.coordinates.SkyCoord) – The sky coordinates of the pixels.
  • max_pix_scale (scalar astropy.units.Quantity) – Maximum angular extent of a pixel. If no pixel is within this distance of a query point, NaN will be returned for that query point.
  • metric_p (Optional[float]) – The metric to use. Defaults to 2, which is the Euclidean metric. A value of 1 corresponds to the Manhattan metric, while a value approaching infinity yields the maximum component metric.
  • frame (Optional[str]) – The coordinate frame to use internally. Must be a frame understood by astropy.coordinates.SkyCoord. Defaults to None, meaning that the frame will be inferred from pix_coords.

config

class dustmaps.config.Configuration(fname)[source]

Bases: object

A class that stores the package configuration.

get(key, default=None)[source]

Gets a configuration option, returning a default value if the specified key isn’t set.

remove(key)[source]

Deletes a key from the configuration.

reset()[source]

Resets the configuration, and overwrites the existing configuration file.

save(force=False)[source]

Saves the configuration to a JSON, in the standard config location.

Parameters:

force (Optional[bool]) – Continue writing, even if the original config file was not loaded properly. This is dangerous, because it could cause the previous configuration options to be lost. Defaults to False.

Raises:
  • ConfigError if the configuration file was not successfully loaded
  • on initialization of the class, and force is False.
dustmaps.config.config = <dustmaps.config.Configuration object>

The package configuration. This is the object that the user should interact with in order to change settings. For example, to set the directory where large files (e.g., dust maps) will be stored:

from dustmaps.config import config
config['data_dir'] = '/path/to/data/directory'

std_paths

dustmaps.std_paths.data_dir()[source]

Returns the directory used to store large data files (e.g., dust maps).

dustmaps.std_paths.fix_path(path)[source]

Returns an absolute path, with ‘~’ expanded to the user’s home directory.

dustmaps.std_paths.output_dir()[source]

Returns a directory that can be used to store temporary output.