docs: def classify(self):
          """
          *classify the transients selected from the transient selection query in the settings file or passed in via the CL or other code*
  
          **Return:**
              - ``crossmatches`` -- list of dictionaries of crossmatched associated sources
              - ``classifications`` -- the classifications assigned to the transients post-crossmatches (dictionary of rank ordered list of classifications)
  
          See 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
          """
  
          global theseBatches
          global crossmatchArray
  
          self.log.debug('starting the ``classify`` method')
  
          remaining = 1
  
          # THE COLUMN MAPS - WHICH COLUMNS IN THE CATALOGUE TABLES = RA, DEC,
          # REDSHIFT, MAG ETC
          colMaps = get_crossmatch_catalogues_column_map(
              log=self.log,
              dbConn=self.cataloguesDbConn
          )
  
          self._create_tables_if_not_exist()
  
          import time
          start_time = time.time()
  
          # COUNT SEARCHES
          sa = self.settings["search algorithm"]
          searchCount = 0
          brightnessFilters = ["bright", "faint", "general"]
          for search_name, searchPara in sa.iteritems():
              for bf in brightnessFilters:
                  if bf in searchPara:
                      searchCount += 1
  
          cpuCount = psutil.cpu_count()
          if searchCount > cpuCount:
              searchCount = cpuCount
  
          largeBatchSize = 5000
          miniBatchSize = 100
          self.largeBatchSize = largeBatchSize
  
          # print "mini batch size ", str(miniBatchSize)
  
          while remaining:
  
              # IF A TRANSIENT HAS NOT BEEN PASSED IN VIA THE COMMAND-LINE, THEN
              # QUERY THE TRANSIENT DATABASE
              if not self.ra and not self.dec:
  
                  # COUNT REMAINING TRANSIENTS
                  from fundamentals.mysql import readquery
                  sqlQuery = self.settings["database settings"][
                      "transients"]["transient count"]
                  thisInt = randint(0, 100)
                  if "where" in sqlQuery:
                      sqlQuery = sqlQuery.replace(
                          "where", "where %(thisInt)s=%(thisInt)s and " % locals())
  
                  if remaining == 1 or remaining < largeBatchSize:
                      rows = readquery(
                          log=self.log,
                          sqlQuery=sqlQuery,
                          dbConn=self.transientsDbConn,
                      )
                      remaining = rows[0]["count(*)"]
                  else:
                      remaining = remaining - largeBatchSize
  
                  print "%(remaining)s transient sources requiring a classification remain" % locals()
  
                  # START THE TIME TO TRACK CLASSIFICATION SPPED
                  start_time = time.time()
  
                  # A LIST OF DICTIONARIES OF TRANSIENT METADATA
                  transientsMetadataList = self._get_transient_metadata_from_database_list()
  
                  count = len(transientsMetadataList)
                  print "  now classifying the next %(count)s transient sources" % locals()
  
                  # EXAMPLE OF TRANSIENT METADATA
                  # { 'name': 'PS17gx',
                  # 'alt_id': 'PS17gx',
                  # 'object_classification': 'SN',
                  # 'dec': '+43:25:44.1',
                  # 'id': 1,
                  # 'ra': '08:57:57.19'}
              # TRANSIENT PASSED VIA COMMAND-LINE
              else:
                  if not self.name:
                      name = "transient"
                  else:
                      name = self.name
                  transient = {
                      'name': name,
                      'object_classification': None,
                      'dec': self.dec,
                      'id': name,
                      'ra': self.ra
                  }
                  transientsMetadataList = [transient]
                  remaining = 0
  
              if self.oneRun:
                  remaining = 0
  
              if len(transientsMetadataList) == 0:
                  if self.daemonMode == False:
                      remaining = 0
                      print "No transients need classified"
                      return None, None
                  else:
                      print "No remaining transients need classified, will try again in 5 mins"
                      time.sleep("10")
  
              # FROM THE LOCATIONS OF THE TRANSIENTS, CHECK IF OUR LOCAL NED DATABASE
              # NEEDS UPDATED
              if self.updateNed:
  
                  self._update_ned_stream(
                      transientsMetadataList=transientsMetadataList
                  )
  
              # SOME TESTING SHOWED THAT 25 IS GOOD
              total = len(transientsMetadataList)
              batches = int((float(total) / float(miniBatchSize)) + 1.)
  
              if batches == 0:
                  batches = 1
  
              start = 0
              end = 0
              theseBatches = []
              for i in range(batches):
                  end = end + miniBatchSize
                  start = i * miniBatchSize
                  thisBatch = transientsMetadataList[start:end]
                  theseBatches.append(thisBatch)
  
              print "BATCH SIZE = %(total)s" % locals()
              print "MINI BATCH SIZE = %(batches)s x %(miniBatchSize)s" % locals()
  
              # DEFINE AN INPUT ARRAY
              # cores = psutil.cpu_count()
              # if cores > 8:
              #     cores = 8
  
              start_time2 = time.time()
  
              print "START CROSSMATCH"
  
              crossmatchArray = fmultiprocess(log=self.log, function=self._crossmatch_transients_against_catalogues,
                                              inputArray=range(len(theseBatches)), poolSize=None, colMaps=colMaps)
  
              print "FINISH CROSSMATCH/START RANKING: %d" % (time.time() - start_time2,)
              start_time2 = time.time()
  
              classifications = {}
              crossmatches = []
  
              for sublist in crossmatchArray:
                  sublist = sorted(
                      sublist, key=itemgetter('transient_object_id'))
  
                  # REORGANISE INTO INDIVIDUAL TRANSIENTS FOR RANKING AND
                  # TOP-LEVEL CLASSIFICATION EXTRACTION
  
                  batch = []
                  if len(sublist) != 0:
                      transientId = sublist[0]['transient_object_id']
                      for s in sublist:
                          if s['transient_object_id'] != transientId:
                              # RANK TRANSIENT CROSSMATCH BATCH
                              cl, cr = self._rank_classifications(
                                  batch, colMaps)
                              crossmatches.extend(cr)
                              classifications = dict(
                                  classifications.items() + cl.items())
  
                              transientId = s['transient_object_id']
                              batch = [s]
                          else:
                              batch.append(s)
  
                      # RANK FINAL BATCH
                      cl, cr = self._rank_classifications(
                          batch, colMaps)
                      classifications = dict(
                          classifications.items() + cl.items())
                      crossmatches.extend(cr)
  
              for t in transientsMetadataList:
                  if t["id"] not in classifications:
                      classifications[t["id"]] = ["ORPHAN"]
  
              if self.cl:
                  self._print_results_to_stdout(
                      classifications=classifications,
                      crossmatches=crossmatches
                  )
  
              # UPDATE THE TRANSIENT DATABASE IF UPDATE REQUESTED (ADD DATA TO
              # tcs_crossmatch_table AND A CLASSIFICATION TO THE ORIGINAL TRANSIENT
              # TABLE)
              print "FINISH RANKING/START UPDATING TRANSIENT DB: %d" % (time.time() - start_time2,)
              start_time2 = time.time()
              if self.update and not self.ra:
                  self._update_transient_database(
                      crossmatches=crossmatches,
                      classifications=classifications,
                      transientsMetadataList=transientsMetadataList,
                      colMaps=colMaps
                  )
  
              print "FINISH UPDATING TRANSIENT DB/START ANNOTATING TRANSIENT DB: %d" % (time.time() - start_time2,)
              start_time2 = time.time()
  
              if self.ra:
                  return classifications, crossmatches
  
              if self.updatePeakMags and self.settings["database settings"]["transients"]["transient peak magnitude query"]:
                  self.update_peak_magnitudes()
              self.update_classification_annotations_and_summaries(
                  self.updatePeakMags)
  
              print "FINISH ANNOTATING TRANSIENT DB: %d" % (time.time() - start_time2,)
              start_time2 = time.time()
  
              classificationRate = count / (time.time() - start_time)
              print "Sherlock is classify at a rate of %(classificationRate)2.1f transients/sec" % locals()
  
          self.log.debug('completed the ``classify`` method')
          return None, None