.. _configuration_file:

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

Configuration file (default name: ``seiscat.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::

  # Configuration file for seiscat
  
  
  ## SQLite database
  ## Event information is stored in a SQLite database, in a table named "events".
  ## The following default (protected) columns are always created:
  ## - evid: event ID
  ## - ver: event version
  ## - time: event origin time (UTC date time)
  ## - lat: event latitude (decimal degrees)
  ## - lon: event longitude (decimal degrees)
  ## - depth: event depth (km, positive down)
  ## - mag: event magnitude (magnitude units)
  ## - mag_type: event magnitude type
  ## - event_type: event type
  ##
  ## Additional user columns can be defined with extra_field_names/types/defaults
  ## below. They are created when the database is initialized and are NOT
  ## protected (they can be renamed/deleted later with "seiscat editdb").
  # Database file name
  db_file = seiscat_db.sqlite
  # List of extra columns to add at database initialization
  # ex.: extra_field_names = field1, field2, field3
  extra_field_names = None
  # List of extra column types (SQLite types)
  # ex.: extra_field_types = TEXT, REAL, BOOLEAN
  extra_field_types = None
  # List of extra column default values (or None)
  # ex.: extra_field_defaults = "", 0.0, False
  extra_field_defaults = None
  
  
  ## FDSN event webservice URL or shortcut for event data and metadata
  # It can be an ObsPy supported shortcut (ex., ISC, USGS, EPOSFR)
  # or a full URL (ex., http://www.isc.ac.uk)
  fdsn_event_url = None
  # Optional credentials for fdsn_event_url authentication
  # Note: restrict file permissions (chmod 600) to protect these values
  fdsn_event_user = None
  fdsn_event_password = None
  # List of FDSN web service providers to download waveforms and station metadata
  # They can be ObsPy supported shortcuts (ex., IRIS, SCEDC, EPOSFR) or full URLs
  # (ex., http://service.iris.edu). Leave it as None to use all the
  # providers supported by ObsPy.
  fdsn_providers = None
  # Optional credentials for fdsn_providers authentication.
  # Each entry corresponds to the provider at the same position in fdsn_providers.
  # Use None for providers that don't require credentials.
  # ex.: fdsn_providers_users = myuser, None, otheruser
  # ex.: fdsn_providers_passwords = mypass, None, otherpass
  # Note: restrict file permissions (chmod 600) to protect these values
  fdsn_providers_users = None
  fdsn_providers_passwords = None
  
  
  ## Directory names to store event and waveform data and station metadata
  # Directory to store event data. For each event, an event directory named
  # after the event ID will be created inside this directory.
  event_dir = events
  # Directory to store waveform data.
  # It will be created inside the event directory.
  waveform_dir = waveforms
  # Directory to store station metadata.
  # It will be created inside the event directory.
  station_dir = stations
  
  
  ## Event selection criteria for downloading event data
  ## and/or cropping the database.
  ## Use "None" to signify no limit
  # Start time for event selection (UTC date time, time interval or None)
  #  ex.: start_time = 2021-08-23T00:00:00
  #  ex.: start_time = -10 days
  start_time = "-1 day"
  # End time for event selection (UTC date time, time interval or None)
  #  ex.: end_time = 2021-08-24T00:00:00
  #  ex.: end_time = -1 hour
  end_time = None
  # Recheck period (string or None).
  # Use a string with the format "X unit" where X is an integer and unit is
  # one of the following: "days", "hours", "minutes", "seconds" (case insensitive
  # and plural or singular).
  #  ex.: recheck_period = 1 day
  #  ex.: recheck_period = 10 hours
  # This option is only used if end_time is None. Every time the program is run,
  # it will check if new events have been added or if existing events have been
  # updated during the recheck_period.
  recheck_period = None
  # Overwrite updated events if they changed during recheck_period (boolean).
  # If False, a new version of the event will be added to the database.
  # The eventid will be the same, but the event version ("ver" column) will be
  # incremented.
  # If True, the existing event will be updated with the new information, but the
  # extra fields will be kept.
  overwrite_updated_events = False
  # Keep a copy of the original event resource_id string in a separate column
  # named "raw_evid" (boolean).
  # Useful if the normalized ID isn’t recognized by the FDSN server when
  # downloading event details.
  # Default: False (only normalized evid kept).
  keep_raw_evid = False
  # Geographic box selection (decimal degrees or None)
  lat_min = None
  lat_max = None
  lon_min = None
  lon_max = None
  # Geographic circular selection.
  # Note, this will override the box selection if both are specified
  # Center of circular selection (decimal degrees or None)
  lat0 = None
  lon0 = None
  # Miminum and maximum radius of circular selection (decimal degrees or None)
  radius_min = None
  radius_max = None
  # Depth selection (km, positive down, or None)
  depth_min = None
  depth_max = None
  # Magnitude selection (magnitude units or None)
  mag_min = None
  mag_max = None
  # List of event types (or None)
  # ex.: event_type = earthquake
  event_type = None
  # List of event types to exclude (or None)
  # ex.: event_type_exclude = quarry blast
  event_type_exclude = None
  ## You can add as many additional criteria as you want by using a suffix
  ## (example "_1").
  ## Note that every omitted parameter will be considered as None (no limit).
  ## So, if you want for example the same time limits for the second set of
  ## criteria, you have to specify them again.
  ## Examples:
  # start_time_1 = 2022-01-01T00:00:00
  # end_time_1 = 2022-01-31T00:00:00
  # recheck_period_1 = 12 hours
  # lat_min_1 = 12.5
  # lat_max_1 = 18.5
  # lon_min_1 = -62.5
  # lon_max_1 = -58.5
  # depth_min_1 = None
  # depth_max_1 = None
  # mag_min_1 = None
  # mag_max_1 = None
  
  
  ## Selection criteria for downloading station metadata and waveforms
  # Minimum and maximum radius to select stations around the event epicenter
  # (decimal degrees, 1 degree is approximately 111 km)
  station_radius_min = 0
  station_radius_max = 1
  # Optional magnitude-dependent maximum station radius (in degrees).
  # Defines a candidate value for station_radius_max based on event magnitude;
  # the applied value is always limited to the range
  #   [station_radius_min, station_radius_max]
  # (see the two parameters above).
  #
  # Two formats are supported:
  #
  # 1) Magnitude bins (discrete binning, no interpolation):
  #    "mag1: radius1, mag2: radius2, ..."
  #    Uses the radius associated with the largest bin magnitude
  #    that is less than or equal to the event magnitude.
  #    Example:
  #      station_radius_max_mag = "2.0: 1.0, 3.0: 2.0, 4.0: 3.0"
  #      (an event with magnitude 2.7 uses a radius of 1.0 degrees)
  #
  # 2) Mathematical expression using variable "mag":
  #    Example:
  #      station_radius_max_mag = "2.0 * mag - 3.0"
  #
  # Note: You must use the string quotes (") for this parameter.
  station_radius_max_mag = None
  # Minimum interstation distance (in km) to select stations. If two stations
  # are closer than this distance, only one of them will be selected.
  interstation_distance_min = 0
  # Seconds before and after the origin time to download waveforms
  seconds_before_origin = 60
  seconds_after_origin = 600
  # Minimum duration (in seconds) to keep a waveform
  duration_min = 0
  # Channel codes to download. If set to None, all channels will be downloaded.
  # Supports multiple channel selection and wildcard patterns.
  # Example: To download channels starting with "HH" or "BH", use:
  #   selected_channel_codes = "HH?,BH?"
  # Note: You must use the string quotes (") to specify the pattern.
  channel_codes = None
  # Station codes to download. If set to None, all stations will be downloaded.
  # Supports multiple station selection and wildcard patterns.
  # Example: To download stations starting with "STA" or named "ABCD", use:
  #   station_codes = "STA?,ABCD"
  # Note: You must use the string quotes (") to specify the pattern.
  station_codes = None
  # Download waveforms only for stations with at least one P or S-wave arrival
  # in the catalog (i.e., from the event QuakeML file downloaded by
  # "seiscat fetch_details"). If True, the event QuakeML file must exist in
  # the event directory.
  picked_stations_only = False
  # Retain only high sampling rate channels when both high and low sampling rate
  # versions exist. If True, lower sampling rate channels will be discarded in
  # favor of higher sampling rate ones.
  # Example: If both HHZ and BHZ are available, only HHZ will be kept.
  prefer_high_sampling_rate = False