Initial Setup

The initial setup includes two steps: Project setup, and STREC setup.

New in version 2.1

The use of projects is optional. If you do not wish to use projects, you need to specify the confdir and datadir command line arguments when calling the gmrecords command.

Project setup

In order to simplify the command line interface, the gmrecords command makes use of “projects”. You can have many projects configured on your system, and a project can have data from many events. A project is essentially a way to encapsulate the configuration and data directories so that they do not need to be specified as command line arguments.

There are two different types of configuration for projects:

directory projects Directory projects work by checking the current working directory for a projects configuration file that holds the data and configuration info. Thus, in order to use the projects, you have to be in that specific directory. Whenever you are in a directory with a projects configuration, those projects are available; system-level projects are not available.

system-level projects System-level projects work by checking the user’s home directory for a project configuration file (~/.gmprocess/projects.conf) that can hold many different configured projects. When you use system-level projects, the projects are available from any directory on your system that does not contain a local projects configuration.

Attention

See the Configuration File section for more information on how configuration options work.

When you create either type of projects configuration, you will be prompted to include your name and email. This information is used for the data provenance. This facilitates reproducibility and giving credit to people processing data. If you do not wish to share your personal information, we recommend using an institution or project name.

To create a directory projects configuration, use the gmrecords init subcommand in the directory where you would like to host projects.

$ gmrecords init
Please enter a project title: [default]
Please enter the conf: [./conf]
Please enter the data: [./data]
Please enter your name and email. This information will be added
to the config file and reported in the provenance of the data
processed in this project.
	Name: Jane
	Email address: jane@mail.org

Created Project: default **Current Project**
	Conf Path: /Users/jane/tmp/gmprocess2/conf
	Data Path: /Users/jane/tmp/gmprocess2/data

The projects subcommand is used for managing system-level projects. The arguments are

usage: gmrecords projects [-h] [-l] [-s <name>] [-c] [-d <name>]
                          [-r <old> <new>] [--set-conf <name> <path>]
                          [--set-data <name> <path>]

options:
  -h, --help            show this help message and exit
  -l, --list            List all configured gmrecords projects.
  -s <name>, --switch <name>
                        Switch from current project to <name>.
  -c, --create          Create a project and switch to it.
  -d <name>, --delete <name>
                        Delete existing project <name>.
  -r <old> <new>, --rename <old> <new>
                        Rename project <old> to <new>.
  --set-conf <name> <path>
                        Set the conf path to <path> for project <name>.
  --set-data <name> <path>
                        Set the data path to <path> for project <name>.

    In order to simplify the command line interface, the gmrecords command makes use of
    "projects". You can have many projects configured on your system, and a project can
    have data from many events. A project is essentially a way to encapsulate the
    configuration and data directories so that they do not need to be specified as
    command line arguments.

    `gmrecords` first checks the current directory for the presence of
    `./.gmprocess/projects.conf` (this is called a "local" or "directory" project); if
    that is not found then it looks for the presence of `~/.gmprocess/projects.conf`
    (this is called a "system" level project).

    Within the `projects.conf` file, the key `project` indicates which the currently
    selected project. Multiple projects can be included in a `projects.conf` file.

    The project name is then stored as a key at the top level, which itself has keys
    `data_path` and `conf_path`. The `data_path` points to the directory where data
    is stored, and organized at the top level by directories named by event id. The
    `conf_path` points to the directory that holds configuration options in YML files.

The Command Line Interface tutorial provides an example of how to create system-level projects.

STREC setup

STREC is the code for getting seismotectonic information about an earthquake. This is used, for example, to select which ground motion model is appropriate. It is installed as a dependency, but the following command needs to be run to to set up the config files and download relevant data:

strec_cfg update [--datafolder /PATH/TO/STREC_DATA_DIR] --gcmt

Note that /PATH/TO/STREC_DATA_DIR can be any directory on your system that you prefer. It will be used for storing the data that STREC uses.