Usage

Basic usage

The function read_gcvs() is the main entry point to the library. When called, it will return a generator yielding a single dictionary at a time. The dictionary fields correspond to variable star attributes such as name, location, min/max brightness, variability type etc.

The following fields are available:

constellation
A three-letter abbreviation of constellation in which the star can be found, normalized to upper case. For example OPH, CRB etc.
name
Variable star designation, such as RR LYR, V838 MON etc. The name is always normalized to upper case.
ra
Right ascension of the variable star in J2000.0 epoch, eg. '20:50:12.7'.
dec
Declination of the variable star in J2000.0 epoch, eg. '+03:39:08'.

Note

The coordinates are returned as strings compatible with the popular PyEphem astronomy package. For example, ra field can be passed directly to pyephem.hours function.

variable_type
Type of variability, for example M for Mira-like pulsating red giants. This value is literal as it appears in the GCVS, meaning that uncertain types contain : (a colon), etc.
max_magnitude
Maximum brightness of a star as a floating point number. Can be None if unspecified in GCVS.
min_magnitude
Brightness of the variable star at minimum, as a floating point number. None if unspecified in GCVS.

Note

At the moment some special characters are stripped from both maximum and minimum magnitude. For example, if GCVS denotes the minimum brightness as <16.0 (fainter than 16.0), the value of min_magnitude will be 16.0 and the fainter than information will be lost. However, if the field in GCVS represents an amplitude instead of minimum magnitude, min_magnitude field will contain a correctly calculated absolute value.

epoch
Julian Day epoch of the maximum brightness as a float. None if the star is not periodic or there is no epoch data in GCVS.
period
Variability period in days, or None if unspecified or not periodic.

PyEphem compatibility

If you have PyEphem installed, you can use the dict_to_body() function to convert star data to a Body instance more suitable for various astronomical computations. See the example below, which checks if TX Del (a Type II cepheid variable) is currently visible in Warsaw.`

"""
Check if TX Del is visible in Warsaw at the moment.
"""

import sys
import ephem

from pygcvs import read_gcvs, dict_to_body


if __name__ == '__main__':
    try:
        gcvs_file = sys.argv[1]
    except IndexError:
        print('Usage: python check_visibility.py <path to iii.dat>')
    else:
        city = ephem.city('Warsaw')
        stars = {star['name']: star for star in read_gcvs(gcvs_file)}
        body = dict_to_body(stars['TX DEL'])
        body.compute(city)
        if body.alt > 0:
            print('TX Del is visible in Warsaw right now, go observe!')
        else:
            print('TX Del is not visible in Warsaw right now. Try later.')

Using GcvsParser directly

Most of the time, the read_gcvs() function works just fine. However, it’s limited (on purpose!) to read GCVS data from a file on disk. If you have the data in some other form, you can pass it directly to the GcvsParser, provided the data source supports the iterator protocol.

For example, when using requests, the response object has a iter_lines method which, well, iterates over the lines of the response.

"""
An example of directly using the parser to read downloaded GCVS data.
"""

import requests

from pygcvs.parser import GcvsParser


if __name__ == '__main__':
    url = 'http://www.sai.msu.su/gcvs/gcvs/iii/iii.dat'
    response = requests.get(url, stream=True)
    parser = GcvsParser(response.iter_lines(decode_unicode=True))
    for star in parser:
        print(star)

Visualisations with matplotlib

You can use matplotlib to visualise various aspects of GCVS variable star data.

Maximum vs minimum magnitude

"""
Visualisation of maximum/minimum magnitude for GCVS stars.
"""

import sys

import matplotlib.pyplot as plot

from pygcvs import read_gcvs


if __name__ == '__main__':
    try:
        gcvs_file = sys.argv[1]
    except IndexError:
        print('Usage: python plot_magnitudes.py <path to iii.dat>')
    else:
        min_magnitudes = []
        max_magnitudes = []
        for star in read_gcvs(gcvs_file):
            if star['min_magnitude'] and star['max_magnitude']:
                min_magnitudes.append(star['min_magnitude'])
                max_magnitudes.append(star['max_magnitude'])
        plot.title('GCVS variable star magnitudes')
        plot.plot(min_magnitudes, max_magnitudes, 'ro')
        plot.xlabel('Min magnitude')
        plot.ylabel('Max magnitude')
        # invert axes because brightest stars have lowest magnitude value
        plot.gca().invert_xaxis()
        plot.gca().invert_yaxis()
        plot.savefig('magnitudes.png')

Brightness amplitude vs period

"""
Visualisation of brightness amplitude vs variability period.
"""

import sys

import matplotlib.pyplot as plot

from pygcvs import read_gcvs


if __name__ == '__main__':
    try:
        gcvs_file = sys.argv[1]
    except IndexError:
        print('Usage: python plot_amplitude_vs_period.py <path to iii.dat>')
    else:
        periods = []
        amplitudes = []
        for star in read_gcvs(gcvs_file):
            if star['period'] and star['min_magnitude'] and star['max_magnitude']:
                periods.append(star['period'])
                amplitudes.append(star['min_magnitude'] - star['max_magnitude'])
        plot.title('GCVS variable stars amplitudes')
        plot.semilogx(periods, amplitudes, 'ro')
        plot.xlabel('Period [days]')
        plot.ylabel('Brightness amplitude [mag]')
        plot.savefig('amplitude_vs_period.png')