llama.files.healpix package¶

FileHandlers associated with HEALPix skymap loading and manipulation. Provides a subclass of FileHandler that specializes in loading and saving HEALPix FITS file skymaps and putting arbitrary skymap pixelizations and functions on the sphere into identical HEALPix pixelization schemes to simplify mathematical analyses.

Some documentation: http://healpix.sourceforge.net/html/intronode4.htm https://healpy.readthedocs.io/en/latest/healpy_pix.html

class llama.files.healpix.HEALPixPlots¶

Bases: llama.filehandler.FileHandler

Load HEALPix skymaps and save Mollweide-projection plots in PDF and PNG format to a compressed tarfile.

classmethod set_class_attributes(subclass)¶: See FileHandler.set_class_attributes; this method sets programatically-generated filenames for this class.

class llama.files.healpix.HEALPixSkyMapAnalysis¶

Bases: llama.files.healpix.HEALPixSkyMapFileHandler

Create output skymaps that are outputs of functions on input HEALPix skymaps.

FILENAME_PREFIX = None¶

static analysis_kernel(*skymaps)¶: A function that operates on an arbitrary number of skymaps and returns a single skymap. This is where the actual analysis algorithm is defined. Defaults to a simple elementwise product of skymaps, but can be overridden to do more complex analyses.

analyze_skymaps(*skymap_lists)¶: A function that takes an arbitrary number N of lists of input skymaps as its arguments and returns (results, indices), a tuple of lists where results is a list of results of combinations of skymaps from each skymap list (as output by analysis_kernel) and indices is a list of tuples of indices indicating which skymap was used from each skymap list.

classmethod set_class_attributes(subclass)¶: See FileHandler.set_class_attributes; this method additionally sets the FILENAME and DETECTORS attributes based on subclass.DEPENDENCIES and subclass.FILENAME_PREFIX.

write_healpix(skymaps, descriptions=None)¶: Write skymap, which should be a HEALPixSkyMap instance or a list containing a single HEALPixSkyMap instance, to the full path specified by this FileHandler instance. outfile must be an HDF5 file (inferred from file extension “.hdf5”).

class llama.files.healpix.HEALPixSkyMapFileHandler¶

Bases: llama.files.healpix.skymap.HEALPixRepresentableFileHandler

A FileHandler that corresponds to a file object containing HEALPix skymaps. Provides methods for reading HEALPix settings (i.e. Nsides, nesting method, and coordinate system) as well as reading and writing HEALPix files from numpy arrays. Methods do NOT assume a single skymap, and in general HEALPix-specific methods return an object for each skymap contained in the file described by this file handler in the form of a (possibly empty!) list.

get_healpix(nest=True, template_skymap=None)¶

Get a list of HEALPix skymaps stored in the file corresponding to this FileHandler.

Parameters

nest (bool, optional) – If True, return skymaps in HEALPix NEST ordering; if False, return in RING ordering.
template_skymap (HEALPixSkyMap, optional) – If provided, force the loaded skymaps to have the same HEALPix parameters as template_skymap. Overrides the nest parameter.

Returns

skymaps – HEALPixSkyMap instances with the data contained in this file.

Return type

list

get_healpix_descriptions(skymap_indices=None)¶

Get a list of descriptive strings for each HEALPix skymap contained in this file.

Parameters: skymap_indices (list) – A list of tuples describing the index of each skymap used to produce this output skymap, with each entry in the tuple corresponding to a detector. In this case, the descriptive strings will be generated based on this FileHandler instance’s DETECTORS property and the indices of the skymap_indices in skymap_indices. The ordering of the returned descriptive strings will match the ordering of skymap_indices. If skymap_indices is not specified, the HEALPix skymaps and their descriptions will be read from file. Note that for single-detector skymaps, the elements of the skymap_indices list should just be single-element tuples corresponding to the index of each skymap.

property num_triggers¶: The number of triggers described by this file. Useful mostly for quickly determining if this trigger list is empty.

static read_healpix_from_file(infile, nest=True)¶

Read the HEALPix skymap stored in infile and return a list containing a single HEALPixSkyMap instance containing the skymap and metadata (returns a list so that other implementations of this class can optionally return many skymaps). By default, return in HEALPix NEST ordering; optionally, return in RING ordering by specifying nest=False. infile can be either a FITS image file (inferred from file extension “.fits” or “.fits.gz”) or a specially-formatted HDF5 file (inferred from file extension “.hdf5”) of the sort produced by write_healpix_to_file. Note that if loading from HDF5 files, nest is ignored.

>>> import tempfile, os
>>> f = tempfile.NamedTemporaryFile(suffix='.hdf5', delete=False)
>>> fname = f.name
>>> f.close()
>>> skymap0 = HEALPixSkyMap(range(12))
>>> skymap1 = HEALPixSkyMap([1.]*12)
>>> HEALPixSkyMapFileHandler.write_healpix_to_file(
...     [skymap0, skymap1],
...     fname
... )
>>> skymaps = HEALPixSkyMapFileHandler.read_healpix_from_file(
...     fname
... )
>>> skymaps[0] == skymap0
True
>>> skymaps[1] == skymap1
True

write_healpix(skymaps, descriptions=None)¶: Write skymap, which should be a HEALPixSkyMap instance or a list containing a single HEALPixSkyMap instance, to the full path specified by this FileHandler instance. outfile can be either a FITS image file (inferred from file extension “.fits” or “.fits.gz”) or a specially-formatted HDF5 file (inferred from file extension “.hdf5”).

static write_healpix_to_file(skymaps, outfile, descriptions=None)¶

Write skymaps to outfile.

Parameters

skymaps (HEALPixSkyMap or list) – HEALPixSkyMap instance or list thereof to be written to file.
outfile (str) – Path to write skymap to. File extension must conform to either a FITS image file (inferred from file extension “.fits” or “.fits.gz”) or a specially-formatted HDF5 file (inferred from file extension “.hdf5”).
descriptions (list, optional) – A list of descriptive strings, each corresponding to the skymap in skymaps of the same index.

class llama.files.healpix.HEALPixSkyMapStats¶

Bases: llama.filehandler.JSONFile

Load a skymap from a HEALPixRepresentableFileHandler instance and generate stats on it, e.g. the likelihood integral for a HEALPixSkyMapAnalysis instance, and store them in JSON format. By default, only has one skymap file as a dependency and stores the integral of that skymap as integrated_likelihood.

classmethod set_class_attributes(subclass)¶: See FileHandler.set_class_attributes; this method sets programatically-generated filenames for this class.

class llama.files.healpix.LvcHEALPixSkyMapFileHandler¶

Bases: llama.files.healpix.HEALPixSkyMapFileHandler

A HEALPixSkyMapFileHandler using astropy.table.Table to read the input file (in order to accomodate the NUNIQ pixel ordering/multi-resolution skymaps).

static read_healpix_from_file(infile, nest=True)¶

Read the HEALPix skymap stored in infile and return a list containing a single HEALPixSkyMap instance containing the skymap and metadata (returns a list so that other implementations of this class can optionally return many skymaps). By default, return in HEALPix NEST ordering; optionally, return in RING ordering by specifying nest=False. infile can be either a FITS image file (inferred from file extension “.fits” or “.fits.gz”) or a specially-formatted HDF5 file (inferred from file extension “.hdf5”) of the sort produced by write_healpix_to_file. Note that if loading from HDF5 files, nest is ignored.

>>> import tempfile, os
>>> f = tempfile.NamedTemporaryFile(suffix='.hdf5', delete=False)
>>> fname = f.name
>>> f.close()
>>> skymap0 = HEALPixSkyMap(range(12))
>>> skymap1 = HEALPixSkyMap([1.]*12)
>>> HEALPixSkyMapFileHandler.write_healpix_to_file(
...     [skymap0, skymap1],
...     fname
... )
>>> skymaps = HEALPixSkyMapFileHandler.read_healpix_from_file(
...     fname
... )
>>> skymaps[0] == skymap0
True
>>> skymaps[1] == skymap1
True

llama.files.healpix.healpix_skymap_analysis_factory(dependencies, bases=(<class 'llama.files.healpix.HEALPixSkyMapAnalysis'>, ), make_plotters=False, make_stats=False, noclobber=False)¶

Programmatically create analysis classes based on input skymaps and analysis algorithm. New classes are saved to the calling namespace (consider this a shortcut macro for making FileHandler subclasses programatically).

Parameters

dependencies (list) – FileHandler subclasses that implement the get_healpix method and can thus be used to run an analysis using some HEALPixSkyMapAnalysis implementation’s analysis_kernel.
bases (tuple) – Base classes for the class being generated in the form of a tuple, e.g. (base1, base2, ...)
make_plotters (bool, optional) – A boolean specifying whether HEALPixPlots class implementations should be created to accompany each HEALPixSkyMapAnalysis class generated.
make_stats (bool, optional) – A boolean specifying whether HEALPixSkyMapStats implementations should be created to accompany each HEALPixSkyMapAnalysis class generated.
noclobber (bool, optional) – If true, don’t overwrite existing variable names; instead, throw a ValueError.

Returns

new_classes – The new classes generated, where each key is the name of the new class and each value is the new class itself.

Return type

dict

llama.files.healpix.pixel_radii_rad()¶: Get the maximum pixel radii in radians for each value of k, where nside = 2**k.

llama.files.healpix.scale2nside(scale, degrees=True)¶

Find the correct HEALPix scale NSIDE for a given feature resolution. For example, to capture features of size 0.2 degrees across, you want a HEALPix skymap with NSIDE large enough so that the max inter-pixel distance is less than 0.1 degrees. Note that HEALPix skymaps cannot have NSIDE > 2**30; if higher resolution is required, a ValueError will be raised.

Parameters

scale (int) – The angular size of the smallest feature you need to capture (in the specified units).
degrees (bool, optional) – If true, the feature size is assumed to be in degrees. Otherwise, it is taken to be in radians.

Returns

nside – The minimum NSIDE parameter required to capture features with scale larger than scale. Will always be a power of 2 less than or equal to 2**30.

Return type

int

Raises

ValueError – If the feature scale is too small to represent with a HEALPix map.

llama.files.healpix.subpixels(indices, inputnside, nside, nest=True)¶

Take a list of indices into a HEALPix skymap with NSIDE=inputnside and return a list of indices into a HEALPix skymap with NSIDE=nside where the returned list of indices correspond to subpixels of the pixels indexed from the original skymap size. Useful for getting higher-resolution subpixels for a list of pixels of interest.

Returns

subindices – Indices for a HEALPix skymap with NSIDE=nside that correspond to subpixels from the input pixel indices, sorted in ascending order.

Return type

array

Parameters

indices (array) – Indices for a HEALPix skymap with NSIDE=inputnside. Repeated indices are ignored.
inputnside (int) – HEALPix NSIDE (i.e. resolution) for the input pixels.
nside (int) – NSIDE for the output pixels (must be greater than inputnside)
nest (bool, optional) – If true, input and output skymaps are interpreted as havin NEST ordering. If false, they are interpreted as having RING ordering.

Raises

ValueError – If nside or inputnside are not valid NSIDE HEALPix parameters (i.e. not equal to 2**k for some integer k between 0 and 29), if inputnside is greater than nside, or if the indices are invalid.

Submodules