docs: def read_in_survey_parameters(
      log,
      pathToSettingsFile
  ):
      """
      *First reads in the mcs_settings.yaml file to determine the name of the settings file to read in the survey parameters.*
  
      **Key Arguments:**
          - ``log`` -- logger
          - ``pathToSettingsFile`` -- path to the settings file for the simulation
  
      **Return:**
          - a tuple of settings lists and dictionaries
      """
      ################ > IMPORTS ################
      ## STANDARD LIB ##
      ## THIRD PARTY ##
      import yaml
      ## LOCAL APPLICATION ##
  
      ############### VARIABLE ATTRIBUTES #############
      ################ >ACTION(S) ################
      # READ THE NAME OF THE SETTINGS FILE FOR THIS SIMULATION
      try:
          stream = file(pathToSettingsFile, 'r')
          thisDict = yaml.load(stream)
          stream.close()
      except Exception, e:
          print str(e)
  
      # NOW READ IN THE USER SET MCS SETTINGS
      try:
          stream = file(pathToSettingsFile, 'r')
          thisDict = yaml.load(stream)
          stream.close()
      except Exception, e:
          print str(e)
  
      allSettings = thisDict
      programSettings = thisDict["Program Settings"]
  
      limitingMags = thisDict["Limiting Magnitudes"]
      # for key in limitingMags:
      # log.debug('filter: %s, limit: %s' % (key, limitingMags[key]))
  
      sampleNumber = thisDict["Simulation Sample"]
  
      peakMagnitudeDistributions = thisDict[
          "SN Absolute Peak-Magnitude Distributions"]
      #log.debug('snDistributions[magnitude] %s' % (snDistributions["magnitude"],))
      #log.debug('snDistributions[sigma] %s' % (snDistributions["sigma"],))
  
      relativeRatesSet = thisDict["Relative Rate Set to Use"]
      relativeSNRates = thisDict["Relative SN Rates"][relativeRatesSet]
      #log.debug('relativeSNRates %s' % (relativeSNRates,))
      lowerReshiftLimit = thisDict["Lower Redshift Limit"]
      upperRedshiftLimit = thisDict["Upper Redshift Limit"]
      #log.debug('upperRedshiftLimit %s' % (upperRedshiftLimit,))
      redshiftResolution = thisDict["Redshift Resolution"]
  
      extinctionSettings = thisDict["Extinctions"]
      extinctionType = extinctionSettings["constant or random"]
      extinctionConstant = extinctionSettings["constant E(b-v)"]
  
      hostExtinctionDistributions = extinctionSettings["host"]
      #log.debug('hostExtinctionDistributions %s' % (hostExtinctionDistributions,))
      galacticExtinctionDistribution = extinctionSettings["galactic"]
      #log.debug('galacticExtinctionDistribution %s' % (galacticExtinctionDistribution,))
  
      surveyCadenceSettings = thisDict["Survey Cadence"]
      #log.debug('surveyCadenceSettings %s' % (surveyCadenceSettings,))
  
      explosionDaysFromSettings = thisDict["Explosion Days"]
      extendLightCurveTail = thisDict["Extend lightcurve tail?"]
  
      snLightCurves = thisDict["Lightcurves"]
      lightCurvePolyOrder = thisDict[
          "Order of polynomial used to fits lightcurves"]
      #log.debug('snlightCurves %s' % (snlightCurves,))
  
      surveyArea = thisDict["Sky Area of the Survey (square degrees)"]
      CCSNRateFraction = thisDict["CCSN Progenitor Population Fraction of IMF"]
      transientToCCSNRateFraction = thisDict["Transient to CCSN Ratio"]
      extraSurveyConstraints = thisDict["Extra Survey Constraints"]
      restFrameFilter = thisDict["Rest Frame Filter for K-corrections"]
      kCorrectionTemporalResolution = thisDict[
          "K-correction temporal resolution (days)"]
      kCorPolyOrder = thisDict["Order of polynomial used to fits k-corrections"]
      kCorMinimumDataPoints = thisDict[
          "Minimum number of datapoints used to generate k-correction curve"]
      logLevel = thisDict["Level of logging required"]
  
      return (
          allSettings,
          programSettings,
          limitingMags,
          sampleNumber,
          peakMagnitudeDistributions,
          explosionDaysFromSettings,
          extendLightCurveTail,
          relativeSNRates,
          lowerReshiftLimit,
          upperRedshiftLimit,
          redshiftResolution,
          restFrameFilter,
          kCorrectionTemporalResolution,
          kCorPolyOrder,
          kCorMinimumDataPoints,
          extinctionType,
          extinctionConstant,
          hostExtinctionDistributions,
          galacticExtinctionDistribution,
          surveyCadenceSettings,
          snLightCurves,
          surveyArea,
          CCSNRateFraction,
          transientToCCSNRateFraction,
          extraSurveyConstraints,
          lightCurvePolyOrder,
          logLevel)