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