overhaul file writing system plus general updates

docs/pysep.rst

@@ -153,62 +153,93 @@ class. See the PySEP docstring for input parameter types and definitions.
 -------------------------------------------------------------------------------
 
 
-Multiple Event Input
---------------------
+PySEP Outputs
+--------------
 
-To use the same configuration file with multiple events, you can use an event 
-file passed to PySEP through the command line.
+PySEP uses a default directory structure when saving files:
 
-When using this option, the event parameters inside the config file will be
-ignored, but all the other parameters will be used to gather data and metadata.
+* ``output_dir``: By default, PySEP writes all files to the User-defined
+  parameter ``output_dir``, which defaults to the current working directory.
+* ``event_tag``: Files are written into a sub-directory defined by the event
+  origin time, and Flinn-Engdahl region. For example:
+  ``2009-04-07T201255_SOUTHERN_ALASKA``
+* ``sac_subdir``: All waveform files are saved in a further sub-directory
+  (default: `SAC/`), to avoid cluttering up the output directory. Waveform
+  files are tagged by the `event_tag` and trace ID.
 
-Event input files should be text files where each row describes one event with 
-the following parameters as columns:
+Users can use the parameters ``write_files`` and ``plot_files`` to control
+exactly what files are produced during a PySEP (see `API documentation
+<autoapi/pysep/pysep/index.html#pysep.pysep.Pysep>`__ for details).
 
-.. ORIGIN_TIME LONGITUDE LATITUDE DEPTH[KM] MAGNITUDE
+By default, PySEP will write SAC files, StationXML, QuakeML and config files,
+and create a source-receiver map and record section.
 
-For an example event input file called 'event_input.txt', call structure is:
+Override Directory Names
+````````````````````````
 
-.. code:: bash
+In some cases it may be useful for Users to save files directly to their
+working directory, without all the automatically generated sub-directories.
 
-    pysep -c pysep_config.yaml -E event_input.txt
+* To ignore the automatically generated event tag, you can set the
+  ``overwrite_event_tag`` parameter as an empty string. Via the command line:
 
-.. note::
+  .. code:: bash
 
-    Multiple event input is only available for command line usage of PySEP.
-    We suggest using a for loop if you would like to script multiple event
-    input using PySEP
+      pysep -c pysep_config.yaml --overwrite_event_tag ''
 
+  or via scripting:
 
-Legacy Filenaming Schema
-------------------------
+  .. code:: python
 
-The new version of PySEP uses a file naming schema that is incompatible with
-previous versions, which may lead to problems in established workflows. 
+      sep = Pysep(overwrite_event_tag="")
 
-To honor the legacy naming schema of PySEP, simply use the `--legacy_naming`
-argument in the command line. This will change how the event tag is formatted,
-how the output directory is structured, and how the output SAC files are named.
+* To set your own event tag, use a string value
 
-.. code:: bash
+  .. code:: bash
 
-    pysep -c pysep_config.yaml --legacy_naming
+        pysep -c pysep_config.yaml --overwrite_event_tag event_abc
 
-Or with scripting
+* To ignore the SAC subdirectory and save waveform files directly in the
+  output directory, use the ``sac_subdir`` parameter, which should be input in
+  your YAML parameter file:
 
-.. code:: python
+  .. code:: yaml
 
-    sep = Pysep(legacy_naming=True, ...)
+      sac_subdir: ''
+
+  or via scripting
+
+  .. code:: python
+
+      sep = Pysep(sac_subdir="")  # or use a string value to define your own
+
+* `Example`: if a User only wants to save SAC waveforms for the rotated RTZ
+  component within their current working directory, ignoring all automatically
+  generated sub directories, all other written files and all plots:
+
+  .. code:: python
+
+      sep = Pysep(overwrite_event_tag="", sac_subdir="", write_files="sac_rtz",
+                  plot_files="")
 
 
-Output Filename Control
-```````````````````````
+Override Filenames
+``````````````````
+
+.. note::
+
+    The output SAC file names are hardcoded as trace IDs (with or without the
+    event tag). If additional control over file IDs is a required feature,
+    please open up a `GitHub issue <https://github.com/adjtomo/pysep/issues>`__
 
 The event tag used to name the output directory and written SAC files can be set
-manually by the user using the `--event_tag` argument. If not given, the tag
-will default to a string consisting of event origin time and Flinn-Engdahl 
-region (or just origin time if `--legacy_naming` is used). Other output files
-such as the config file and ObsPy objects can be set as in the following: 
+manually by the user using the ``overwrite_event_tag`` argument.
+
+Other output file names can also be changed from their default values, see the
+:meth:`write function <pysep.pysep.Pysep.write>` for write file options and
+arguments to use for changing file names.
+
+An example of this via the command line:
 
 .. code:: bash
 
@@ -228,15 +259,57 @@ Or with scripting
                 config_fid="event_abc.yaml", ...)
 
 
+Legacy Filenaming Schema
+````````````````````````
+
+The new version of PySEP uses a file naming schema that is incompatible with
+previous versions, which may lead to problems in established workflows.
+
+To honor the legacy naming schema of PySEP, simply use the ``legacy_naming``
+parameter. This will change how the event tag is formatted, how the output
+directory is structured, and how the output SAC files are named.
+
+.. code:: bash
+
+    pysep -c pysep_config.yaml --legacy_naming
+
+Or with scripting
+
+.. code:: python
+
+    sep = Pysep(legacy_naming=True, ...)
+
+
+Multiple Event Input
+--------------------
+
+To use the same configuration file with multiple events, you can use an event
+file passed to PySEP through the command line.
+
 .. note::
 
-    The output SAC file names are hardcoded and cannot be changed
-    by the user. If this is a required feature, please open up a GitHub issue,
-    and the developers will address this need.
+    Multiple event input is only available for command line usage of PySEP.
+    We suggest using a for loop if you would like to script multiple event
+    input using PySEP
+
+
+When using this option, the event parameters inside the config file will be
+ignored, but all the other parameters will be used to gather data and metadata.
+
+Event input files should be text files where each row describes one event with
+the following parameters as columns:
+
+.. ORIGIN_TIME LONGITUDE LATITUDE DEPTH[KM] MAGNITUDE
+
+For an example event input file called 'event_input.txt', call structure is:
+
+.. code:: bash
+
+    pysep -c pysep_config.yaml -E event_input.txt
 
 
 ObsPy Mass Downloader
-`````````````````````
+---------------------
 
 `ObsPy's Mass Download
 <https://docs.obspy.org/packages/autogen/obspy.clients.fdsn.mass_downloader.html>`__