Coverage for sherlock/catalogue

Hot-keys on this page

r m x p toggle line displays

j k next/prev highlighted chunk

0 (zero) top of page

1 (one) first highlighted chunk

1#!/usr/local/bin/python

2# encoding: utf-8

3"""

4*perform a conesearch on a **single** sherlock crossmatch catalogue table*

6:Author:

7 David Young

9:noindex:

10"""

11from builtins import zip

12from builtins import object

13import sys

14import os

15os.environ['TERM'] = 'vt100'

16from fundamentals import tools

17from astrocalc.coords import unit_conversion

18from HMpTy.mysql import conesearch as hmptyConesearch

19import copy

22class catalogue_conesearch(object):

23 """

24 *The worker class for the conesearch module*

26 **Key Arguments**

28 - ``dbConn`` -- mysql database connection to the catalogues database

29 - ``log`` -- logger

30 - ``ra`` -- ra of transient location (sexegesimal or decimal degrees, J2000, single location or list of locations)

31 - ``dec`` -- dec of transient location (sexegesimal or decimal degrees, J2000, single location or list of locations)

32 - ``tableName`` -- the name of the database table to perform the conesearch on

33 - ``radius`` -- radius of the conesearch to perform (arcsec)

34 - ``colMaps`` -- maps of the important column names for each table/view in the crossmatch-catalogues database

35 - ``nearestOnly`` -- return only the nearest object. Default *False*

36 - ``physicalSearch`` -- is this a physical search, so only return matches with distance information. Default *False*

37 - ``upperMagnitudeLimit`` -- the upper magnitude limit if a magnitude cut is requird with the conesearch. Default *False*

40 - ``lowerMagnitudeLimit`` -- the lower magnitude limit if a magnitude cut is requird with the conesearch. Default *False*

41 - ``magnitudeLimitFilter`` -- the filter to use for the magnitude limit if requird. Default *False*, ("_u"|"_g"|"_r"|"_i"|"_z"|"_y"|"U"|"B"|"V"|"R"|"I"|"Z"|"J"|"H"|"K"|"G")

43 **Usage**

45 To setup your logger, settings and database connections, please use the ``fundamentals`` package (`see tutorial here <http://fundamentals.readthedocs.io/en/latest/#tutorial>`_).

47 .. todo::

49 - update the package tutorial if needed

51 The following examples assume you've connected to the various databases and generated the catalogue column maps in the following menner:

53 ```python

54 # SETUP ALL DATABASE CONNECTIONS

55 from sherlock import database

56 db = database(

57 log=log,

58 settings=settings

59 )

60 dbConns, dbVersions = db.connect()

61 transientsDbConn = dbConns["transients"]

62 cataloguesDbConn = dbConns["catalogues"]

64 # GET THE COLUMN MAPS FROM THE CATALOGUE DATABASE

65 from sherlock.commonutils import get_crossmatch_catalogues_column_map

66 colMaps = get_crossmatch_catalogues_column_map(

67 log=log,

68 dbConn=cataloguesDbConn

69 )

70 ```

72 To perform a single location conesearch on a catalogue in the database, for example the milliquas AGN catalogue:

74 ```python

75 from sherlock import catalogue_conesearch

76 cs = catalogue_conesearch(

77 log=log,

78 ra="23:01:07.99",

79 dec="-01:58:04.5",

80 radiusArcsec=60.,

81 colMaps=colMaps,

82 tableName="tcs_view_agn_milliquas_v4_5",

83 dbConn=cataloguesDbConn,

84 nearestOnly=False,

85 physicalSearch=False

86 )

87 # catalogueMatches ARE ORDERED BY ANGULAR SEPARATION

88 indices, catalogueMatches = cs.search()

90 print(catalogueMatches)

91 ```

93 The output of this search is:

95 ```text

96 [{'R': 20.1, 'cmSepArcsec': 0.28015184686564643, 'ra': 345.2832267, 'catalogue_object_subtype': u'QR', 'z': 0.777, 'dec': -1.9679629, 'catalogue_object_id': u'PKS 2258-022'}]

97 ```

99 Note ``catalogue_conesearch`` can accept coordinates in sexegesimal or decimal degrees (J200). It can also accept lists of corrdinates:

100

101 ```python

102 from sherlock import catalogue_conesearch

103 cs = catalogue_conesearch(

104 log=log,

105 ra=["23:01:07.99", 45.36722, 13.875250],

106 dec=["-01:58:04.5", 30.45671, -25.26721],

107 radiusArcsec=60.,

108

109

110 colMaps=colMaps,

111 tableName="tcs_view_agn_milliquas_v4_5",

112 dbConn=cataloguesDbConn,

113 nearestOnly=False,

114 physicalSearch=False

115 )

116 ```

117

118 When passing a list of transient coordinates the returned ``indices`` value becomes important as this list identifies which transient is matched with which crossmatch results (and possibly multiple crossmatch results)

119

120 ```python

121 indices, catalogueMatches = cs.search()

122 for i, c in zip(indices, catalogueMatches):

123 print(i, c)

124 ```

125

126 The output of this search is:

127

128 ```text

129 0 {'R': 20.1, 'cmSepArcsec': 0.28015184686564643, 'ra': 345.2832267, 'catalogue_object_subtype': u'QR', 'z': 0.777, 'dec': -1.9679629, 'catalogue_object_id': u'PKS 2258-022'}

130 2 {'R': 19.2, 'cmSepArcsec': 0.81509715903447644, 'ra': 13.875, 'catalogue_object_subtype': u'Q', 'z': 2.7, 'dec': -25.2672223, 'catalogue_object_id': u'Q 0053-2532'}

131 ```

132

133 .. todo ::

134

135 - update key arguments values and definitions with defaults

136 - update return values and definitions

137 - update usage examples and text

138 - update docstring text

139 - check sublime snippet exists

140 - clip any useful text to docs mindmap

141 - regenerate the docs and check redendering of this docstring

142 """