docs: def angular_crossmatch_against_catalogue(
          self,
          objectList,
          searchPara={},
          search_name="",
          brightnessFilter=False,
          physicalSearch=False,
          classificationType=False
      ):
          """*perform an angular separation crossmatch against a given catalogue in the database and annotate the crossmatch with some value added parameters (distances, physical separations, sub-type of transient etc)*
  
          **Key Arguments:**
              - ``objectList`` -- the list of transient locations to match against the crossmatch catalogue
              - ``searchPara`` -- the search parameters for this individual search as lifted from the search algorithm in the sherlock settings file
              - ``search_name`` -- the name of the search as given in the sherlock settings file
              - ``brightnessFilter`` -- is this search to be constrained by magnitude of the catalogue sources? Default *False*. [bright|faint|general]
              - ``physicalSearch`` -- is this angular search a sub-part of a physical separation search
              - ``classificationType`` -- synonym, association or annotation. Default *False*
  
           **Return:**
              - matchedObjects -- any sources matched against the object
  
          **Usage:**
  
              Take a list of transients from somewhere
  
              .. code-block:: python 
  
  
                  transients = [
                      {'ps1_designation': u'PS1-14aef',
                       'name': u'4L3Piiq',
                       'detection_list_id': 2,
                       'local_comments': u'',
                       'ra': 0.02548233704918263,
                       'followup_id': 2065412L,
                       'dec': -4.284933417540423,
                       'id': 1000006110041705700L,
                       'object_classification': 0L
                       },
  
                      {'ps1_designation': u'PS1-13dcr',
                       'name': u'3I3Phzx',
                       'detection_list_id': 2,
                       'local_comments': u'',
                       'ra': 4.754236999477372,
                       'followup_id': 1140386L,
                       'dec': 28.276703631398625,
                       'id': 1001901011281636100L,
                       'object_classification': 0L
                       },
  
                      {'ps1_designation': u'PS1-13dhc',
                       'name': u'3I3Pixd',
                       'detection_list_id': 2,
                       'local_comments': u'',
                       'ra': 1.3324973428505413,
                       'followup_id': 1202386L,
                       'dec': 32.98869220595689,
                       'id': 1000519791325919200L,
                       'object_classification': 0L
                       }
                  ]
  
              Then run the ``angular_crossmatch_against_catalogue`` method to crossmatch against the catalogues and return results:
  
              .. code-block:: python 
  
                  # ANGULAR CONESEARCH ON CATALOGUE
                  search_name = "ned_d spec sn"
                  searchPara = self.settings["search algorithm"][search_name]
                  matchedObjects = xmatcher.angular_crossmatch_against_catalogue(
                      objectList=transients,
                      searchPara=searchPara,
                      search_name=search_name
                  )
  
          .. todo ::
  
              - update key arguments values and definitions with defaults
              - update return values and definitions
              - update usage examples and text
              - update docstring text
              - check sublime snippet exists
              - clip any useful text to docs mindmap
              - regenerate the docs and check redendering of this docstring
          """
          self.log.debug(
              'starting the ``angular_crossmatch_against_catalogue`` method')
  
          self.log.info("STARTING %s SEARCH" %
                        (search_name,))
  
          start_time = time.time()
  
          # DEFAULTS
  
          # print search_name, classificationType
  
          magnitudeLimitFilter = None
          upperMagnitudeLimit = False
          lowerMagnitudeLimit = False
  
          catalogueName = searchPara["database table"]
  
          if not "mag column" in searchPara:
              searchPara["mag column"] = None
  
          if brightnessFilter:
              if "mag column" in searchPara and searchPara["mag column"]:
                  magnitudeLimitFilter = self.colMaps[
                      catalogueName][searchPara["mag column"] + "ColName"]
              theseSearchPara = searchPara[brightnessFilter]
          else:
              theseSearchPara = searchPara
  
          # EXTRACT PARAMETERS FROM ARGUMENTS & SETTINGS FILE
          if classificationType == "synonym":
              radius = self.settings["synonym radius arcsec"]
              matchedType = theseSearchPara["synonym"]
          elif classificationType == "association":
              radius = theseSearchPara["angular radius arcsec"]
              matchedType = theseSearchPara["association"]
          elif classificationType == "annotation":
              radius = theseSearchPara["angular radius arcsec"]
              matchedType = theseSearchPara["annotation"]
  
          if brightnessFilter == "faint":
              upperMagnitudeLimit = theseSearchPara["mag limit"]
          elif brightnessFilter == "bright":
              lowerMagnitudeLimit = theseSearchPara["mag limit"]
          elif brightnessFilter == "general":
              if "faint" in searchPara:
                  lowerMagnitudeLimit = searchPara["faint"]["mag limit"]
              if "bright" in searchPara:
                  upperMagnitudeLimit = searchPara["bright"]["mag limit"]
  
          # VARIABLES
          matchedObjects = []
          matchSubset = []
  
          transRAs = []
          transRAs[:] = [t['ra'] for t in objectList]
          transDecs = []
          transDecs[:] = [t['dec'] for t in objectList]
  
          if len(transRAs) == 0:
              return []
  
          cs = catalogue_conesearch(
              log=self.log,
              ra=transRAs,
              dec=transDecs,
              radiusArcsec=radius,
              colMaps=self.colMaps,
              tableName=catalogueName,
              dbConn=self.dbConn,
              nearestOnly=False,
              physicalSearch=physicalSearch,
              upperMagnitudeLimit=upperMagnitudeLimit,
              lowerMagnitudeLimit=lowerMagnitudeLimit,
              magnitudeLimitFilter=magnitudeLimitFilter
          )
  
          # catalogueMatches ARE ORDERED BY ANGULAR SEPARATION
          indices, catalogueMatches = cs.search()
          count = 1
          annotatedcatalogueMatches = []
  
          for i, xm in zip(indices, catalogueMatches):
  
              # CALCULATE PHYSICAL PARAMETERS ... IF WE CAN
              if "cmSepArcsec" in xm:
                  xm["separationArcsec"] = xm["cmSepArcsec"]
                  # CALCULATE SEPARATION IN ARCSEC
  
                  calculator = separations(
                      log=self.log,
                      ra1=objectList[i]["ra"],
                      dec1=objectList[i]["dec"],
                      ra2=xm["ra"],
                      dec2=xm["dec"]
                  )
                  angularSeparation, north, east = calculator.get()
  
                  xm["northSeparationArcsec"] = north
                  xm["eastSeparationArcsec"] = east
                  del xm["cmSepArcsec"]
  
              xm["association_type"] = matchedType
              xm["catalogue_view_name"] = catalogueName
              xm["transient_object_id"] = objectList[i]["id"]
              xm["catalogue_table_name"] = self.colMaps[
                  catalogueName]["description"]
              xm["catalogue_table_id"] = self.colMaps[
                  catalogueName]["table_id"]
              xm["catalogue_view_id"] = self.colMaps[
                  catalogueName]["id"]
              if classificationType == "synonym":
                  xm["classificationReliability"] = 1
              elif classificationType == "association":
                  xm["classificationReliability"] = 2
              elif classificationType == "annotation":
                  xm["classificationReliability"] = 3
  
              xm = self._annotate_crossmatch_with_value_added_parameters(
                  crossmatchDict=xm,
                  catalogueName=catalogueName,
                  searchPara=theseSearchPara,
                  search_name=search_name
              )
              annotatedcatalogueMatches.append(xm)
  
          catalogueMatches = annotatedcatalogueMatches
  
          # IF BRIGHT STAR SEARCH
          if brightnessFilter == "bright" and "star" in search_name:
              catalogueMatches = self._bright_star_match(
                  matchedObjects=catalogueMatches,
                  catalogueName=catalogueName,
                  lowerMagnitudeLimit=lowerMagnitudeLimit,
                  magnitudeLimitFilter=searchPara["mag column"]
              )
  
          if brightnessFilter == "general" and "galaxy" in search_name and "galaxy-like" not in search_name and "physical radius kpc" not in theseSearchPara:
              catalogueMatches = self._galaxy_association_cuts(
                  matchedObjects=catalogueMatches,
                  catalogueName=catalogueName,
                  lowerMagnitudeLimit=lowerMagnitudeLimit,
                  upperMagnitudeLimit=upperMagnitudeLimit,
                  magnitudeLimitFilter=searchPara["mag column"]
              )
  
          if "match nearest source only" in theseSearchPara and theseSearchPara["match nearest source only"] == True and len(catalogueMatches):
              nearestMatches = []
              transList = []
              for c in catalogueMatches:
                  if c["transient_object_id"] not in transList:
                      transList.append(c["transient_object_id"])
                      nearestMatches.append(c)
              catalogueMatches = nearestMatches
  
          self.log.debug(
              'completed the ``angular_crossmatch_against_catalogue`` method')
  
          self.log.debug("FINISHED %s SEARCH IN %0.5f s" %
                         (search_name, time.time() - start_time,))
  
          return catalogueMatches