Main interface

The ongc module is the main interface for retrieving objects data through Python objects. It also provides some tools to query the database through several parameters.

Public Classes

class pyongc.ongc.Dso(name: str, returndup: bool = False)

Describes a Deep Sky Object from ONGC database.

Each object of this class has the following read only properties:

cstar_data: The data about central star of planetary nebulaes.
constellation: The constellation where the object is located.
coords: Object coordinates in HMS and DMS as numpy array or None.
dec: Object Declination in a easy to read format as string.
dimensions: Object axes dimensions and position angle.
hubble: The Hubble classification of a galaxy.
id: The internal database Id of the object.
identifiers: All the alternative identifiers of the object.
magnitudes: Object magnitudes.
name: The main identifier of the object.
notes: Notes from NED and from ONGC.
notngc: A flag which marks objects not being in the NGC or IC catalog
parallax: Parallax, expressed in milliarcseconds.
pm_dec: Proper apparent motion in Dec, expressed in milliarcseconds/year.
pm_ra: Proper apparent motion in RA, expressed in milliarcseconds/year.
ra: Object Right Ascension in a easy to read format as string.
rad_coords: Object coordinates in radians as numpy array or None.
radvel: Radial velocity (heliocentric), expressed in km/s.
redshift: Redshift value (heliocentric).
surface_brightness: The surface brightness value of a galaxy or None.
type: Object type.

The class also provides the following methods:

__init__: Object constructor.
__str__: Returns a basic description of the object.
xephemFormat: Returns object data in Xephem format.

__init__(name: str, returndup: bool = False)

Object constructor.

Parameters:

name – Object identifier (ex.: ‘NGC1’, ‘M15’).
returndup – If set to True, don’t resolve Dup objects. Default is False.

Raises:

TypeError – If the object identifier is not a string.
pyongc.ObjectNotFound – If the object identifier is not found in the database.

__str__() → str

Returns a basic description of the object.

>>> from pyongc.ongc import Dso
>>> s = Dso("ngc1")
>>> print(s)
NGC0001, Galaxy in Peg

property constellation: str

The constellation where the object is located.

>>> from pyongc.ongc import Dso
>>> s = Dso("ngc1")
>>> s.constellation
'Peg'

Returns:: Name of the constellation in IAU 3-letter form.

property coords: ndarray | None

Returns object coordinates in HMS and DMS as numpy array or None.

>>> from pyongc.ongc import Dso
>>> s = Dso("ngc1")
>>> s.coords
array([[ 0.  ,  7.  , 15.84],
       [27.  , 42.  , 29.1 ]])

Returns:: A numpy array of shape (2, 3) with R.A. and Declination values expressed in HMS and DMS.

Data about central star of planetary nebulaes.

If the DSO object is a Planetary Nebulae, this method will return a tuple with the central star identifiers and its magnitudes in U-B-V bands:

>>> from pyongc.ongc import Dso
>>> s = Dso("ngc1535")
>>> s.cstar_data
(['BD -13 842', 'HD 26847'], None, 12.19, 12.18)

If the object is not a PN it returns None:

>>> from pyongc.ongc import Dso
>>> s = Dso("ngc1")
>>> s.cstar_data is None
True

Returns:: ([‘cstar identifiers’], cstar UMag, cstar BMag, cstar VMag)

property dec: str

Object Declination in a easy to read format as string.

If you need the raw data to use in calculations use coords or rad_coords properties.

>>> from pyongc.ongc import Dso
>>> s = Dso("ngc1")
>>> s.dec
'+27:42:29.1'

>>> from pyongc.ongc import Dso
>>> s = Dso("ic1064")
>>> s.dec
'N/A'

Returns:: ‘+/-DD:MM:SS.s’ or ‘N/A’ if the object has no coordinates.
Return type:: string

property dimensions: Tuple[float | None, float | None, int | None]

Object axes dimensions and position angle.

Where a value is not available a None type is returned.

>>> from pyongc.ongc import Dso
>>> s = Dso("ngc1")
>>> s.dimensions
(1.57, 1.07, 112)

Returns:: (MajAx, MinAx, P.A.)

property hubble: str

The Hubble classification of a galaxy.

>>> from pyongc.ongc import Dso
>>> s = Dso("ngc1")
>>> s.hubble
'Sb'

Returns:: The Hubble classification code of a galaxy or empty string.
Return type:: string

property id: int

The internal database Id of the object.

Returns:

The internal database id of the object.

>>> from pyongc.ongc import Dso
>>> s = Dso("ngc1")
>>> s.id
5596

All the alternative identifiers of the object.

The tuple returned by this method will list all the alternative identifiers associated to the object. The first element of the tuple will be a string with the Messier name or None. The other fields will be lists of cross identifiers or None.

>>> from pyongc.ongc import Dso
>>> s = Dso("ngc1976")
>>> s.identifiers
('M042', None, None, ['Great Orion Nebula', 'Orion Nebula'], ['LBN 974', 'MWSC 0582'])

>>> from pyongc.ongc import Dso
>>> s = Dso("mel22")
>>> s.identifiers
('M045', None, None, ['Pleiades'], ['MWSC 0305'])

Returns:: (‘Messier’, [‘NGC’], [‘IC’], [‘common names’], [‘other’])

Returns object magnitudes.

Where a value is not available a None type is returned

>>> from pyongc.ongc import Dso
>>> s = Dso("ngc1")
>>> s.magnitudes
(13.69, 12.93, 10.78, 10.02, 9.76)

Returns:: (Bmag, Vmag, Jmag, Hmag, Kmag)

property name: str

The main identifier of the object.

>>> from pyongc.ongc import Dso
>>> s = Dso("m45")
>>> s.name
'Mel022'

Returns:: The main identifier of the object, as listed in ONGC database or its addendum.

property notes: Tuple[str, str]

Returns notes from NED and from ONGC.

>>> from pyongc.ongc import Dso
>>> s = Dso("ngc6543")
>>> s.notes
('Additional radio sources may contribute to the WMAP flux.', 'The fainter outer shell has a diameter of 5.5 arcmin ca.')

Returns:: (‘nednotes’, ‘ongcnotes’)

property notngc: bool

A flag which marks objects not being in the NGC or IC catalog.

The OpenNGC database also includes objects which aren’t part of the NGC or IC catalog. For example, objects from the ‘addendum’ are objects which can interest amateur astronomers, thus we’re including in our listings. The notngc property is a convenient flag to mark these extra objects.

>>> from pyongc.ongc import Dso
>>> s = Dso("m45")
>>> s.notngc
True

property parallax: float | None

Object’s parallax.

>>> from pyongc.ongc import Dso
>>> s = Dso("m13")
>>> s.parallax
0.0813

Returns:: Object’s parallax expressed in milliarcseconds or None.

property pm_dec: float | None

Proper apparent motion in Dec, expressed in milliarcseconds/year.

>>> from pyongc.ongc import Dso
>>> s = Dso("m13")
>>> s.pm_dec
-2.56

Returns:: Object’s apparent motion in Dec or None.

property pm_ra: float | None

Proper apparent motion in RA, expressed in milliarcseconds/year.

>>> from pyongc.ongc import Dso
>>> s = Dso("m13")
>>> s.pm_ra
-3.18

Returns:: Object’s apparent motion in RA or None.

property ra: str

Object Right Ascension in a easy to read format as string.

If you need the raw data to use in calculations use coords or rad_coords properties.

>>> from pyongc.ongc import Dso
>>> s = Dso("ngc1")
>>> s.ra
'00:07:15.84'

>>> from pyongc.ongc import Dso
>>> s = Dso("ic1064")
>>> s.ra
'N/A'

Returns:: ‘HH:MM:SS.ss’ or ‘N/A’ if the object has no coordinates.
Return type:: string

property rad_coords: ndarray | None

Returns object coordinates in radians as numpy array or None.

>>> from pyongc.ongc import Dso
>>> s = Dso("ngc1")
>>> s.rad_coords
array([0.03169518, 0.48359728])

Returns:: A numpy array of shape (2,) with R.A. and Declination values expressed in radians.

property radvel: float | None

Object’s radial velocity.

>>> from pyongc.ongc import Dso
>>> s = Dso("m13")
>>> s.radvel
-244

Returns:: Object’s radial velocity (heliocentric) expressed in km/s or None.

property redshift: float | None

Object’s redshift value.

>>> from pyongc.ongc import Dso
>>> s = Dso("m13")
>>> s.redshift
-0.000815

Returns:: Object’s redshift value or None.

property surface_brightness: float | None

The surface brightness value of a galaxy.

>>> from pyongc.ongc import Dso
>>> s = Dso("ngc1")
>>> s.surface_brightness
23.13

Returns:: Object’s surface brightness
Return type:: float

to_json() → str: Returns object data in JSON format.

property type: str

Object type.

>>> from pyongc.ongc import Dso
>>> s = Dso("ngc1")
>>> s.type
'Galaxy'

Returns:: Object type
Return type:: string

xephemFormat() → str

Returns object data in Xephem format.

This function will produce a string containing information about the object suitable to be imported in other software that accept Xephem format (for example: PyEphem).

>>> from pyongc.ongc import Dso
>>> s = Dso("ngc1")
>>> s.xephemFormat()
'NGC0001,f|G,00:07:15.84,+27:42:29.1,13.69,,94.20|64.20|112'

Returns:: Xephem format object description

class pyongc.ongc.DsoEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

A custom json.dumps serializer for Dso class.

default(obj: Dso) → dict

A custom json.dumps serializer for Dso class.

Parameters:: obj – the Dso object to encode.

Public Methods

pyongc.ongc.get(name: str) → Dso | None

Search and return an object from the database.

If an object name isn’t recognized, it will return None.

Parameters:: name – the name of the object
Returns:: Dso or None.

pyongc.ongc.getNeighbors(obj: Dso | str, separation: int | float, catalog: str = 'all') → List[Tuple[Dso, float]]

Find all neighbors of an object within a user selected range.

It requires an object as the starting point of the search (either a string containing the name or a Dso type) and a search radius expressed in arcmins.

The maximum allowed search radius is 600 arcmin (10 degrees).

It returns a list of of tuples with the Dso objects found in range and its distance, or an empty list if no object is found:

>>> from pyongc.ongc import Dso, getNeighbors
>>> s1 = Dso("ngc521")
>>> getNeighbors(s1, 15) 
[(<pyongc.ongc.Dso object at 0x...>, 0.13726168561780452), (<pyongc.ongc.Dso object at 0x...>, 0.24140243942744602)]

>>> from pyongc.ongc import getNeighbors
>>> getNeighbors("ngc521", 1)
[]

The optional “catalog” parameter can be used to filter the search to only NGC or IC objects:

>>> from pyongc.ongc import getNeighbors
>>> getNeighbors("ngc521", 15, catalog="NGC") 
[(<pyongc.ongc.Dso object at 0x...>, 0.24140243942744602)]

Parameters:

object – a Dso object or a string which identifies the object
separation – maximum distance from the object expressed in arcmin
catalog – filter for “NGC” or “IC” objects - default is all

Returns:

A list of tuples with each element composed by the Dso object found and its distance from the starting point, ordered by distance.

Raises:

ValueError – If the search radius exceeds 10 degrees.
InvalidCoordinates – If the starting object hasn’t got registered cordinates.

pyongc.ongc.getSeparation(obj1: Dso | str, obj2: Dso | str, style: str = 'raw') → Tuple[float, float, float] | str

Finds the apparent angular separation between two objects.

This function will compute the apparent angular separation between two objects, either identified with their names as strings or directly as Dso type.

By default it returns a tuple containing the angular separation and the differences in A.R. and Declination expressed in degrees:

>>> from pyongc.ongc import Dso, getSeparation
>>> s1 = Dso("ngc1")
>>> s2 = Dso("ngc2")
>>> getSeparation(s1, s2)
(0.03008927371519897, 0.005291666666666788, -0.02972222222221896)

>>> from pyongc.ongc import getSeparation
>>> getSeparation("ngc1", "ngc2")
(0.03008927371519897, 0.005291666666666788, -0.02972222222221896)

With the optional parameter style set to text, it returns a formatted string:

>>> from pyongc.ongc import getSeparation
>>> getSeparation("ngc1", "ngc2", style="text")
'0° 1m 48.32s'

If one of the objects is not found in the database it returns an ObjectNotFound exception:

>>> from pyongc.ongc import getSeparation
>>> getSeparation("ngc1a", "ngc2")
Traceback (most recent call last):
...
pyongc.exceptions.ObjectNotFound: Object named NGC0001A not found in the database.

Parameters:

obj1 – first Dso object or string identifier
obj2 – second Dso object or string identifier
style – use “text” to return a string with degrees, minutes and seconds

Returns:

By default the return value is a tuple with values expressed in degrees

(angular separation, difference in A.R, difference in Dec)

With the style parameter set to text we get a more readable output in the form ‘DD° MMm SS.SSs’

pyongc.ongc.listObjects(**kwargs) → List[Dso]

Query the database for DSObjects with specific parameters.

This function returns a list of all DSObjects that match user defined parameters. If no argument is passed to the function, it returns all the objects from the database:

>>> from pyongc.ongc import listObjects
>>> objectList = listObjects()
>>> len(objectList)
14033

Filters are combined with “AND” in the query; only one value for filter is allowed:

>>> from pyongc.ongc import listObjects
>>> objectList = listObjects(catalog="NGC", constellation=["Boo", ])
>>> len(objectList)
281

Duplicated objects are not resolved to main objects:

>>> from pyongc.ongc import listObjects
>>> objectList = listObjects(type=["Dup", ])
>>> print(objectList[0])
IC0011, Duplicated record in Cas

The maxSize filter will include objects with no size recorded in database:

>>> from pyongc.ongc import listObjects
>>> objectList = listObjects(maxsize=0)
>>> len(objectList)
1967

Parameters:

catalog (string, optional) – filter for catalog. [NGC|IC|M]
type (list, optional) – filter for object type. See OpenNGC types list.
constellation (list, optional) – filter for constellation (three letter latin form - e.g. “And”)
minsize (float, optional) – filter for objects with MajAx >= minSize(arcmin)
maxsize (float, optional) – filter for objects with MajAx < maxSize(arcmin) OR MajAx not available
uptobmag (float, optional) – filter for objects with B-Mag brighter than value
uptovmag (float, optional) – filter for objects with V-Mag brighter than value
minra (float, optional) – filter for objects with RA degrees greater than value
maxra (float, optional) – filter for objects with RA degrees lower than value
mindec (float, optional) – filter for objects above specified Dec degrees
maxdec (float, optional) – filter for objects below specified Dec degrees
cname (string, optional) – filter for objects with common name like input value
withname (bool, optional) – filter for objects with common names

Returns:

A list of ongc.Dso objects.

Raises:

ValueError – If a filter name other than those expected is inserted.
ValueError – If an unrecognized catalog name is entered. Only [NGC|IC|M] are permitted.

pyongc.ongc.nearby(coords_string: str, separation: float = 60, catalog: str = 'all') → List[Tuple[Dso, float]]

Search for objects around given coordinates.

Returns all objects around a point expressed by the coords parameter and within a search radius expressed by the separation parameter. Coordinates must be Right Ascension and Declination expressed as a string in the form “HH:MM:SS.ss +/-DD:MM:SS.s”.

The maximum allowed search radius is 600 arcmin (10 degrees) and default value is 60.

It returns a list of of tuples with the Dso objects found in range and its distance, or an empty list if no object is found:

>>> from pyongc.ongc import nearby
>>> nearby('11:08:44 -00:09:01.3') 
[(<pyongc.ongc.Dso object at 0x...>, 0.1799936868460791), (<pyongc.ongc.Dso object at 0x...>, 0.7398295985600021), (<pyongc.ongc.Dso object at 0x...>, 0.9810037613087355)]

The optional “catalog” parameter can be used to filter the search to only NGC or IC objects:

>>> from pyongc.ongc import nearby
>>> nearby('11:08:44 -00:09:01.3', separation=60, catalog='NGC') 
[(<pyongc.ongc.Dso object at 0x...>, 0.7398295985600021)]

Parameters:

coords – R.A. and Dec of search center
separation – search radius expressed in arcmin - default 60
catalog – filter for “NGC” or “IC” objects - default is all

Returns:

[(Dso, separation),]

A list of tuples with the Dso object found and its distance from the starting point, ordered by distance.

Raises:

ValueError – If the search radius exceeds 10 degrees.

pyongc.ongc.printDetails(dso: Dso | str) → str

Prints a detailed description of the object in a formatted output.

This function returns a string with all the available details of the object, formatted in a way to fit a 80cols display. The object can be identified by its name as a string or by a Dso type:

>>> from pyongc.ongc import printDetails
>>> print(printDetails("ngc1"))
+-----------------------------------------------------------------------------+
| Id: 5597      Name: NGC0001           Type: Galaxy                          |
| R.A.: 00:07:15.84      Dec.: +27:42:29.1      Constellation: Peg            |
+-----------------------------------------------------------------------------+
| Major axis: 1.57'      Minor axis: 1.07'      Position angle: 112°          |
| B-mag: 13.69   V-mag: 12.93   J-mag: 10.78   H-mag: 10.02   K-mag: 9.76     |
|                                                                             |
| Parallax: N/A          Radial velocity: 4536km/s      Redshift: 0.015245    |
|                                                                             |
| Proper apparent motion in RA: N/A                                           |
| Proper apparent motion in Dec: N/A                                          |
|                                                                             |
| Surface brightness: 23.13     Hubble classification: Sb                     |
+-----------------------------------------------------------------------------+
| Other identifiers:                                                          |
|    2MASX J00071582+2742291, IRAS 00047+2725, MCG +04-01-025, PGC 000564,    |
|    UGC 00057                                                                |
+-----------------------------------------------------------------------------+

If the object is not found in the database it returns an ObjectNotFound exception:

>>> from pyongc.ongc import printDetails
>>> printDetails("ngc1a")
Traceback (most recent call last):
...
pyongc.exceptions.ObjectNotFound: Object named NGC0001A not found in the database.

Parameters:: dso – a Dso object or a string identifier
Returns:: All the object data ready to be printed on a 80cols terminal output.

Private Methods

These functions are usually only useful internally.

pyongc.ongc._distance(coords1: ndarray, coords2: ndarray) → Tuple[float, float, float]

Calculate distance between two points in the sky.

With p1 = ‘01:00:00 +15:30:00’ and p2 = ‘01:30:00 +10:30:00’:

>>> import numpy as np
>>> p1 = np.array([0.26179939, 0.27052603])
>>> p2 = np.array([0.39269908, 0.18325957])
>>> _distance(p1, p2)
(8.852139937970884, 7.499999776570824, -4.999999851047216)

Parameters:

coords1 – R.A. and Dec expressed in radians of the first point as numpy array with shape(2,)
coords2 – R.A. and Dec expressed in radians of the second point as numpy array with shape(2,)

Returns:

(angular separation, difference in A.R, difference in Dec)

This function will return three float values, which are the apparent total angular separation between the two objects, the difference in Right Ascension and the difference in Declination.

All values are expressed in degrees.

pyongc.ongc._limiting_coords(coords: ndarray, radius: int) → str

Write query filters for limiting search to specific area of the sky.

This is a quick method to exclude objects farther than a specified distance from the starting point, but it’s not meant to be precise.

>>> from pyongc.ongc import Dso, _limiting_coords
>>> start = Dso('ngc1').coords
>>> _limiting_coords(start, 2)
' AND (ra <= 0.06660176425610362 OR ra >= 6.279973901355917) AND (dec BETWEEN 0.44869069854374555 AND 0.5185038686235187)'

Parameters:

coords –
R.A. and Dec of the starting point in the sky.

It can be expressed as a numpy array of H:M:S/D:M:S

array([[HH., MM., SS.ss],[DD., MM., SS.ss]])

or as numpy array of radians

array([RA, Dec])
radius – radius of the search in degrees

Returns:

Parameters to be added to query

pyongc.ongc._queryFetchOne(cols: str, tables: str, params: str) → tuple

Search one row in database.

Be sure to use a WHERE clause which is very specific, otherwise the query will return the first row that matches.

>>> from pyongc.ongc import _queryFetchOne
>>> cols = 'type'
>>> tables = 'objects'
>>> params = 'name="NGC0001"'
>>> _queryFetchOne(cols, tables, params)
('G',)

Parameters:

cols – the SELECT field of the query
tables – the FROM field of the query
params – the WHERE field of the query

Returns:

Selected row data from database

pyongc.ongc._queryFetchMany(cols: str, tables: str, params: str, order: str = '') → Generator[tuple, None, None]

Search many rows in database.

>>> from pyongc.ongc import _queryFetchMany
>>> cols = 'name'
>>> tables = 'objects'
>>> params = 'type="G"'
>>> _queryFetchMany(cols, tables, params) 
<generator object _queryFetchMany at 0x...>

Parameters:

cols – the SELECT field of the query
tables – the FROM field of the query
params – the WHERE field of the query
order – the ORDER clause of the query

Yields:

Selected row data from database

pyongc.ongc._recognize_name(text: str) → Tuple[str, str]

Recognize catalog and object id.

>>> from pyongc.ongc import _recognize_name
>>> _recognize_name('NGC1')
('NGC|IC', 'NGC0001')

Parameters:: text – the object name in input. Must be uppercase.
Returns:: (‘catalog name’, ‘object name’)
Raises:: UnknownIdentifier – If the text cannot be recognized as a valid object name.

pyongc.ongc._str_to_coords(text: str) → ndarray

Recognize coordinates as string and return them as radians.

Parameters:

text (string) – a string expressing coordinates in the form HH:MM:SS.ss +/-DD:MM:SS.s

Returns:

array([RA, Dec])

A numpy array of shape (2,) with coordinates expressed in radians.

Raises:

InvalidCoordinates – If the text cannot be recognized as valid coordinates.