docs: def match(self):
          """
          *match the transients against the sherlock-catalogues according to the search algorithm and return matches alongside the predicted classification(s)*
  
          **Return:**
              - ``classification`` -- the crossmatch results and classifications assigned to the transients
  
          See the class docstring for usage.
  
          .. 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 ``match`` method')
  
          classifications = []
  
          # COUNT NUMBER OF TRANSIENT TO CROSSMATCH
          numberOfTransients = len(self.transients)
          count = 0
  
          # GRAB SEARCH ALGORITHM
          sa = self.settings["search algorithm"]
  
          # FOR EACH TRANSIENT SOURCE IN THE LIST ...
          allCatalogueMatches = []
          catalogueMatches = []
          nonSynonymTransients = self.transients[:]
  
          # SYNONYM SEARCHES
          # ITERATE THROUGH SEARCH ALGORITHM IN ORDER
          # PRESENTED IN THE SETTINGS FILE
          brightnessFilters = ["bright", "faint", "general"]
          for search_name, searchPara in sa.iteritems():
              for bf in brightnessFilters:
                  if bf not in searchPara:
                      continue
                  if "synonym" not in searchPara[bf] or searchPara[bf]["synonym"] == False:
                      continue
                  self.log.debug("""  searching: %(search_name)s""" % locals())
                  if "physical radius kpc" in searchPara[bf]:
                      # THE PHYSICAL SEPARATION SEARCHES
                      self.log.debug(
                          'checking physical distance crossmatches in %(search_name)s' % locals())
                      catalogueMatches = self.physical_separation_crossmatch_against_catalogue(
                          objectList=self.transients,
                          searchPara=searchPara,
                          search_name=search_name + " physical",
                          brightnessFilter=bf,
                          classificationType="synonym"
                      )
                  else:
                      # THE ANGULAR SEPARATION SEARCHES
                      self.log.debug(
                          'Crossmatching against %(search_name)s' % locals())
                      # RENAMED from searchCatalogue
                      catalogueMatches = self.angular_crossmatch_against_catalogue(
                          objectList=self.transients,
                          searchPara=searchPara,
                          search_name=search_name + " angular",
                          brightnessFilter=bf,
                          classificationType="synonym"
                      )
  
                  # ADD CLASSIFICATION AND CROSSMATCHES IF FOUND
                  if catalogueMatches:
                      allCatalogueMatches = allCatalogueMatches + catalogueMatches
  
          synonymIDs = []
          synonymIDs[:] = [xm["transient_object_id"]
                           for xm in allCatalogueMatches]
  
          nonSynonymTransients = []
          nonSynonymTransients[:] = [
              t for t in self.transients if t["id"] not in synonymIDs]
  
          # ASSOCIATION SEARCHES
          # ITERATE THROUGH SEARCH ALGORITHM IN ORDER
          # PRESENTED IN THE SETTINGS FILE
          if len(nonSynonymTransients) > 0:
              for search_name, searchPara in sa.iteritems():
                  self.log.debug("""  searching: %(search_name)s""" % locals())
                  for bf in brightnessFilters:
                      if bf not in searchPara:
                          continue
                      if "association" not in searchPara[bf] or searchPara[bf]["association"] == False:
                          continue
                      if "physical radius kpc" in searchPara[bf]:
  
                          # THE PHYSICAL SEPARATION SEARCHES
                          self.log.debug(
                              'checking physical distance crossmatches in %(search_name)s' % locals())
                          catalogueMatches = self.physical_separation_crossmatch_against_catalogue(
                              objectList=nonSynonymTransients,
                              searchPara=searchPara,
                              search_name=search_name + " physical",
                              brightnessFilter=bf,
                              classificationType="association"
                          )
                      else:
                          # THE ANGULAR SEPARATION SEARCHES
                          self.log.debug(
                              'Crossmatching against %(search_name)s' % locals())
  
                          # RENAMED from searchCatalogue
                          catalogueMatches = self.angular_crossmatch_against_catalogue(
                              objectList=nonSynonymTransients,
                              searchPara=searchPara,
                              search_name=search_name + " angular",
                              brightnessFilter=bf,
                              classificationType="association"
                          )
  
                      # ADD CLASSIFICATION AND CROSSMATCHES IF FOUND
                      if catalogueMatches:
                          allCatalogueMatches = allCatalogueMatches + catalogueMatches
                          catalogueMatches = []
  
          associationIDs = []
          associationIDs[:] = [xm["transient_object_id"]
                               for xm in allCatalogueMatches]
  
          nonAssociationTransients = []
          nonAssociationTransients[:] = [
              t for t in self.transients if t["id"] not in associationIDs]
  
          # ANNOTATION SEARCHES
          # ITERATE THROUGH SEARCH ALGORITHM IN ORDER
          # PRESENTED IN THE SETTINGS FILE
          brightnessFilters = ["bright", "faint", "general"]
          for search_name, searchPara in sa.iteritems():
              for bf in brightnessFilters:
                  if bf not in searchPara:
                      continue
                  if "annotation" not in searchPara[bf] or searchPara[bf]["annotation"] == False:
                      continue
                  self.log.debug("""  searching: %(search_name)s""" % locals())
                  if "physical radius kpc" in searchPara[bf]:
                      # THE PHYSICAL SEPARATION SEARCHES
                      self.log.debug(
                          'checking physical distance crossmatches in %(search_name)s' % locals())
                      if bf in searchPara:
                          catalogueMatches = self.physical_separation_crossmatch_against_catalogue(
                              objectList=nonAssociationTransients,
                              searchPara=searchPara,
                              search_name=search_name + " physical",
                              brightnessFilter=bf,
                              classificationType="annotation"
                          )
                  else:
                      # THE ANGULAR SEPARATION SEARCHES
                      self.log.debug(
                          'Crossmatching against %(search_name)s' % locals())
                      # RENAMED from searchCatalogue
                      if bf in searchPara:
                          catalogueMatches = self.angular_crossmatch_against_catalogue(
                              objectList=nonAssociationTransients,
                              searchPara=searchPara,
                              search_name=search_name + " angular",
                              brightnessFilter=bf,
                              classificationType="annotation"
                          )
  
                  # ADD CLASSIFICATION AND CROSSMATCHES IF FOUND
                  if catalogueMatches:
                      allCatalogueMatches = allCatalogueMatches + catalogueMatches
  
          self.log.debug('completed the ``match`` method')
          return allCatalogueMatches