Source code for libvhc.utils

# Virus Health Check: a validation tool for HETDEX/VIRUS data
# Copyright (C) 2015, 2016, 2017, 2018  "The HETDEX collaboration"
#
# 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 3 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, see <https://www.gnu.org/licenses/>.
"""Collection of utility variables and functions
"""
from __future__ import (absolute_import, division, print_function,
                        unicode_literals)

import argparse as ap
import re

from pyhetdex.het.fplane import FPlane

import libvhc.config as vhcconf
from . import __version__

_fplane = []

generic_virus_match = "*virus/[0-9]*[a-z].fits"
"""Wildcard match for virus file"""

recipe_match = {}
"""Map between recipe name and the corresponding fits file names.
Filled when loading the recipes"""

default_drivers = {}
"""Default drivers for every recipe. Filled when loading the recipes"""


EXTRA_KEY = 'VHCVERS'
'''When the VHC header keywords are saved in FITS files add one with the
version of VHC used'''
EXTRA_VALUE = __version__
'''Version of VHC used'''
EXTRA_COMMENT = 'Latest VHC version used'
'''Comment attached to the header keyword'''


###########################
# generic utilities

def extra_value_with_conf_revision(conf):
    '''If the ``write_vhc_config_revision`` option of the ``[headerkeys]``
    configuration section is set to ``yes``/``true``, the revision number is
    extracted from the import configuration and added to :data:`EXTRA_VALUE`.

    Parameters
    ----------
    conf : instance of :class:`configparser.ConfigParser`
        configuration object

    Returns
    -------
    _extra_value : string
        extended version number
    '''
    _extra_value = EXTRA_VALUE
    if conf.getboolean('headerkeys', 'write_vhc_config_revision'):
        rev = vhcconf.conf_svn_info(conf)['revision']
        _extra_value = EXTRA_VALUE + '. cfg: ' + rev

    return _extra_value


###########################
# Functions to get ids, channel and amplifier

def get_fplane():
    '''Returns, creating it first if necessary, an instance of
    :class:`~pyhetdex.het.fplane.FPlane`. The name of the fplane file is take
    from the configuration file section ``[fplane]`` and option
    ``fplane_file``.

    Returns
    -------
    :class:`~pyhetdex.het.fplane.FPlane`
    '''
    try:
        return _fplane[0]
    except IndexError:
        _conf = vhcconf.get_config()
        fplane_file = _conf['fplane']['fplane_file']
        skip_ifuslot = _conf.get_list('fplane', 'skip_ifuslot',
                                      use_default=True)
        fplane = FPlane(fplane_file, exclude_ifuslot=skip_ifuslot)
        _fplane.append(fplane)
        return fplane


def channel(fname, section='DEFAULT'):
    '''Extract the channel from the file name using regular expression
    matching.

    The regex comes from the ``re_pattern_ch`` configuration entry.

    Parameters
    ----------
    fname : string
        name of the from which to extract the channel
    section : string, optional
        name of the section containing the match.

    Returns
    -------
    string
        name of the channel
    '''
    re_pattern = vhcconf.get_config()[section]['re_pattern_ch']
    return re.findall(re_pattern, fname)[0]


def amplifier(fname, section='DEFAULT'):
    '''Extract the amplifier from the file name using regular expression
    matching.

    The regex comes from the ``re_pattern_amp`` configuration entry.

    Parameters
    ----------
    fname : string
        name of the from which to extract the channel
    section : string, optional
        name of the section containing the match.

    Returns
    -------
    string
        name of the amplifier
    '''
    re_pattern = vhcconf.get_config()[section]['re_pattern_amp']
    return re.findall(re_pattern, fname)[0]


def ifuslot(fname, section='DEFAULT'):
    '''Extract the slot id from the file name using regular expression
    matching.

    The regex comes from the ``re_pattern_id`` configuration entry.

    Parameters
    ----------
    fname : string
        name of the from which to extract the channel
    section : string, optional
        name of the section containing the match.

    Returns
    -------
    string
        slotid
    '''
    re_pattern = vhcconf.get_config()[section]['re_pattern_id']
    return re.findall(re_pattern, fname)[0]


def specid(id_, idtype='ifuslot'):
    '''Get the specid corresponding to the input id

    Parameters
    ----------
    id_ : string
        input ID
    idtype : string, optional
        type of id accepted by :class:`~pyhetdex.het.fplane.FPlane`

    Returns
    -------
    string
        spec id in a zero-padded three digit format
    '''
    return '{0:03d}'.format(get_fplane().by_id(id_, idtype).specid)


def ifuid(id_, idtype='ifuslot'):
    '''Get the ifuid corresponding to the input id.

    Parameters
    ----------
    id_ : string
        input ID
    idtype : string, optional
        type of id accepted by :class:`~pyhetdex.het.fplane.FPlane`

    Returns
    -------
    string
        ifu id
    '''
    return get_fplane().by_id(id_, idtype).ifuid


###########################
# common command line parse arguments
def common_parser_arguments():
    '''Return a command line parser without help nor description. Useful for
    as parent parser.

    Returns
    -------
    parser : :class:`argparse.ArgumentParser`
    '''
    from . import __version__
    parser = ap.ArgumentParser(add_help=False)
    parser.add_argument('-V', '--version', action='version',
                        version=__version__)

    return parser