Source code for LineStacker

"""
Stacking positions (:class:`Coord`, :func:`readCatalog`, :func:`makeCoords`,
:func:`readCoords`), their conversion to pixels, random positions, and the
package settings (:data:`verbose`, :data:`casa_logfile`). The stacking itself
is in :mod:`LineStacker.image` (cubes) and :mod:`LineStacker.OneD_Stacker`
(spectra); :mod:`LineStacker.analysisTools` tests stacks.
"""
# -*- coding: utf-8; -*-
# LineStacker, Python module for stacking data cubes.
# Copyright (C) 2019  Jean-Baptiste Jolly
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor,
# Boston, MA 02110-1301, USA.

#LineStacker is based on Stacker by Lukas Lindroos,
#Most of the main module (this one) is hence directly taken from Stacker
"""
    Library to stack interferometric data-cubes, or lines from 1D data.
"""

import copy as _copy
import os
import re
import numpy as np


__author__ = 'Jean-Baptiste Jolly'
__copyright__ = 'Copyright 2019'
__license__ = 'GPL'
__version__ = '2.0.1'
__maintainer__ = 'Jean-Baptiste Jolly'
__email__ = 'jbjolly@mpe.mpg.de'


def _major_minor(version):
    nums = re.findall(r'\d+', str(version))[:2]
    return tuple(int(n) for n in nums) + (0,) * (2 - len(nums))


def _astropy_numpy_problem(numpy_version=None, astropy_version=None, astropy_path=None):
    """Message if the astropy that would be imported cannot work with this
    NumPy, else None. astropy < 7.2 uses np.in1d, which NumPy 2.4 removed;
    this happens e.g. when CASA's bundled NumPy is mixed with an older astropy
    from another environment. Checked without importing astropy."""
    try:
        if astropy_version is None:
            from importlib.metadata import version
            from importlib.util import find_spec
            astropy_version = version('astropy')
            spec = find_spec('astropy')
            astropy_path = os.path.dirname(spec.origin) if spec and spec.origin else '?'
        numpy_version = numpy_version or np.__version__
    except Exception:            # astropy not installed: reported when needed
        return None
    if _major_minor(numpy_version) < (2, 4) or _major_minor(astropy_version) >= (7, 2):
        return None
    return ('astropy {0} (from {1}) cannot be used with NumPy {2}: astropy < 7.2 needs '
            'np.in1d, which NumPy 2.4 removed, so reading coordinates and cubes will fail with '
            "\"module 'numpy' has no attribute 'in1d'\". Install astropy >= 7.2 into the Python "
            'that runs LineStacker; for the CASA prompt (monolithic CASA): '
            "PYTHONNOUSERSITE=1 <casa>/bin/pip3 install 'astropy>=7.2'.").format(
                astropy_version, astropy_path, numpy_version)


def _warn_astropy_numpy():
    msg = _astropy_numpy_problem()
    if msg:
        import warnings
        warnings.warn(msg, stacklevel=3)


_warn_astropy_numpy()


#: When True (default), LineStacker reports what it does, the files it writes
#: (with their full path), what it reads, and progress bars. Set
#: ``LineStacker.verbose = False`` to silence it; every function that prints
#: also takes ``verbose=True/False`` to decide for one call. Warnings about
#: possible problems are shown either way.
verbose = True

#: Where CASA writes its log when LineStacker starts CASA itself (only to
#: read or write CASA images; FITS cubes never start CASA):
#:
#: - ``'auto'`` (default): one file, ``<temporary dir>/linestacker-casa-<user>.log``,
#:   instead of a new ``casa-<date>.log`` in the working directory at every
#:   run; a ``logfile`` set in ``~/.casa/config.py`` is used instead.
#: - a path: CASA's log goes there.
#: - ``None``: no log file.
#: - ``'casa'``: CASA's own default (``casa-<date>.log`` in the working directory).
#:
#: Set it before the first CASA image is read. Inside a CASA session, or once
#: casatools/casatasks were imported, CASA's own settings apply.
casa_logfile = 'auto'

#: Cubes are read once and kept in memory. When True (default) LineStacker
#: checks, every time it uses a cached cube, that its file has not changed
#: (about 0.1 ms per CASA image, a few microseconds per FITS file) and reads
#: it again if it has. Set ``LineStacker.cache_check = False`` to trust the
#: cache until ``LineStacker.image.clear_cache()``.
cache_check = True


def _verbose(flag=None):
    """A function's verbose argument, defaulting to LineStacker.verbose."""
    return bool(verbose) if flag is None else bool(flag)


def _info(message, flag=None):
    if _verbose(flag):
        print('LineStacker: ' + message, flush=True)


# CASA writes sexagesimal coordinates with dots as deg/min/sec separators
# (e.g. '-027.45.34.566' for declination, sometimes also '03.30.34.79' for RA).
# Astropy's angle parser doesn't understand that form -- it expects colons
# ('-027:45:34.566'), letter separators ('-027d45m34.566s'), or spaces. This
# helper normalises CASA's dot form to colons; anything else passes through.
_CASA_SEXAGESIMAL_RE = re.compile(r'^\s*([+-]?\d+)\.(\d+)\.(\d+(?:\.\d+)?)\s*$')


def _normalize_sexagesimal(s):
    """Convert CASA dot-separated sexagesimal ('DD.MM.SS.fff') to colon form
    ('DD:MM:SS.fff'). Returns the input unchanged if it doesn't match the
    CASA pattern (so plain degrees, 'HH:MM:SS', '00h42m30s', and space-
    separated forms all pass through untouched)."""
    if not isinstance(s, str):
        return s
    m = _CASA_SEXAGESIMAL_RE.match(s)
    if m:
        return '{0}:{1}:{2}'.format(m.group(1), m.group(2), m.group(3))
    return s


[docs] def round_half_up(x): """Round like Python 2's round() did (halves away from zero). Python 3's round() rounds halves to even, which would move some stack centres by one channel compared with LineStacker < 2.0.""" return int(np.floor(np.abs(x) + 0.5) * np.sign(x))
[docs] class Coord: """ Describes a stacking position on an image. Class used internally to represent coordinates. May describe a physical coordinate or a pixel coordinate. Init: Creates a coordinate. A pixel coordinate should always specify to which image it belongs. Physical coordinates are astropy angles (as produced by **LineStacker.readCoords**, **readCatalog** and **makeCoords**) or plain numbers in radians, in the equatorial frame given by **frame** (default ICRS). Parameters --------- ra x coordinate of stacking target (RA, or x pixel for pixel coordinates). Also available as ``coord.x``. dec y coordinate of stacking target (Dec, or y pixel). Also ``coord.y``. spec spectral coordinate of stacking target (redshift, observed spectral value or channel depending on spectralMethod). Also ``coord.z``. weight Weight of the source for mean stacking. Default is 1. image Cube associated to the source, either its path or its index in the list of images given to the stacking function. Automatically set with **LineStacker.readCoords**. type Either 'physical' or 'pixel' imagenumber Index of the cube in the image list (set by readCoords to the index of the coordinate file the source was read from). frame Equatorial frame of ra, dec: 'icrs' (default), 'fk5' (J2000), 'fk4'... """ def __init__(self, ra, dec, spec='continuum', weight=1, image=0, type='physical', imagenumber=-1, frame='icrs', z=None, index=None): self.ra = ra self.dec = dec self.spec = spec if z is None else z self.weight = weight self.image = image self.type = type self.imagenumber = imagenumber self.frame = frame self.index = index # Stacker-era attribute names, still used by older scripts. @property def x(self): return self.ra @x.setter def x(self, value): self.ra = value @property def y(self): return self.dec @y.setter def y(self, value): self.dec = value @property def z(self): return self.spec @z.setter def z(self, value): self.spec = value
[docs] def copy(self): """Independent copy (weights arrays are copied too).""" new = _copy.copy(self) if isinstance(self.weight, np.ndarray): new.weight = self.weight.copy() elif isinstance(self.weight, list): new.weight = list(self.weight) return new
def __str__(self): return '{0}, {1}'.format(self.ra, self.dec) def __repr__(self): return 'Coord({0}, {1}, spec={2}, weight={3}, image={4!r}, type={5!r})'.format( self.ra, self.dec, self.spec, self.weight, self.image, self.type)
[docs] def readCoordsNamesGUI(): """ Opens a file dialog (Tk) to select coordinate files; returns their paths. """ import tkinter from tkinter import filedialog root = tkinter.Tk() root.withdraw() filez = filedialog.askopenfilenames(initialdir=".", title="Select coord files", filetypes=(("txt files", "*.txt"), ("all files", "*.*"))) root.destroy() return list(filez)
class _CoordFormatError(RuntimeError): """A coordinate file could not be parsed with the current delimiter."""
[docs] def readCoords(coordfiles, unit='deg', lineON=True, delimiter='default', frame='icrs', images='default', type='physical', verbose=None): """ Reads coordinate files (one file per cube, the format of LineStacker 1.x) and returns a list of LineStacker.Coord. Parameters --------- coordfiles: List of path to coordinate files. Files in csv format: x (RA) and y (Dec) in the equatorial frame given by **frame**. If using to stack line, redshift should be in the third column. A weight may be added in the last column to weight positions for mean stacking. If set to **None** stacking position is defined as the center of each cube. Coordinates can either be in degrees (e.g. "10.625, 41.2"), or in hour angle + deg, as hms dms format (e.g. "'00h42m30s', '+41d12m00s'"), or as hour angle + deg without hms nor dms (e.g. "00 42 30, +41 12 00" or CASA's "00:42:30, +41.12.00"). A plain number is always in **unit**, also next to a sexagesimal value. Empty lines and lines starting with # are ignored. unit: Unit of plain numbers. Allows two values, **'deg'** or **'rad'**. lineON Either **True** or **False**, should be set to **True** if doing line stacking. Default is **True**. delimiter: Delimiter used to separate coordinates, 'default' tries comma, space and tab (in that order). With commas, an empty field in a line (e.g. "x, y, , w") is an error for line stacking. frame Equatorial frame of the positions: 'icrs' (default), 'fk5' (J2000), 'fk4'... images List of images to which each coordfile is assigned, if set to 'default', image names are same as coordfiles, with '.fits' instead of '_coord.txt'. The stacking functions also accept coordinates whose image is not in their imagenames list: the n-th coordinate file is then matched to the n-th image. type Coordinate type, can be either 'physical' (default), or 'pixel' verbose report how many positions were read (default: LineStacker.verbose) """ if coordfiles is None: _info('coordfile is None, stacking on the center', verbose) return None if isinstance(coordfiles, (str, os.PathLike)): coordfiles = [coordfiles] coordfiles = [os.fspath(name) for name in coordfiles] if isinstance(delimiter, str) and delimiter=='default': delimiters=[',',' ','\t'] delimiterNames=['comma', 'space', 'tab'] else: delimiters=[delimiter] delimiterNames=[repr(delimiter)] if isinstance(images, str) and images=='default': images=[coordname.replace('_coord.txt', '.fits') for coordname in coordfiles] elif isinstance(images, (str, os.PathLike)): images=[images] else: images=list(images) if len(images) < len(coordfiles): raise ValueError('{0} coordinate files but only {1} images given'.format(len(coordfiles), len(images))) errors = [] for (j, delim) in enumerate(delimiters): try: coords = _readCoords(coordfiles, unit=unit, lineON=lineON, delimiter=delim, frame=frame, images=images, type=type) except _CoordFormatError as err: errors.append('{0}: {1}'.format(delimiterNames[j], err)) continue _info('read {0} position{1} from {2} coordinate file{3}'.format( len(coords), 's' if len(coords) != 1 else '', len(coordfiles), 's' if len(coordfiles) != 1 else ''), verbose) return coords raise Exception("Could not read the coordinate files. If set to default delimiters can be comma, space, and tab. " "Otherwise feed own delimiter to this function.\n" + '\n'.join(errors))
def _parse_angle_pair(ra, dec, unit, frame): from astropy.coordinates import SkyCoord import astropy.units as u uni = {'deg': u.deg, 'rad': u.rad}.get(unit) if uni is None: raise ValueError("unit must be 'deg' or 'rad'") ra_str = _normalize_sexagesimal(ra) dec_str = _normalize_sexagesimal(dec) def number(text): try: return float(text) except ValueError: return None ra_num, dec_num = number(ra_str), number(dec_str) if ra_num is not None and dec_num is not None: return SkyCoord(ra=ra_num*uni, dec=dec_num*uni, frame=frame) if (ra_num is None) != (dec_num is None): # One plain number and one sexagesimal value: the number is in `unit` # (a decimal RA next to a sexagesimal Dec was read as hours). from astropy.coordinates import Angle def angle(text, sexagesimal_unit): return Angle(text) if _HAS_UNIT_LETTER.search(text) else Angle(text, unit=sexagesimal_unit) try: ra_q = ra_num * uni if ra_num is not None else angle(ra_str, u.hourangle) dec_q = dec_num * uni if dec_num is not None else angle(dec_str, u.deg) return SkyCoord(ra=ra_q, dec=dec_q, frame=frame) except (u.UnitsError, ValueError) as err: raise _CoordFormatError('Angles must be in a format recognized by astropy.coordinates, ' 'with ra in hourangle and dec in deg ({0})'.format(err)) try: return SkyCoord(ra=ra_str, dec=dec_str, frame=frame) except (u.UnitsError, ValueError): pass try: return SkyCoord(ra=ra_str, dec=dec_str, frame=frame, unit=(u.hourangle, u.deg)) except ValueError as err: raise _CoordFormatError('Angles must be in a format recognized by astropy.coordinates, ' 'with ra in hourangle and dec in deg ({0})'.format(err)) def _readCoords(coordfiles, unit='deg', lineON=True, delimiter=',', frame='icrs', images='', type='physical'): import csv coords = [] for (i, coordi) in enumerate(coordfiles): with open(coordi, 'r') as fh: rows = list(csv.reader(fh, delimiter=delimiter)) for lineno, row in enumerate(rows, 1): row = [field.strip() for field in row] if delimiter.strip() != '' and not (row and row[0].startswith('#')): # With commas (or another visible delimiter) an empty field # is a missing value, not a repeated delimiter: 'x, y, , w' # must not be read as x, y, z=w. while row and row[-1] == '': row.pop() if lineON and '' in row: raise _CoordFormatError('{0}, line {1}: empty field {2} (structure should be x, y, z (, w))'.format( coordi, lineno, row.index('') + 1)) row = [field for field in row if field != ''] if len(row) == 0 or row[0].startswith('#'): continue if len(row) < 2: raise _CoordFormatError('{0}, line {1}: expected at least 2 columns, found {2}'.format(coordi, lineno, len(row))) lineMode = lineON if not lineMode and len(row) == 4: lineMode = True import warnings warnings.warn('{0}, line {1}: lineON=False but 4 columns found; reading it as x, y, z, w ' '(line mode)'.format(coordi, lineno), stacklevel=3) try: if lineMode: if len(row) == 4: weight = float(row[3]) elif len(row) == 3: weight = 1. else: raise _CoordFormatError('{0}, line {1}: structure should be x, y, z (, w)'.format(coordi, lineno)) spec = float(row[2]) else: if len(row) == 3: weight = float(row[2]) elif len(row) == 2: weight = 1. else: raise _CoordFormatError('{0}, line {1}: too many columns, structure should be x, y, w ' '(or x, y, spec, w and LineON set to True)'.format(coordi, lineno)) spec = 'continuum' except ValueError as err: raise _CoordFormatError('{0}, line {1}: {2}'.format(coordi, lineno, err)) if type == 'physical': coord = _parse_angle_pair(row[0], row[1], unit, frame) coords.append(Coord(coord.ra, coord.dec, spec=spec, weight=weight, image=images[i], imagenumber=i, type='physical', frame=frame)) elif type == 'pixel': try: x, y = float(row[0]), float(row[1]) except ValueError as err: raise _CoordFormatError('{0}, line {1}: {2}'.format(coordi, lineno, err)) coords.append(Coord(x, y, spec=spec, weight=weight, image=images[i], imagenumber=i, type='pixel')) else: raise ValueError("type must be 'physical' or 'pixel'") return coords _HAS_UNIT_LETTER = re.compile(r'[hdms°\'"]', re.IGNORECASE) _SEXAGESIMAL = re.compile(r'^([+-]?)(\d+)(?::|\s+)(\d+)(?::|\s+)(\d+(?:\.\d*)?)$') def _per_source(values, n, name): """One value per source: scalars (and strings) are repeated n times.""" if values is None: return [None] * n if isinstance(values, (str, os.PathLike)) or np.ndim(values) == 0: return [values] * n seq = list(values) if len(seq) != n: raise ValueError('{0} has {1} values but there are {2} sources'.format(name, len(seq), n)) return seq def _equatorial(frame): """Name of an equatorial astropy frame (ra/dec), or ValueError.""" from astropy.coordinates import frame_transform_graph name = frame if isinstance(frame, str) else getattr(frame, 'name', None) cls = frame_transform_graph.lookup_name(name) if name else None if cls is None: raise ValueError('unknown coordinate frame {0!r}'.format(frame)) names = cls().representation_component_names if 'ra' not in names or 'dec' not in names: raise ValueError("frame {0!r} has no RA/Dec: LineStacker coordinates are equatorial ('icrs', 'fk5' " "for J2000, 'fk4'...). Convert the positions, e.g. SkyCoord(...).icrs".format(name)) return name def _angles_to_sky(ra, dec, unit, frame): """SkyCoord (1D) from numbers in unit, astropy angles/quantities, or sexagesimal strings (RA in hours; CASA's dotted declinations accepted).""" from astropy.coordinates import SkyCoord import astropy.units as u uni = {'deg': u.deg, 'rad': u.rad}.get(unit) if uni is None: raise ValueError("unit must be 'deg' or 'rad'") def as_degrees(values, sexagesimal_unit, axis): # Quantities, and table columns with a unit (a Column always has a # .unit attribute, None when it has no unit) if getattr(values, 'unit', None) is not None: q = values.quantity if hasattr(values, 'quantity') else u.Quantity(values) return q.reshape(-1).to_value(u.deg) if hasattr(values, 'unit'): values = np.asarray(values) # a unit-less Column: its values arr = np.atleast_1d(np.asarray(values, dtype=object)) try: return (np.asarray(arr, dtype=float) * uni).to_value(u.deg) except (TypeError, ValueError): pass strings = [_normalize_sexagesimal(str(v).strip()) for v in arr] parts = [_SEXAGESIMAL.match(s) for s in strings] if all(parts): # common case: 'DD:MM:SS.s' or 'DD MM SS.s' sign = np.array([-1. if p.group(1) == '-' else 1. for p in parts]) dms = np.array([[float(p.group(2)), float(p.group(3)), float(p.group(4))] for p in parts]) if np.all(dms[:, 1] < 60) and np.all(dms[:, 2] < 60): value = sign * (dms[:, 0] + dms[:, 1] / 60. + dms[:, 2] / 3600.) return value * (15. if sexagesimal_unit == u.hourangle else 1.) out = np.empty(len(arr)) for k, v in enumerate(arr): # strings: each value read on its own s = _normalize_sexagesimal(str(v).strip()) try: out[k] = (float(s) * uni).to_value(u.deg) continue except ValueError: pass try: angle = Angle(s) if _HAS_UNIT_LETTER.search(s) else Angle(s, unit=sexagesimal_unit) except Exception as err: raise ValueError('source {0}: cannot read {1} {2!r} ({3})'.format(k, axis, str(v), err)) out[k] = angle.deg return out from astropy.coordinates import Angle ra_deg = as_degrees(ra, u.hourangle, 'RA') dec_deg = as_degrees(dec, u.deg, 'Dec') if len(ra_deg) != len(dec_deg): raise ValueError('ra has {0} values but dec has {1}'.format(len(ra_deg), len(dec_deg))) return SkyCoord(ra=ra_deg * u.deg, dec=dec_deg * u.deg, frame=frame)
[docs] def makeCoords(ra, dec=None, z=None, weight=None, image=None, unit='deg', frame='icrs', type='physical', verbose=None): """ Builds stacking coordinates directly from Python values (lists, numpy arrays, astropy quantities or a SkyCoord), e.g. in a notebook. Parameters --------- ra, dec Positions, one value per source. Numbers are in **unit** (or pixels if type='pixel'); astropy Angles/Quantities carry their own unit; strings are sexagesimal with RA in hours ('03:31:04.15', '-27:40:59.87', or CASA's '-027.40.59.866'). A SkyCoord can be given as ra, with dec=None. z Spectral value of each source: the redshift for spectralMethod='z' (the default of LineStacker.image.stack), the observed frequency/wavelength for 'obsSpec', the channel for 'channel'. None for continuum stacking. weight Weight of each source for mean stacks (default 1). image Cube of each source (path to a FITS file or CASA image), or one path for all sources. None when all sources lie in the single cube given to the stacking function. unit 'deg' (default) or 'rad', for plain numbers. frame Equatorial frame of the positions: 'icrs' (default), 'fk5' (J2000), 'fk4'... A SkyCoord in any frame (e.g. Galactic) is converted to it. type 'physical' (sky positions, default) or 'pixel'. Returns ------- list of LineStacker.Coord to give to LineStacker.image.stack (imagenames can then be omitted when every source names its cube). """ from astropy.coordinates import SkyCoord if type not in ('physical', 'pixel'): raise ValueError("type must be 'physical' or 'pixel'") frame = _equatorial(frame) if dec is None: if not isinstance(ra, SkyCoord): raise ValueError('dec is missing (or give a SkyCoord as ra)') if type == 'pixel': raise ValueError("a SkyCoord holds sky positions: use type='physical'") sky = ra.transform_to(frame) sky = sky.reshape((1,)) if sky.isscalar else sky.reshape(-1) elif type == 'physical': sky = _angles_to_sky(ra, dec, unit, frame) else: xs = np.atleast_1d(np.asarray(ra, dtype=float)) ys = np.atleast_1d(np.asarray(dec, dtype=float)) if len(xs) != len(ys): raise ValueError('ra has {0} values but dec has {1}'.format(len(xs), len(ys))) if type == 'physical': xs, ys = sky.ra, sky.dec # extract once: indexing a SkyCoord is slow n = len(sky) else: n = len(xs) specs = _per_source(z, n, 'z') weights = _per_source(1. if weight is None else weight, n, 'weight') images = _per_source(image, n, 'image') for k in range(n): if specs[k] is not None and not np.isfinite(float(specs[k])): raise ValueError('source {0}: z is {1}; every source needs a finite spectral value ' '(or z=None for continuum)'.format(k, specs[k])) if not np.isfinite(float(weights[k])) or float(weights[k]) < 0: raise ValueError('source {0}: weight is {1}; weights must be finite and >= 0'.format(k, weights[k])) if images[k] is not None and not os.fspath(images[k]).strip(): raise ValueError('source {0}: its image (cube) name is empty'.format(k)) coords = [] for k in range(n): spec = 'continuum' if specs[k] is None else float(specs[k]) img = os.fspath(images[k]) if images[k] is not None else None if type == 'physical': px, py = xs[k], ys[k] else: px, py = float(xs[k]), float(ys[k]) # imagenumber -1: the cube is matched by name only, never by order coords.append(Coord(px, py, spec=spec, weight=float(weights[k]), image=img, imagenumber=-1, type=type, frame=frame)) _info('made {0} coordinate{1}'.format(n, 's' if n != 1 else ''), verbose) return coords
_CATALOG_ALIASES = { 'ra': ('ra', 'ra_deg', 'raj2000', 'ra_j2000', 'alpha'), 'dec': ('dec', 'dec_deg', 'dej2000', 'decj2000', 'dec_j2000', 'delta'), 'z': ('z', 'redshift', 'zspec', 'z_spec', 'spec'), 'weight': ('weight', 'weights'), 'image': ('image', 'imagename', 'cube', 'file', 'filename', 'path'), } def _read_table(catalog, format): """astropy Table and the folder of the catalogue file (None if not a file).""" from astropy.table import Table if isinstance(catalog, Table): return catalog, None if hasattr(catalog, 'columns') and hasattr(catalog, 'to_dict') and not isinstance(catalog, (str, os.PathLike)): return Table.from_pandas(catalog), None # pandas DataFrame if isinstance(catalog, dict): return Table(catalog), None path = os.fspath(catalog) if not os.path.isfile(path): raise FileNotFoundError('catalogue not found: {0}'.format(path)) import warnings lower = path.lower() binary = lower.endswith(('.fits', '.fit', '.fts', '.fits.gz', '.vot', '.votable', '.xml', '.hdf5', '.h5', '.parquet')) with warnings.catch_warnings(): warnings.simplefilter('ignore') # unit-parsing chatter of some writers if format is not None: table = Table.read(path, format=format) elif binary: table = Table.read(path) # its own error is the useful one else: try: table = Table.read(path) except Exception as first: try: table = Table.read(path, format='ascii') except Exception as second: raise ValueError('cannot read the catalogue {0}: {1} (as a text table: {2}). Give format=, ' "e.g. 'ascii.csv' or 'fits'.".format(path, first, second)) from second return table, os.path.dirname(os.path.abspath(path)) def _find_column(table, wanted, role, default): """Column of table for role ('ra', 'dec', ...): the name given, matched case-insensitively, and, when the default name was kept, its aliases.""" if wanted is None: return None lower = {name.lower(): name for name in table.colnames} names = [wanted] if wanted == default: names += list(_CATALOG_ALIASES[role]) for name in names: if name.lower() in lower: return lower[name.lower()] if wanted != default or role in ('ra', 'dec'): raise ValueError('catalogue has no column {0!r} for {1} (columns: {2})'.format( wanted, role, ', '.join(table.colnames))) return None def _column_values(table, name, role): col = table[name] mask = np.ma.getmaskarray(col) if mask.any(): raise ValueError('catalogue column {0!r} ({1}) has missing values in rows {2}'.format( name, role, list(np.where(mask)[0][:10]))) if col.unit is not None and role in ('ra', 'dec'): return col.quantity data = np.asarray(col) if data.dtype.kind in 'SU': data = np.char.strip(data.astype(str)) if role == 'image': def missing(v): if v is None or (isinstance(v, (float, np.floating)) and not np.isfinite(v)): return True return str(v).strip().lower() in ('', 'nan', 'none', '--') empty = [k for k, v in enumerate(data) if missing(v)] if data.dtype.kind not in 'SUO': data = data.astype(str) if empty: raise ValueError('catalogue column {0!r} (image) is empty in rows {1}'.format(name, empty[:10])) elif role in ('z', 'weight'): try: values = np.asarray(data, dtype=float) except ValueError: raise ValueError('catalogue column {0!r} ({1}) is not numeric'.format(name, role)) bad = np.where(~np.isfinite(values))[0] if bad.size: raise ValueError('catalogue column {0!r} ({1}) has non-finite values in rows {2}'.format( name, role, list(bad[:10]))) if role == 'weight' and np.any(values < 0): raise ValueError('catalogue column {0!r} has negative weights in rows {1}'.format( name, list(np.where(values < 0)[0][:10]))) return data def _resolve_cube(name, base, imagedir): name = os.path.expanduser(str(name).strip()) if os.path.isabs(name): return os.path.normpath(name) if imagedir is not None: return os.path.normpath(os.path.join(imagedir, name)) if base is not None: candidate = os.path.normpath(os.path.join(base, name)) if os.path.exists(candidate) or not os.path.exists(name): return candidate return os.path.normpath(name)
[docs] def readCatalog(catalog, ra='ra', dec='dec', z='z', weight='weight', image='image', unit='deg', frame='icrs', imagedir=None, format=None, verbose=None): """ Reads the stacking positions of all sources from one catalogue table, one row per source. The cube of each source is given in the table (image column); it is never guessed. Parameters --------- catalog Path to a table file: CSV (with a header line), ECSV, FITS table, VOTable or any format astropy.table reads (see **format**). Also accepted: an astropy Table, a pandas DataFrame or a dict of columns. ra, dec Column names of the positions (default 'ra', 'dec'; also found: RAJ2000/DEJ2000, ra_deg/dec_deg...). Numbers are in **unit** unless the column has a unit (FITS, ECSV, VOTable); strings are sexagesimal with RA in hours (CASA's '-027.40.59.866' accepted). z Column of the spectral value (default 'z', also 'redshift'): the redshift, or the observed frequency/wavelength or channel for spectralMethod 'obsSpec'/'channel'. If the catalogue has no such column (or z=None) the positions are for continuum stacking. weight Column of the weights (optional, default 1). image Column naming the cube of each source (FITS file or CASA image; default 'image', also 'cube', 'file'). Relative paths are looked up next to the catalogue first, then from the working directory. Without this column, give the stacking function a single cube. unit 'deg' (default) or 'rad', for unit-less numeric positions. imagedir Folder to which relative cube names are relative (overrides the rule above). format astropy table format, e.g. 'ascii.csv', 'ascii.commented_header' (default: guessed from the file). verbose report what was read (default: LineStacker.verbose) Returns ------- list of LineStacker.Coord for LineStacker.image.stack and the analysis tools; imagenames can be omitted there when the catalogue has an image column. """ table, base = _read_table(catalog, format) if len(table) == 0: raise ValueError('the catalogue is empty') cols = {} for role, wanted, default in (('ra', ra, 'ra'), ('dec', dec, 'dec'), ('z', z, 'z'), ('weight', weight, 'weight'), ('image', image, 'image')): cols[role] = _find_column(table, wanted, role, default) values = {role: _column_values(table, name, role) for role, name in cols.items() if name is not None} images = None if 'image' in values: images = [_resolve_cube(v, base, imagedir) for v in values['image']] coords = makeCoords(values['ra'], values['dec'], z=values.get('z'), weight=values.get('weight'), image=images, unit=unit, frame=frame, verbose=False) source = os.path.basename(os.fspath(catalog)) if isinstance(catalog, (str, os.PathLike)) else 'the table' ncubes = len(set(images)) if images is not None else 0 _info('read {0} position{1}{2} from {3}{4}'.format( len(coords), 's' if len(coords) != 1 else '', ' in {0} cube{1}'.format(ncubes, 's' if ncubes != 1 else '') if images is not None else '', source, '' if 'z' in values else ' (z=None: continuum positions)' if z is None else ' (no {0!r} column: continuum positions)'.format(z)), verbose) return coords
def _cube_list(coords, imagenames): """The cubes to use: imagenames as given, or else the cubes named by the coordinates (readCatalog image column, makeCoords image=...).""" if imagenames is not None and not isinstance(imagenames, (str, os.PathLike)) and len(imagenames) > 0: return [os.fspath(n) for n in imagenames] if isinstance(imagenames, (str, os.PathLike)): return [os.fspath(imagenames)] if coords is None or len(coords) == 0: raise ValueError('imagenames is empty: give the list of cubes to stack') names = [] for c in coords: if not isinstance(c.image, (str, os.PathLike)): raise ValueError('imagenames was not given and the coordinate {0!r} does not name its cube. ' 'Give imagenames, or the cube of each source (image column of readCatalog, ' 'image= of makeCoords).'.format(c)) name = os.fspath(c.image) if name not in names: names.append(name) return names def _image_index(coord, imagenames): """Index in imagenames of the cube a coordinate belongs to.""" img = coord.image if isinstance(img, (int, np.integer)) and not isinstance(img, bool): if 0 <= img < len(imagenames): return int(img) elif isinstance(img, (str, os.PathLike)): img = os.fspath(img) if img in imagenames: return imagenames.index(img) norm = os.path.normpath(os.path.abspath(img)) for k, name in enumerate(imagenames): if os.path.normpath(os.path.abspath(name)) == norm: return k elif img is None and len(imagenames) == 1: return 0 # positions without a cube, single cube given num = coord.imagenumber if num is not None and 0 <= num < len(imagenames): return int(num) if num is None or num < 0: raise ValueError('The cube {0!r} of coordinate {1!r} is not in imagenames {2}'.format( img, coord, imagenames if len(imagenames) <= 5 else imagenames[:5] + ['...'])) raise ValueError('Cannot tell which image coordinate {0!r} belongs to: its image {1!r} is not ' 'in imagenames and its imagenumber ({2}) is out of range'.format(coord, img, num)) def _to_skycoord(coords): """SkyCoord array (in the frame of the first coordinate) from physical Coords given as astropy angles or radians; coordinates in other frames are converted.""" from astropy.coordinates import SkyCoord import astropy.units as u def val(a): return a if hasattr(a, 'unit') else a * u.rad frames = [_equatorial(c.frame or 'icrs') for c in coords] target = frames[0] ra = u.Quantity([val(c.ra) for c in coords]) dec = u.Quantity([val(c.dec) for c in coords]) if all(f == target for f in frames): return SkyCoord(ra=ra, dec=dec, frame=target) out_ra, out_dec = ra.to(u.deg).copy(), dec.to(u.deg).copy() for f in set(frames) - {target}: sel = np.array([g == f for g in frames]) conv = SkyCoord(ra=ra[sel], dec=dec[sel], frame=f).transform_to(target) out_ra[sel], out_dec[sel] = conv.ra.to(u.deg), conv.dec.to(u.deg) return SkyCoord(ra=out_ra, dec=out_dec, frame=target)
[docs] def getPixelCoords(coords, imagenames=None, hdul='auto'): """ Creates pixel coordinate list from a physical coordinate list and a list of images. Parameters --------- coords A list of LineStacker.Coord coordinates. imagenames A list of images' paths (FITS files or CASA images). Optional when every coordinate names its cube (readCatalog, makeCoords). hdul index of the FITS HDU holding the cube; 'auto' (default) uses the first HDU containing an image (HDU 0 for ALMA/CASA FITS, 1 for MUSE). Returns ------- list of LineStacker.Coord new coordinates of type 'pixel'; the original coordinates are not modified. Each new coordinate's ``index`` is the position of the original in ``coords``. """ from LineStacker import _io imagenames = _cube_list(coords, imagenames) pixcoords = [None] * len(coords) groups = {} for n, coord in enumerate(coords): k = _image_index(coord, imagenames) if coord.type == 'pixel': new = coord.copy() new.image, new.imagenumber, new.index = imagenames[k], k, n pixcoords[n] = new else: groups.setdefault(k, []).append(n) for k, members in groups.items(): info = _io.read_info(imagenames[k], hdul) sky = _to_skycoord([coords[n] for n in members]) xs, ys = info.world_to_pixel(sky) for n, x, y in zip(members, np.atleast_1d(xs), np.atleast_1d(ys)): old = coords[n] new = old.copy() new.ra, new.dec = float(x), float(y) new.type, new.image, new.imagenumber, new.index = 'pixel', imagenames[k], k, n pixcoords[n] = new return pixcoords
[docs] def randomCoords(imagenames, ncoords=10, hdul='auto', margin=0, rng=None): """ Random positions anywhere in a set of images: pixel coordinates whose spec is a random channel of their cube, to be stacked with spectralMethod='channel'. Parameters --------- imagenames A list of images paths (or one path). ncoords Number of random coordinates. Default is 10. margin Minimal distance (pixels) to the image edges, e.g. half the stampsize. rng numpy Generator or seed, for reproducible draws. """ from LineStacker import _io if isinstance(imagenames, (str, os.PathLike)): imagenames = [imagenames] imagenames = [os.fspath(n) for n in imagenames] if not imagenames: raise ValueError('randomCoords needs at least one image') if isinstance(ncoords, bool) or int(ncoords) != ncoords or ncoords < 0: raise ValueError('ncoords must be an integer >= 0 (got {0!r})'.format(ncoords)) ncoords = int(ncoords) if margin < 0: raise ValueError('margin must be >= 0 (got {0})'.format(margin)) rng = np.random.default_rng(rng) infos = [_io.read_info(name, hdul) for name in imagenames] for name, inf in zip(imagenames, infos): if 2 * margin > min(inf.nx, inf.ny) - 1: raise ValueError('margin {0} leaves no room in {1} ({2}x{3} pixels): it must be at most {4}'.format( margin, name, inf.nx, inf.ny, (min(inf.nx, inf.ny) - 1) / 2.)) out = [] for _ in range(ncoords): k = int(rng.integers(len(imagenames))) inf = infos[k] x = rng.uniform(margin, inf.nx - 1 - margin) y = rng.uniform(margin, inf.ny - 1 - margin) chan = int(rng.integers(inf.nchan)) out.append(Coord(x, y, spec=chan, image=imagenames[k], imagenumber=k, type='pixel')) return out
def _image_list(imagenames): """imagenames as a list of paths (one path is a list of one).""" if imagenames is None: return None if isinstance(imagenames, (str, os.PathLike)): return [os.fspath(imagenames)] return [os.fspath(n) for n in imagenames]
[docs] def randomizeCoords(coords, beam, maxBeamRange=5, imagenames=None, hdul='auto', rng=None, maxTries=100): """ New positions at a random distance between beam and maxBeamRange*beam from each of the original coordinates (random direction). See also LineStacker.analysisTools.randomizeCoords, which takes the limits in radians. Parameters --------- coords list of original coordinates (LineStacker.Coord instances) beam beam size in radians, new random coordinates will be at a minimum distance beam from the original coordinates. maxBeamRange maximum distance from original coordinates at which new coordinates can be located, in units of beams. Default is 5. imagenames images the coordinates refer to; when given, new positions are kept inside their image. rng numpy Generator or seed, for reproducible draws. """ from LineStacker import _io imagenames = _image_list(imagenames) if not np.isfinite(beam) or beam <= 0: raise ValueError('beam must be > 0 (radians), got {0}'.format(beam)) if not (np.isfinite(maxBeamRange) and maxBeamRange >= 1): raise ValueError('maxBeamRange must be finite and >= 1 (in beams), got {0}'.format(maxBeamRange)) if isinstance(maxTries, bool) or int(maxTries) != maxTries or maxTries < 1: raise ValueError('maxTries must be an integer >= 1 (got {0!r})'.format(maxTries)) maxTries = int(maxTries) rng = np.random.default_rng(rng) out = [] for coord in coords: info = None if imagenames is not None: info = _io.read_info(imagenames[_image_index(coord, imagenames)], hdul) for _ in range(maxTries): sep = rng.uniform(beam, maxBeamRange * beam) pa = rng.uniform(0, 2 * np.pi) new = coord.copy() if coord.type == 'pixel': if info is None: raise ValueError('imagenames is needed to randomize pixel coordinates') step = sep / np.deg2rad(info.pixscale_deg) new.ra = coord.ra + step * np.cos(pa) new.dec = coord.dec + step * np.sin(pa) px, py = new.ra, new.dec else: import astropy.units as u sky = _to_skycoord([coord])[0].directional_offset_by(pa * u.rad, sep * u.rad) new.ra, new.dec = sky.ra, sky.dec px, py = info.world_to_pixel(sky) if info is not None else (0, 0) if info is None or (0 <= px <= info.nx - 1 and 0 <= py <= info.ny - 1): out.append(new) break else: raise Exception('Cannot find random position, change search region') return out