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
(maybe it’s from the addendum or it has a possible identification on a NGC/IC id).
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.
>>> s = Dso("ngc1") >>> print(s) NGC0001, Galaxy in Peg
- property constellation: str
The constellation where the object is located.
>>> s = Dso("ngc1") >>> s.constellation 'Peg'
- Returns
Name of the constellation in IAU 3-letter form.
- property coords: Optional[numpy.ndarray]
Returns object coordinates in HMS and DMS as numpy array or None.
>>> 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.
- property cstar_data: Optional[Tuple[Optional[List[str]], Optional[float], Optional[float], Optional[float]]]
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:
>>> 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:
>>> 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.
>>> s = Dso("ngc1") >>> s.dec '+27:42:29.1'
>>> 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[Optional[float], Optional[float], Optional[int]]
Object axes dimensions and position angle.
Where a value is not available a None type is returned.
>>> s = Dso("ngc1") >>> s.dimensions (1.57, 1.07, 112)
- Returns
(MajAx, MinAx, P.A.)
- property hubble: str
The Hubble classification of a galaxy.
>>> 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.
>>> s = Dso("ngc1") >>> s.id 5616
- property identifiers: Tuple[Optional[str], Optional[List[str]], Optional[List[str]], Optional[List[str]], Optional[List[str]]]
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.
>>> s = Dso("ngc1976") >>> s.identifiers ('M042', None, None, ['Great Orion Nebula', 'Orion Nebula'], ['LBN 974', 'MWSC 0582'])
>>> s = Dso("mel22") >>> s.identifiers ('M045', None, None, ['Pleiades'], ['MWSC 0305'])
- Returns
(‘Messier’, [‘NGC’], [‘IC’], [‘common names’], [‘other’])
- property magnitudes: Tuple[Optional[float], Optional[float], Optional[float], Optional[float], Optional[float]]
Returns object magnitudes.
Where a value is not available a None type is returned
>>> s = Dso("ngc1") >>> s.magnitudes (13.4, None, 10.78, 10.02, 9.76)
- Returns
(Bmag, Vmag, Jmag, Hmag, Kmag)
- property name: str
The main identifier of the object.
>>> 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.
>>> s = Dso("ngc6543") >>> s.notes ('Additional radio sources may contribute to the WMAP flux.', 'Diameter measured by the author from DSS2 images. 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.
>>> s = Dso("m45") >>> s.notngc True
- property parallax: Optional[float]
Object’s parallax.
>>> s = Dso("m13") >>> s.parallax 0.0813
- Returns
Object’s parallax expressed in milliarcseconds or None.
- property pm_dec: Optional[float]
Proper apparent motion in Dec, expressed in milliarcseconds/year.
>>> s = Dso("m13") >>> s.pm_dec -2.56
- Returns
Object’s apparent motion in Dec or None.
- property pm_ra: Optional[float]
Proper apparent motion in RA, expressed in milliarcseconds/year.
>>> 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.
>>> s = Dso("ngc1") >>> s.ra '00:07:15.84'
>>> 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: Optional[numpy.ndarray]
Returns object coordinates in radians as numpy array or None.
>>> 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: Optional[float]
Object’s radial velocity.
>>> s = Dso("m13") >>> s.radvel -244
- Returns
Object’s radial velocity (heliocentric) expressed in km/s or None.
- property redshift: Optional[float]
Object’s redshift value.
>>> s = Dso("m13") >>> s.redshift -0.000815
- Returns
Object’s redshift value or None.
- property surface_brightness: Optional[float]
The surface brightness value of a galaxy.
>>> 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.
>>> 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).
>>> s = Dso("ngc1") >>> s.xephemFormat() 'NGC0001,f|G,00:07:15.84,+27:42:29.1,13.4,,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: pyongc.ongc.Dso) dict
A custom json.dumps serializer for Dso class.
- Parameters
obj – the Dso object to encode.
Public Methods
- pyongc.ongc.get(name: str) Optional[pyongc.ongc.Dso]
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: Union[pyongc.ongc.Dso, str], separation: Union[int, float], catalog: str = 'all') List[Tuple[pyongc.ongc.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:
>>> s1 = Dso("ngc521") >>> getNeighbors(s1, 15) [(<pyongc.ongc.Dso object at 0x...>, 0.13726168561780452), (<pyongc.ongc.Dso object at 0x...>, 0.24140243942744602)]
>>> getNeighbors("ngc521", 1) []
The optional “catalog” parameter can be used to filter the search to only NGC or IC objects:
>>> 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: Union[pyongc.ongc.Dso, str], obj2: Union[pyongc.ongc.Dso, str], style: str = 'raw') Union[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:
>>> s1 = Dso("ngc1") >>> s2 = Dso("ngc2") >>> getSeparation(s1, s2) (0.03008927371519897, 0.005291666666666788, -0.02972222222221896)
>>> getSeparation("ngc1", "ngc2") (0.03008927371519897, 0.005291666666666788, -0.02972222222221896)
With the optional parameter style set to text, it returns a formatted string:
>>> 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:
>>> 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[pyongc.ongc.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:
>>> objectList = listObjects() >>> len(objectList) 14011
Filters are combined with “AND” in the query; only one value for filter is allowed:
>>> objectList = listObjects(catalog="NGC", constellation=["Boo", ]) >>> len(objectList) 281
Duplicated objects are not resolved to main objects:
>>> objectList = listObjects(type=["Dup", ]) >>> print(objectList[0]) IC0011, Duplicated record in Cas
The maxSize filter will include objects with no size recorded in database:
>>> objectList = listObjects(maxsize=0) >>> len(objectList) 2008
- 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[pyongc.ongc.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:
>>> 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:
>>> 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: Union[pyongc.ongc.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:
>>> print(printDetails("ngc1")) +-----------------------------------------------------------------------------+ | Id: 5616 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.4 V-mag: N/A 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:
>>> 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: numpy.ndarray, coords2: numpy.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: numpy.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.
>>> 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.
>>> 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.
>>> 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.
>>> _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) numpy.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.