tessl/pypi-dustmaps

Uniform interface for multiple dust reddening maps

Overview

Eval results

Files

Base Classes and Utilities

Name: tessl/pypi-dustmaps
Author: tessl

Foundation classes and utility functions that provide the common infrastructure for all dust map implementations. These components handle coordinate transformations, data loading, map querying, and serialization across the dustmaps ecosystem.

Capabilities

Abstract Base Classes

Core abstract classes that define the standard interface for all dust map queries.

class DustMap:
    """Abstract base class for all dust map implementations."""

    def __init__(self):
        """Initialize dust map instance."""

    def __call__(self, coords, **kwargs):
        """
        Callable alias for query method.

        Parameters:
        - coords (SkyCoord): Coordinate positions to query
        - **kwargs: Additional arguments passed to query

        Returns:
        - float | np.ndarray: Dust values
        """

    def query(self, coords, **kwargs):
        """
        Query dust map at specified coordinates. Must be implemented by subclasses.

        Parameters:
        - coords (SkyCoord): Coordinate positions to query
        - **kwargs: Map-specific query parameters

        Returns:
        - float | np.ndarray: Dust extinction or density values

        Raises:
        - NotImplementedError: If not implemented by subclass
        """

    def query_gal(self, l, b, d=None, **kwargs):
        """
        Query using Galactic coordinates.

        Parameters:
        - l (float | array): Galactic longitude (degrees)
        - b (float | array): Galactic latitude (degrees)
        - d (float | array, optional): Distance (pc, required for 3D maps)
        - **kwargs: Additional query parameters

        Returns:
        - float | np.ndarray: Dust values
        """

    def query_equ(self, ra, dec, d=None, frame='icrs', **kwargs):
        """
        Query using Equatorial coordinates.

        Parameters:
        - ra (float | array): Right ascension (degrees)
        - dec (float | array): Declination (degrees)
        - d (float | array, optional): Distance (pc, required for 3D maps)
        - frame (str): Coordinate frame ('icrs', 'fk5', etc.)
        - **kwargs: Additional query parameters

        Returns:
        - float | np.ndarray: Dust values
        """

class WebDustMap:
    """Base class for web API-based dust map queries."""

    def __init__(self, api_url=None, map_name=''):
        """
        Initialize web dust map query.

        Parameters:
        - api_url (str, optional): Base URL for web API
        - map_name (str): Name of dust map for API requests
        """

    def __call__(self, coords, **kwargs):
        """Callable alias for query method."""

    def query(self, coords, **kwargs):
        """
        Query dust map via web API.

        Parameters:
        - coords (SkyCoord): Coordinate positions to query
        - **kwargs: API-specific parameters

        Returns:
        - float | np.ndarray: Dust values from web service
        """

    def query_gal(self, l, b, d=None, **kwargs):
        """Query web API using Galactic coordinates."""

    def query_equ(self, ra, dec, d=None, frame='icrs', **kwargs):
        """Query web API using Equatorial coordinates."""

HEALPix Map Support

Base classes for dust maps stored in HEALPix format (Hierarchical Equal Area isoLatitude Pixelization).

class HEALPixQuery(DustMap):
    """Base class for HEALPix-formatted dust maps."""

    def __init__(self, pix_val, nest, coord_frame, flags=None):
        """
        Initialize HEALPix dust map from pixel values.

        Parameters:
        - pix_val (np.ndarray): HEALPix pixel values
        - nest (bool): True for nested pixel ordering, False for ring ordering
        - coord_frame (str): Coordinate frame ('galactic', 'icrs', etc.)
        - flags (np.ndarray, optional): Quality flags for each pixel
        """

    def query(self, coords, return_flags=False):
        """
        Query HEALPix map at coordinates.

        Parameters:
        - coords (SkyCoord): Query coordinates
        - return_flags (bool): Return quality flags along with values

        Returns:
        - float | np.ndarray: Dust values
        - tuple: (values, flags) if return_flags=True
        """

class HEALPixFITSQuery(HEALPixQuery):
    """HEALPix dust maps loaded from FITS files."""

    def __init__(self, fname, coord_frame, hdu=0, field=None, dtype='f8', scale=None):
        """
        Initialize HEALPix map from FITS file.

        Parameters:
        - fname (str): Path to HEALPix FITS file
        - coord_frame (str): Coordinate frame of the map
        - hdu (int): FITS HDU number to read
        - field (str, optional): Field name for multi-field maps
        - dtype (str): Data type for pixel values
        - scale (float, optional): Scaling factor for pixel values
        """

    def query(self, coords, **kwargs):
        """Query FITS-based HEALPix map."""

Unstructured Map Support

Base classes for dust maps with irregular spatial sampling.

class UnstructuredDustMap(DustMap):
    """Base class for unstructured (irregular) dust maps."""

    def __init__(self, pix_coords, max_pix_scale, metric_p=2, frame=None):
        """
        Initialize unstructured dust map.

        Parameters:
        - pix_coords (SkyCoord): Coordinates of map pixels/data points
        - max_pix_scale (float): Maximum pixel scale (degrees)
        - metric_p (int): Minkowski metric parameter (1=Manhattan, 2=Euclidean)
        - frame (str, optional): Coordinate frame
        """

    def query(self, coords, return_indices=False):
        """
        Query unstructured map using nearest neighbor interpolation.

        Parameters:
        - coords (SkyCoord): Query coordinates
        - return_indices (bool): Return pixel indices along with values

        Returns:
        - float | np.ndarray: Dust values
        - tuple: (values, indices) if return_indices=True
        """

Equirectangular Map Support

Base class for maps using Equirectangular (cylindrical) projections.

class EquirectangularDustMap(DustMap):
    """Base class for Equirectangular projection dust maps."""

    def __init__(self, pix_values, lon0, lon1, lat0, lat1,
                 dist0=None, dist1=None,
                 axis_order=('lon','lat','dist'),
                 frame='galactic',
                 dist_interp='linear'):
        """
        Initialize Equirectangular projection map.

        Parameters:
        - pix_values (np.ndarray): Map pixel values
        - lon0, lon1 (float): Longitude range (degrees)
        - lat0, lat1 (float): Latitude range (degrees)
        - dist0, dist1 (float, optional): Distance range (pc) for 3D maps
        - axis_order (tuple): Order of array axes
        - frame (str): Coordinate frame
        - dist_interp (str): Distance interpolation method ('linear', 'log')
        """

    def query(self, coords, **kwargs):
        """Query Equirectangular map with bilinear interpolation."""

Coordinate Utility Functions

Essential functions for coordinate system transformations and array handling.

def coord2healpix(coords, frame, nside, nest=True):
    """
    Convert astropy SkyCoord to HEALPix pixel indices.

    Parameters:
    - coords (SkyCoord): Input coordinates
    - frame (str): Coordinate frame for HEALPix map
    - nside (int): HEALPix resolution parameter
    - nest (bool): Use nested pixel ordering

    Returns:
    - int | np.ndarray: HEALPix pixel indices
    """

def coords_to_shape(gal, shape):
    """
    Reshape coordinate arrays to match target shape.

    Parameters:
    - gal (tuple): Tuple of coordinate arrays (l, b) or (l, b, d)
    - shape (tuple): Target array shape

    Returns:
    - tuple: Reshaped coordinate arrays
    """

def gal_to_shape(gal, shape):
    """
    Reshape Galactic coordinate arrays.

    Parameters:
    - gal (tuple): Galactic coordinate arrays (l, b, d)
    - shape (tuple): Target shape

    Returns:
    - tuple: Reshaped arrays
    """

Decorators

Function decorators that provide common coordinate and data validation functionality.

@ensure_coord_type
def decorated_function(coords, **kwargs):
    """
    Decorator ensuring input coordinates are astropy SkyCoord objects.
    Converts other coordinate types to SkyCoord if possible.
    """

@ensure_flat_galactic
def decorated_function(coords, **kwargs):
    """
    Decorator converting coordinates to flat Galactic coordinate arrays.
    Handles coordinate frame conversions automatically.
    """

@ensure_flat_coords
def decorated_function(coords, **kwargs):
    """
    Decorator ensuring coordinates are provided as flat arrays.
    Handles shape normalization and validation.
    """

@web_api_method(url, encoder, decoder)
def decorated_function(coords, **kwargs):
    """
    Decorator converting local method to web API call.

    Parameters:
    - url (str): API endpoint URL
    - encoder (callable): Function to encode request parameters
    - decoder (callable): Function to decode API response
    """

Exception Classes

Standard exceptions used throughout the dustmaps ecosystem.

class Error(Exception):
    """Base exception class for dustmaps."""

class CoordFrameError(Error):
    """Exception for unsupported coordinate frames."""

def data_missing_message(package, name):
    """
    Generate helpful error message for missing data files.

    Parameters:
    - package (str): Package/module name
    - name (str): Dataset name

    Returns:
    - str: Formatted error message with download instructions
    """

JSON Serialization Support

Utilities for serializing and deserializing complex data types used in dustmaps.

def serialize_tuple(o):
    """Serialize Python tuples for JSON storage."""

def deserialize_tuple(d):
    """Deserialize tuples from JSON data."""

def serialize_dtype(o):
    """Serialize NumPy dtypes for JSON storage."""

def deserialize_dtype(d):
    """Deserialize NumPy dtypes from JSON data."""

def serialize_ndarray(o):
    """Serialize NumPy arrays for JSON storage."""

def deserialize_ndarray(d):
    """Deserialize NumPy arrays from JSON data."""

def serialize_quantity(o):
    """Serialize Astropy Quantity objects for JSON storage."""

def deserialize_quantity(d):
    """Deserialize Astropy Quantities from JSON data."""

def serialize_skycoord(o):
    """Serialize Astropy SkyCoord objects for JSON storage."""

def deserialize_skycoord(d):
    """Deserialize SkyCoord objects from JSON data."""

def get_encoder():
    """
    Get JSON encoder with custom serializers for dustmaps types.

    Returns:
    - json.JSONEncoder: Custom encoder instance
    """

class MultiJSONDecoder(json.JSONDecoder):
    """JSON decoder with custom deserializers for dustmaps types."""

    def __init__(self, **kwargs):
        """Initialize decoder with custom object hook."""

    def object_hook(self, obj):
        """Custom object hook for deserializing complex types."""

Usage Patterns

Creating Custom Dust Map

from dustmaps.map_base import DustMap
import numpy as np
from astropy.coordinates import SkyCoord

class CustomDustMap(DustMap):
    def __init__(self, data_file):
        super().__init__()
        # Load custom map data
        self.load_data(data_file)

    def query(self, coords, **kwargs):
        # Implement custom query logic
        # Convert coords to map coordinates
        # Interpolate dust values
        return dust_values

# Use custom map
custom_map = CustomDustMap('my_dust_map.fits')
coord = SkyCoord(ra=180.0, dec=0.0, unit='deg', frame='icrs')
extinction = custom_map(coord)

Coordinate Validation

from dustmaps.map_base import ensure_coord_type, ensure_flat_galactic

@ensure_coord_type
@ensure_flat_galactic
def my_dust_query(coords, **kwargs):
    """Function with automatic coordinate validation and conversion."""
    # coords are guaranteed to be SkyCoord in flat Galactic coordinates
    l, b = coords.galactic.l.degree, coords.galactic.b.degree
    # Perform dust query
    return dust_values

Web API Integration

from dustmaps.map_base import WebDustMap, web_api_method

class MyWebDustMap(WebDustMap):
    def __init__(self):
        super().__init__(api_url='https://api.example.com/dust', map_name='mymap')

    @web_api_method('/query', encode_coords, decode_response)
    def query(self, coords, **kwargs):
        """Method automatically converted to web API call."""
        pass

Install with Tessl CLI