docs: def update_classification_annotations_and_summaries(
              self,
              updatePeakMagnitudes=True):
          """*update classification annotations and summaries*
  
          **Key Arguments:**
              - ``updatePeakMagnitudes`` -- update the peak magnitudes in the annotations to give absolute magnitudes. Default *True*
  
              **Return:**
              - None
  
          **Usage:**
              ..  todo::
  
                  - add usage info
                  - create a sublime snippet for usage
                  - write a command-line tool for this method
                  - update package tutorial with command-line tool info if needed
  
              .. code-block:: python
  
                  usage code
  
  
          .. 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 ``update_classification_annotations_and_summaries`` method')
  
          # import time
          # start_time = time.time()
          # print "COLLECTING TRANSIENTS WITH NO ANNOTATIONS"
  
          if updatePeakMagnitudes:
              sqlQuery = u"""
                  SELECT * from sherlock_crossmatches cm, sherlock_classifications cl where rank =1 and cl.transient_object_id=cm.transient_object_id and (cl.annotation is null orcl.dateLastModified is null or cl.dateLastModified > DATE_SUB(NOW(), INTERVAL 30 DAY)) order by  cl.dateLastModified asc limit 100000
              """ % locals()
          else:
              sqlQuery = u"""
                  SELECT * from sherlock_crossmatches cm, sherlock_classifications cl where rank =1 and cl.transient_object_id=cm.transient_object_id and cl.summary is null
              """ % locals()
  
          rows = readquery(
              log=self.log,
              sqlQuery=sqlQuery,
              dbConn=self.transientsDbConn,
              quiet=False
          )
  
          # print "FINISHED COLLECTING TRANSIENTS WITH NO ANNOTATIONS/GENERATING ANNOTATIONS: %d" % (time.time() - start_time,)
          # start_time = time.time()
  
          from astrocalc.coords import unit_conversion
          # ASTROCALC UNIT CONVERTER OBJECT
          converter = unit_conversion(
              log=self.log
          )
  
          updates = []
  
          for row in rows:
  
              catalogue = row["catalogue_table_name"]
              objectId = row["catalogue_object_id"]
              objectType = row["catalogue_object_type"]
              objectSubtype = row["catalogue_object_subtype"]
              catalogueString = catalogue
              if "catalogue" not in catalogueString.lower():
                  catalogueString = catalogue + " catalogue"
              if "/" in catalogueString:
                  catalogueString += "s"
  
              if "ned" in catalogue.lower() and "/" not in catalogue:
                  objectId = '''<a href="https://ned.ipac.caltech.edu/cgi-bin/objsearch?objname=%(objectId)s&extend=no&hconst=73&omegam=0.27&omegav=0.73&corr_z=1&out_csys=Equatorial&out_equinox=J2000.0&obj_sort=RA+or+Longitude&of=pre_text&zv_breaker=30000.0&list_limit=5&img_stamp=YES">%(objectId)s</a>''' % locals()
              elif "sdss" in catalogue.lower() and "/" not in catalogue:
                  objectId = "http://skyserver.sdss.org/dr12/en/tools/explore/Summary.aspx?id=%(objectId)s" % locals(
                  )
  
                  ra = converter.ra_decimal_to_sexegesimal(
                      ra=row["raDeg"],
                      delimiter=""
                  )
                  dec = converter.dec_decimal_to_sexegesimal(
                      dec=row["decDeg"],
                      delimiter=""
                  )
                  betterName = "SDSS J" + ra[0:9] + dec[0:9]
                  objectId = '''<a href="%(objectId)s">%(betterName)s</a>''' % locals()
              elif "milliquas" in catalogue.lower() and "/" not in catalogue:
                  thisName = objectId
                  objectId = objectId.replace(" ", "+")
                  objectId = '''<a href="https://heasarc.gsfc.nasa.gov/db-perl/W3Browse/w3table.pl?popupFrom=Query+Results&tablehead=name%%3Dheasarc_milliquas%%26description%%3DMillion+Quasars+Catalog+%%28MILLIQUAS%%29%%2C+Version+4.8+%%2822+June+2016%%29%%26url%%3Dhttp%%3A%%2F%%2Fheasarc.gsfc.nasa.gov%%2FW3Browse%%2Fgalaxy-catalog%%2Fmilliquas.html%%26archive%%3DN%%26radius%%3D1%%26mission%%3DGALAXY+CATALOG%%26priority%%3D5%%26tabletype%%3DObject&dummy=Examples+of+query+constraints%%3A&varon=name&bparam_name=%%3D%%22%(objectId)s%%22&bparam_name%%3A%%3Aunit=+&bparam_name%%3A%%3Aformat=char25&varon=ra&bparam_ra=&bparam_ra%%3A%%3Aunit=degree&bparam_ra%%3A%%3Aformat=float8%%3A.5f&varon=dec&bparam_dec=&bparam_dec%%3A%%3Aunit=degree&bparam_dec%%3A%%3Aformat=float8%%3A.5f&varon=bmag&bparam_bmag=&bparam_bmag%%3A%%3Aunit=mag&bparam_bmag%%3A%%3Aformat=float8%%3A4.1f&varon=rmag&bparam_rmag=&bparam_rmag%%3A%%3Aunit=mag&bparam_rmag%%3A%%3Aformat=float8%%3A4.1f&varon=redshift&bparam_redshift=&bparam_redshift%%3A%%3Aunit=+&bparam_redshift%%3A%%3Aformat=float8%%3A6.3f&varon=radio_name&bparam_radio_name=&bparam_radio_name%%3A%%3Aunit=+&bparam_radio_name%%3A%%3Aformat=char22&varon=xray_name&bparam_xray_name=&bparam_xray_name%%3A%%3Aunit=+&bparam_xray_name%%3A%%3Aformat=char22&bparam_lii=&bparam_lii%%3A%%3Aunit=degree&bparam_lii%%3A%%3Aformat=float8%%3A.5f&bparam_bii=&bparam_bii%%3A%%3Aunit=degree&bparam_bii%%3A%%3Aformat=float8%%3A.5f&bparam_broad_type=&bparam_broad_type%%3A%%3Aunit=+&bparam_broad_type%%3A%%3Aformat=char4&bparam_optical_flag=&bparam_optical_flag%%3A%%3Aunit=+&bparam_optical_flag%%3A%%3Aformat=char3&bparam_red_psf_flag=&bparam_red_psf_flag%%3A%%3Aunit=+&bparam_red_psf_flag%%3A%%3Aformat=char1&bparam_blue_psf_flag=&bparam_blue_psf_flag%%3A%%3Aunit=+&bparam_blue_psf_flag%%3A%%3Aformat=char1&bparam_ref_name=&bparam_ref_name%%3A%%3Aunit=+&bparam_ref_name%%3A%%3Aformat=char6&bparam_ref_redshift=&bparam_ref_redshift%%3A%%3Aunit=+&bparam_ref_redshift%%3A%%3Aformat=char6&bparam_qso_prob=&bparam_qso_prob%%3A%%3Aunit=percent&bparam_qso_prob%%3A%%3Aformat=int2%%3A3d&bparam_alt_name_1=&bparam_alt_name_1%%3A%%3Aunit=+&bparam_alt_name_1%%3A%%3Aformat=char22&bparam_alt_name_2=&bparam_alt_name_2%%3A%%3Aunit=+&bparam_alt_name_2%%3A%%3Aformat=char22&Entry=&Coordinates=J2000&Radius=Default&Radius_unit=arcsec&NR=CheckCaches%%2FGRB%%2FSIMBAD%%2BSesame%%2FNED&Time=&ResultMax=1000&displaymode=Display&Action=Start+Search&table=heasarc_milliquas">%(thisName)s</a>''' % locals()
  
              if objectSubtype and objectSubtype.lower() in ["uvs", "radios", "xray", "qso", "irs", 'uves', 'viss', 'hii', 'gclstr', 'ggroup', 'gpair', 'gtrpl']:
                  objectType = objectSubtype
  
              if objectType == "star":
                  objectType = "stellar source"
              elif objectType == "agn":
                  objectType = "AGN"
              elif objectType == "cb":
                  objectType = "CV"
              elif objectType == "unknown":
                  objectType = "unclassified source"
  
              sep = row["separationArcsec"]
              if row["classificationReliability"] == 1:
                  classificationReliability = "synonymous"
                  psep = row["physical_separation_kpc"]
                  if psep:
                      location = '%(sep)0.1f" (%(psep)0.1f Kpc) from the %(objectType)s core' % locals(
                      )
                  else:
                      location = '%(sep)0.1f" from the %(objectType)s core' % locals(
                      )
              elif row["classificationReliability"] in (2, 3):
                  classificationReliability = "possibly associated"
                  n = row["northSeparationArcsec"]
                  if n > 0:
                      nd = "S"
                  else:
                      nd = "N"
                  e = row["eastSeparationArcsec"]
                  if e > 0:
                      ed = "W"
                  else:
                      ed = "E"
                  n = math.fabs(n)
                  e = math.fabs(e)
                  psep = row["physical_separation_kpc"]
                  if psep:
                      location = '%(n)0.2f" %(nd)s, %(e)0.2f" %(ed)s (%(psep)0.1f Kpc) from the %(objectType)s centre' % locals(
                      )
                  else:
                      location = '%(n)0.2f" %(nd)s, %(e)0.2f" %(ed)s from the %(objectType)s centre' % locals(
                      )
                  location = location.replace("unclassified", "object's")
  
              best_mag = None
              best_mag_error = None
              best_mag_filter = None
              filters = ["R", "V", "B", "I", "J", "G", "H", "K", "U",
                         "_r", "_g", "_i", "_g", "_z", "_y", "_u", "unkMag"]
              for f in filters:
                  if row[f] and not best_mag:
                      best_mag = row[f]
                      best_mag_error = row[f + "Err"]
                      subfilter = f.replace(
                          "_", "").replace("Mag", "")
                      best_mag_filter = f.replace(
                          "_", "").replace("Mag", "") + "="
                      if "unk" in best_mag_filter:
                          best_mag_filter = ""
                          subfilter = ''
  
              if not best_mag_filter:
                  if str(best_mag).lower() in ("8", "11", "18"):
                      best_mag_filter = "an "
                  else:
                      best_mag_filter = "a "
              else:
                  if str(best_mag_filter)[0].lower() in ("r", "i", "h"):
                      best_mag_filter = "an " + best_mag_filter
                  else:
                      best_mag_filter = "a " + best_mag_filter
              if not best_mag:
                  best_mag = "an unknown-"
                  best_mag_filter = ""
              else:
                  best_mag = "%(best_mag)0.2f " % locals()
  
              distance = None
              if row["direct_distance"]:
                  d = row["direct_distance"]
                  distance = "distance of %(d)0.1f Mpc" % locals()
  
                  if row["z"]:
                      z = row["z"]
                      distance += "(z=%(z)0.3f)" % locals()
              elif row["z"]:
                  z = row["z"]
                  distance = "z=%(z)0.3f" % locals()
              elif row["photoZ"]:
                  z = row["photoZ"]
                  zErr = row["photoZErr"]
                  distance = "photoZ=%(z)0.3f (&plusmn%(zErr)0.3f)" % locals()
  
              if distance:
                  distance = "%(distance)s" % locals()
  
              distance_modulus = None
              if row["direct_distance_modulus"]:
                  distance_modulus = row["direct_distance_modulus"]
              elif row["distance_modulus"]:
                  distance_modulus = row["distance_modulus"]
  
              if updatePeakMagnitudes:
                  if distance:
                      absMag = row["transientAbsMag"]
                      absMag = """ A host %(distance)s implies a transient <em>M =</em> %(absMag)s.""" % locals(
                      )
                  else:
                      absMag = ""
              else:
                  if distance and distance_modulus:
                      absMag = "%(distance_modulus)0.2f" % locals()
                      absMag = """ A host %(distance)s implies a <em>m - M =</em> %(absMag)s.""" % locals(
                      )
                  else:
                      absMag = ""
  
              annotation = "The transient is %(classificationReliability)s with <em>%(objectId)s</em>; %(best_mag_filter)s%(best_mag)smag %(objectType)s found in the %(catalogueString)s. It's located %(location)s.%(absMag)s" % locals()
              summary = '%(sep)0.1f" from %(objectType)s in %(catalogue)s' % locals(
              )
  
              update = {
                  "transient_object_id": row["transient_object_id"],
                  "annotation": annotation,
                  "summary": summary,
                  "separationArcsec": sep
              }
              updates.append(update)
  
          # print "FINISHED GENERATING ANNOTATIONS/ADDING ANNOTATIONS TO TRANSIENT DATABASE: %d" % (time.time() - start_time,)
          # start_time = time.time()
  
          insert_list_of_dictionaries_into_database_tables(
              dbConn=self.transientsDbConn,
              log=self.log,
              dictList=updates,
              dbTableName="sherlock_classifications",
              dateModified=True,
              batchSize=10000,
              replace=True,
              dbSettings=self.settings["database settings"]["transients"]
          )
  
          # print "FINISHED ADDING ANNOTATIONS TO TRANSIENT DATABASE/UPDATING ORPHAN ANNOTATIONS: %d" % (time.time() - start_time,)
          # start_time = time.time()
  
          sqlQuery = """update sherlock_classifications  set annotation = "The transient location is not matched against any known catalogued source", summary = "No catalogued match" where classification = 'ORPHAN'  and summary is null """ % locals()
          writequery(
              log=self.log,
              sqlQuery=sqlQuery,
              dbConn=self.transientsDbConn,
          )
  
          # print "FINISHED UPDATING ORPHAN ANNOTATIONS: %d" % (time.time() - start_time,)
          # start_time = time.time()
  
          self.log.debug(
              'completed the ``update_classification_annotations_and_summaries`` method')
          return None