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')