.. _configuration_file:

##################
Configuration File
##################

Configuration file (default name: ``requake.conf``) is a plain text file
with keys and values in the form ``key = value``.
Comment lines start with ``#``.

Here is the default config file, generated through ``requake sample_config``::

  #### Configuration file for Requake
  
  #### Station metadata and waveform data
  ## FDSN station webservice URL to retrieve station metadata.
  ## Use a full URL or an ObsPy shortcut (e.g., IRIS, EPOSFR, GEOFON, ...)
  fdsn_station_url = http://example.com
  ## Alternatively, you can provide the path to a local file with station
  ## metadata in any format supported by ObsPy (note that some formats may not
  ## contain station coordinates, which are required for the scan, see
  ## https://docs.obspy.org/packages/autogen/obspy.core.inventory.inventory.read_inventory.html)
  ## If both fdsn_station_url and station_metadata_path are provided, the
  ## local file will be used.
  station_metadata_path = None
  ## FDSN dataselect webservice URL to retrieve waveforms.
  ## Use a full URL or an ObsPy shortcut (e.g., IRIS, EPOSFR, GEOFON, ...)
  fdsn_dataselect_url = http://example.com
  ## Alternatively, you can provide the path to a local SDS waveform archive
  ## (see https://docs.obspy.org/packages/autogen/obspy.clients.filesystem.sds.html)
  sds_data_path = None
  ## Or, specify a local directory with waveform files organized per event
  ## This directory should contain subdirectories named after the eventid, each
  ## containing waveform files in any format supported by ObsPy
  ## (e.g., SAC, miniSEED). The eventid should be the same as in the catalog.
  event_data_path = None
  
  #### Catalog-based scan
  ### The following parameters are for a catalog-based scan:
  ### each catalog event is compared with the other catalog events within
  ### a certain distance range. Similarity is checked by waveform
  ### cross-correlation at one or more stations.
  ### To perform a catalog-based scan use:
  ###    requake scan_catalog
  ## FDSN event webservice URL to retrieve event catalogs.
  ## Use a full URL or an ObsPy shortcut (e.g., IRIS, EPOSFR, GEOFON, ...)
  catalog_fdsn_event_url = http://example.com
  ## start time for event selection (UTC date time)
  catalog_start_time = 2021-08-23T00:00:00
  ## end time for event selection (UTC date time or 'now')
  catalog_end_time = 2021-08-24T00:00:00
  ## Optionally, up to three other sources can be defined for different
  ## time intervals
  catalog_fdsn_event_url_1 = None
  catalog_start_time_1 = None
  catalog_end_time_1 = None
  catalog_fdsn_event_url_2 = None
  catalog_start_time_2 = None
  catalog_end_time_2 = None
  catalog_fdsn_event_url_3 = None
  catalog_start_time_3 = None
  catalog_end_time_3 = None
  ## geographic selection (decimal degrees)
  catalog_lat_min = 12.5
  catalog_lat_max = 18.5
  catalog_lon_min = -62.5
  catalog_lon_max = -58.5
  ## depth selection (km, positive down)
  catalog_depth_min = 0
  catalog_depth_max = 60
  ## magnitude selection
  catalog_mag_min = 2
  catalog_mag_max = 4
  ## maximum epicentral distance range to search for similar earthquakes
  ## (radius, km)
  catalog_search_range = 30
  ## trace id(s) to compute cross-correlation, in NET.STA.LOC.CHAN format.
  ## Waveform data for this trace(s) id will be retrieved using the station
  ## webservice.
  ## If more than one trace_id is specified (separated by commas), the closest
  ## station will be used for a given event pair.
  catalog_trace_id = NET.STA.LOC.CHAN
  ## Maximum number of event waveforms kept in memory cache during
  ## catalog-based scan. Higher values increase memory usage and can reduce
  ## repeated waveform downloads.
  catalog_waveform_cache_size = 5000
  ## Per-worker waveform cache size for parallel catalog scan.
  ## Set to 0 to derive it automatically from catalog_waveform_cache_size.
  catalog_waveform_cache_size_parallel = 0
  ## Keep a persistent copy of fetched event waveforms on disk to speed up
  ## reruns. This on-disk cache lives in OUTDIR/waveform_cache and is not
  ## limited by catalog_waveform_cache_size.
  catalog_waveform_disk_cache_enabled = true
  ## Number of worker processes for catalog scan.
  ## 0 means automatic selection; 1 disables parallelism.
  catalog_scan_nprocs = 0
  
  #### Template-based scan
  ### The following parameters are for template-based scan:
  ### A template is used to search for similar waveforms at a given station
  ### over a given time interval.
  ### To perform a template-based scan use:
  ###    requake scan_templates
  ## start time for template search (UTC date time)
  template_start_time = 2021-08-23T00:00:00
  ## end time for event template search (UTC date time or 'now')
  template_end_time = 2021-08-24T00:00:00
  ## Time chunk (in seconds) to analyze continuous data.
  ## Large values (1 hour or more) will result in fewer data requests and
  ## faster execution. However, cross-correlation can be slow for too large
  ## values. No more than one event per time chunk can be detected, so the
  ## length of time chunk should be smaller than the minimum inter-event time
  ## you want to detect.
  time_chunk = 3600
  ## Overlap between time chunks (in seconds)
  time_chunk_overlap = 60
  ## Minimum ratio between cross-correlation (cc) and median absolute deviation
  ## (MAD) of cross-correlation (cc_mad). A detection is declared when:
  ##  cc/cc_mad > min_cc_mad_ratio
  min_cc_mad_ratio = 50
  
  #### Processing parameters
  ## Seconds before P arrival to cut trace
  ## (only used for catalog search and continuous data)
  cc_pre_P = 5
  ## Trace length in seconds (only used for catalog search and continuous data)
  cc_trace_length = 120
  ## Frequency range for computing cross-correlation (Hz)
  cc_freq_min = 2
  cc_freq_max = 10
  ## Maximum authorized shift for computing cross-correlation (s)
  cc_max_shift = 5
  ## Minimum cross-correlation value to declare similar waveforms
  ## (between 0 and 1)
  cc_min = 0.95
  ## Clustering algorithm to create families of similar events.
  ## Possible options are:
  ##  shared : families are created by clustering all event pairs sharing
  ##           an event
  ##  UPGMA : families are created through the Unweighted Pair Group Method
  ##          with Arithmetic Mean (UPGMA) algorithm
  ##          (see https://en.wikipedia.org/wiki/UPGMA)
  clustering_algorithm = shared
  ## Search for anticorrelated events (negative CC)
  cc_allow_negative = false
  ## How families should be sorted when assigning family numbers.
  ## Possible options are:
  ##  time : increasing origin time of first event in family (default option)
  ##  longitude : increasing longitude
  ##  latitude : increasing latitude
  ##  depth : increasing depth
  ##  distance_from : increasing horizontal distance from a given point
  sort_families_by = time
  ## Longitude and latitude of reference point,
  ## if sort_families_by = 'distance_from'
  distance_from_lon = None
  distance_from_lat = None
  ## Templates are built by averaging the traces in the family.
  ## Set the following parameter to True if you want to normalize the traces
  ## before averaging.
  ## Normalization will produce an average trace which is more representative
  ## of the family, but will be less effective in reducing noise.
  normalize_traces_before_averaging = False
  
  #### Post-processing parameters
  ## Estimation of fault slip (in cm) from repeater's magnitude
  ## Choose between:
  ##  NJ1998 : Nadeau and Johnson (1998)
  ##  B2001 : Beeler et al. (2001)
  ##  E1957 : Eshelby (1957), circular crack model
  ## See Uchida (2019, https://doi.org/10.1186/s40645-019-0284-z) for details
  ## on the models.
  mag_to_slip_model = NJ1998
  ## Static stress drop value for B2001 and E1957 models (MPa)
  static_stress_drop = 10.0
  ## Rigidity value for B2001 and E1957 models (GPa)
  rigidity = 30.0
  ## Strain hardening coefficient for B2001 model (MPa/cm)
  strain_hardening = 0.5