docs: def physical_separation_crossmatch_against_catalogue(
          self,
          objectList,
          searchPara,
          search_name,
          brightnessFilter=False,
          classificationType=False
      ):
          """*perform an physical separation crossmatch against a given catalogue in the database*
  
          This search is basically the same as the angular separation search except extra filtering is done to exclude sources outside the physical search radius (matched sources require distance info to calulate physical separations)
  
          **Key Arguments:**
              - ``objectList`` -- transients to be crossmatched
              - ``searchPara`` -- parameters of the search (from settings file)
              - ``search_name`` -- the name of the search
              - ``brightnessFilter`` -- is this search to be constrained by magnitude of the catalogue sources? Default *False*. [bright|faint|general]
              - ``classificationType`` -- synonym, association or annotation. Default *False*
  
          **Return:**
              - matchedObjects -- any sources matched against the object
  
          To run a physical separation crossmatch, run in a similar way to the angular separation crossmatch:
  
          **Usage:**
  
              .. code-block:: python 
  
                  search_name = "ned spec sn"
                  searchPara = self.settings["search algorithm"][search_name]
                  matchedObjects = xmatcher.physical_separation_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 ``physical_separation_crossmatch_against_catalogue`` method')
  
          start_time = time.time()
  
          bf = brightnessFilter
          # SETUP PARAMETERS
          tableName = searchPara["database table"]
          if bf:
              angularRadius = searchPara[bf]["angular radius arcsec"]
              physicalRadius = searchPara[bf]["physical radius kpc"]
              matchedType = searchPara[bf][classificationType]
              if "match nearest source only" in searchPara[bf]:
                  nearestOnly = searchPara[bf]["match nearest source only"]
              else:
                  nearestOnly = False
          else:
              angularRadius = searchPara["angular radius arcsec"]
              physicalRadius = searchPara["physical radius kpc"]
              matchedType = searchPara[classificationType]
              if "match nearest source only" in searchPara:
                  nearestOnly = searchPara["match nearest source only"]
              else:
                  nearestOnly = False
  
          matchedObjects = []
          matchSubset = []
  
          # RETURN ALL ANGULAR MATCHES BEFORE RETURNING NEAREST PHYSICAL SEARCH
          tmpSearchPara = dict(searchPara)
          tmpSearchPara["match nearest source only"] = False
  
          # ANGULAR CONESEARCH ON CATALOGUE - RETURN ALL MATCHES
          catalogueMatches = self.angular_crossmatch_against_catalogue(
              objectList=objectList,
              searchPara=tmpSearchPara,
              search_name=search_name,
              physicalSearch=True,
              brightnessFilter=brightnessFilter,
              classificationType=classificationType
          )
  
          # OK - WE HAVE SOME ANGULAR SEPARATION MATCHES. NOW SEARCH THROUGH THESE FOR MATCHES WITH
          # A PHYSICAL SEPARATION WITHIN THE PHYSICAL RADIUS.
          if catalogueMatches:
              for row in catalogueMatches:
                  thisMatch = False
                  physical_separation_kpc = row["physical_separation_kpc"]
                  newsearch_name = search_name
  
                  # FIRST CHECK FOR MAJOR AXIS MEASUREMENT
                  # BYPASS NED FAULTY AXES MEASUREMENTS:
                  # https://gist.github.com/search?utf8=%E2%9C%93&q=user%3Athespacedoctor+ned
                  if row["major_axis_arcsec"] and ("ned" not in search_name or (row["unkMag"] and row["unkMag"] < 20.)):
                      if row["separationArcsec"] < row["major_axis_arcsec"] * self.settings["galaxy radius stetch factor"]:
                          thisMatch = True
                          newsearch_name = newsearch_name + \
                              " (within %s * major axis)" % (
                                  self.settings["galaxy radius stetch factor"],)
                          newAngularSep = row[
                              "major_axis_arcsec"] * self.settings["galaxy radius stetch factor"]
                      else:
                          continue
                  # NOW CHECK FOR A DIRECT DISTANCE MEASUREMENT
                  elif row["direct_distance_scale"] and physical_separation_kpc < physicalRadius:
                      if row["separationArcsec"] > 300.:
                          continue
                      thisMatch = True
                      newsearch_name = newsearch_name + " (direct distance)"
                      newAngularSep = physicalRadius / \
                          row["direct_distance_scale"]
                  # NEW CHECK FOR A REDSHIFT DISTANCE
                  elif row["scale"] and physical_separation_kpc < physicalRadius:
                      thisMatch = True
                      newsearch_name = newsearch_name + " (redshift distance)"
                      newAngularSep = physicalRadius / row["scale"]
  
                  if thisMatch == True:
                      row["physical_separation_kpc"] = physical_separation_kpc
                      row["original_search_radius_arcsec"] = newAngularSep
                      if physical_separation_kpc:
                          self.log.debug(
                              "\t\tPhysical separation = %.2f kpc" % (physical_separation_kpc,))
                      row["search_name"] = newsearch_name
                      matchSubset.append(row)
  
          if matchSubset:
  
              from operator import itemgetter
              matchSubset = sorted(matchSubset, key=itemgetter(
                  'physical_separation_kpc'), reverse=False)
  
              if nearestOnly == True:
                  theseMatches = matchSubset[0]
              else:
                  theseMatches = matchSubset
  
              matchedObjects = matchSubset
          self.log.debug(
              'completed the ``physical_separation_crossmatch_against_catalogue`` method')
  
          self.log.debug("FINISHED %s SEARCH IN %0.5f s" %
                         (search_name, time.time() - start_time,))
  
          return matchedObjects