docs: def validate_analysis_period(self):
          """Get a collection where the header analysis_period aligns with datetimes.
  
          This means that checks for three criteria will be performed:
          1) All months in the data collection are chronological starting from the
              analysis_period start month to the end month.
          2) No duplicate months exist in the data collection.
          3) There are no months that lie outside of the analysis_period range.
  
          Note that there is no need to run this check any time that a
          data collection has been derived from a continuous one or when the
          validated_a_period attribute of the collection is True.
          """
          a_per = self.header.analysis_period
          n_ap = [a_per.st_month, a_per.end_month]
  
          # make sure that months are in chronological order.
          sort_datetimes, sort_values = zip(*sorted(zip(self.datetimes, self.values)))
          # check that no datetimes lie outside of the analysis_period
          if not a_per.is_reversed and not a_per.is_annual:
              if sort_datetimes[0] < a_per.st_month:
                  n_ap[0] = sort_datetimes[0]
              if sort_datetimes[-1] > a_per.end_month:
                  n_ap[1] = sort_datetimes[-1]
          elif a_per.is_reversed:
              last_ind = None
              for i, date_t in enumerate(sort_datetimes):
                  last_ind = i if date_t <= a_per.end_time.month else last_ind
              if last_ind is not None:
                  last_ind = last_ind + 1
                  sort_datetimes = sort_datetimes[last_ind:] + sort_datetimes[:last_ind]
                  sort_values = sort_values[last_ind:] + sort_values[:last_ind]
              if sort_datetimes[0] > a_per.end_time.month and \
                      sort_datetimes[0] < a_per.st_time.month:
                  n_ap = [1, 12]
                  sort_datetimes, sort_values = zip(*sorted(zip(
                      self.datetimes, self.values)))
  
          # check that there are no duplicate months.
          for i in xrange(len(sort_datetimes)):
              assert sort_datetimes[i] != sort_datetimes[i - 1], 'Duplicate month ' \
                  'was found in the collection: {}'.format(sort_datetimes[i])
  
          # build a validated collection.
          new_ap = AnalysisPeriod(st_month=n_ap[0], end_month=n_ap[1])
          new_header = self.header.duplicate()
          new_header._analysis_period = new_ap
          new_coll = MonthlyCollection(new_header, sort_values, sort_datetimes)
          new_coll._validated_a_period = True
          return new_coll