Command Line Interface¶

The recommended way to interact with LASIF 2.0 projects is to use the API but the command line interface remains an option for anyone who prefers that. It consists of a number of subcommands grouped below the main lasif command. The general usage is quickly explained in this paragraph whilst the remainder of this sections explains all subcommands in greater detail.

The general help can be accessed with the lasif help command.

$ lasif help
####################################################################################################
    LASIF - Large Scale Seismic Inversion Framework  [Version 0.0.0-tar/zipball]
    http://krischer.github.io/LASIF
####################################################################################################

usage: lasif [--help] COMMAND [ARGS]

======== Data Acquisition Functions
                   add_gcmt_events: Selects and adds optimally distributed events from the GCMT catalog.
                    add_spud_event: Add an event from the IRIS SPUD webservice to the project.
...

To access the subcommand specific help append --help to the command.

$ lasif init_project --help
usage: lasif init_project [-h] [--ipdb] folder_path

Create a new project.

positional arguments:
  folder_path  where to create the project

optional arguments:
  -h, --help   show this help message and exit
  --ipdb       If true, a debugger will be launched upon encountering an
               exception. Requires ipdb.

Each command can have a number of positional arguments and some optional arguments. Positional arguments have to be given in the specified order while optional arguments can be passed if needed.

Note

All lasif commands work and use the correct project as long as they are executed somewhere inside a project’s folder structure. It will recursively search the parent directories until it finds a lasif_config.toml file. This will then be assumed to be the root folder of the project.

MPI¶

Some commands can be executed with MPI to speed up their execution. Don’t use too many cores as the problem quickly becomes I/O bounds. For example to run the preprocessing on 16 cores, do

$ mpirun -n 16 lasif process_data 1 GCMT_event_AZORES_ISLANDS

The following commands are MPI-enabled. Attempting to run any other command with MPI will result in an error.:

lasif calculate_adjoint_sources
lasif compare_misfits
lasif process_data
lasif select_windows

Command Documentation¶

In the following all subcommands are documented in detail. The commands are grouped by functionality.

Available Commands

Data Acquisition Functions
Event Management Functions
- lasif list_events
- lasif event_info
Iteration Management Functions
Misc Functions
- lasif shell
- lasif tutorial
Plotting Functions
Project Management Functions

Data Acquisition Functions ¶

Data Acquisition

These functions are used to acquire and archive different types of data usually from webservices.

lasif add_spud_event ¶

usage: lasif add_spud_event [-h] [--ipdb] url

Add an event from the IRIS SPUD webservice to the project.

Positional Arguments
`url`	any SPUD momenttensor URL
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.

lasif add_gcmt_events ¶

usage: lasif add_gcmt_events [-h] [--ipdb] [--min_year MIN_YEAR]
                                 [--max_year MAX_YEAR]
                                 count min_magnitude max_magnitude min_distance

Selects and adds optimally distributed events from the GCMT catalog.

Positional Arguments
`count`	maximum amount of events to add
`min_magnitude`	minimum magnitude off events to add
`max_magnitude`	maximum magnitude off events to add
`min_distance`	The minimum acceptable distance to the next closest event in km.
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`--min_year`	minimum year from which to add events
`--max_year`	maximum year from which to add events

lasif download_data ¶

usage: lasif download_data [-h] [--ipdb]
                               [--providers PROVIDERS [PROVIDERS ...]]
                               [event_name [event_name ...]]

Download waveform and station data for one or more events. Can be used to download data for all events in LASIF project.

Positional Arguments
`event_name`	name of the event. Possible to add more than one event separated by a space. If argument is left empty. data will be downloaded for all events
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`--providers`	FDSN providers to query. Will use all known ones if not set.

Event Management Functions ¶

Event Management

Function helping in organzing the earthquakes inside a LASIF project.

lasif list_events ¶

usage: lasif list_events [-h] [--ipdb] [--just_list] [--iteration ITERATION]

Print a list of all events in the project.

Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`--just_list`	Show only a list of eventswithout properties. Good for scripting bash.
`--iteration`	Show only events related to a specific iteration

lasif event_info ¶

usage: lasif event_info [-h] [--ipdb] [-v] event_name

Print information about a single event.

Positional Arguments
`event_name`	name of the event
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`-v`	Verbose. Print all contained events.

Iteration Management Functions ¶

Iteration Management

Functions dealing with one or more iterations inside a LASIF project.

lasif submit_job ¶

usage: lasif submit_job [-h] [--ipdb]
                            iteration_name ranks wall_time_in_seconds
                            simulation_type site [event [event ...]]

EXPERIMENTAL: Submits event(s) to daint with salvus-flow. NO QA

Requires all input_files and salvus-flow to be installed and configured.

Positional Arguments
`iteration_name`	name of the iteration
`ranks`	amount of ranks
`wall_time_in_seconds`	wall time
`simulation_type`	forward, step_length, adjoint
`site`	Computer to submit the job to
`event`	If you only want to submit selected events. You can input more than one separated by a space. If none is specified, all will be taken
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.

lasif retrieve_output ¶

usage: lasif retrieve_output [-h] [--ipdb]
                                 iteration_name simulation_type site
                                 [event [event ...]]

EXPERIMENTAL: Retrieves output from simulation, No QA.

Positional Arguments
`iteration_name`	name of the iteration
`simulation_type`	forward, step_length, adjoint
`site`	Computer to get output from
`event`	names of events you want to retrieve output from. If more than one, separate with space. If none specified all will be used.
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.

lasif generate_input_files ¶

usage: lasif generate_input_files [-h] [--ipdb]
                                      [--weight_set_name WEIGHT_SET_NAME]
                                      [--prev_iter PREV_ITER]
                                      iteration_name [events [events ...]]
                                      simulation_type

Generate input files for the forward simulation of the waveform solver.

Positional Arguments
`iteration_name`	name of the iteration
`events`	One or more events. If none given, all will be done.
`simulation_type`	forward, step_length, adjoint
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`--weight_set_name`	Set of station and event weights,used to scale the adjoint sources
`--prev_iter`	Optionally specify a previous iterationto use input files_from, only updatesthe mesh file.

lasif calculate_adjoint_sources ¶

This function can be used with MPI

usage: lasif calculate_adjoint_sources [-h] [--ipdb] [--weight_set WEIGHT_SET]
                                           iteration_name window_set_name
                                           [events [events ...]]

Calculates adjoint sources for a given iteration.

Positional Arguments
`iteration_name`	name of the iteration
`window_set_name`	name of the window_set
`events`	One or more events. If none given,all will be done.
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`--weight_set`	name of station weight set

lasif select_windows ¶

This function can be used with MPI

usage: lasif select_windows [-h] [--ipdb]
                                iteration window_set_name [events [events ...]]

Autoselect windows for a given event and iteration combination.

This function works with MPI. Don’t use too many cores, I/O quickly becomes the limiting factor. It also works without MPI but then only one core actually does any work.

Positional Arguments
`iteration`	name of the iteration
`window_set_name`	name of the window_set
`events`	One or more events. If none given, all will be done.
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.

lasif gui ¶

usage: lasif gui [-h] [--ipdb]

Launch the misfit GUI.

Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.

lasif create_weight_set ¶

usage: lasif create_weight_set [-h] [--ipdb] weight_set_name

Create a new set of event and station weights.

Positional Arguments
`weight_set_name`	name of the weight set, i.e. “A”
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.

lasif compute_station_weights ¶

usage: lasif compute_station_weights [-h] [--ipdb] [--iteration ITERATION]
                                         weight_set_name
                                         [event_name [event_name ...]]

Compute weights for stations. Useful when distribution is uneven. Weights are calculated for each event. This may take a while if you have many stations.

Positional Arguments
`weight_set_name`	Pick a name for the weight set. If the weightset already exists, it willoverwrite
`event_name`	name of event. If none is specified weights willbe calculated for all. Also possible to specifymore than one separated by a space
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`--iteration`	If you only want to do this for the events specified for an iteration

lasif get_weighting_bins ¶

usage: lasif get_weighting_bins [-h] [--ipdb] [--iteration ITERATION]
                                    window_set_name [event_name [event_name ...]]

Compute median envelopes for the observed data in certain station bins. The binning is based on event-station distances.

Positional Arguments
`window_set_name`	Name of window set
`event_name`	Name of event
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`--iteration`	Take all eventsused in a specificiteration.

lasif set_up_iteration ¶

usage: lasif set_up_iteration [-h] [--ipdb] [--remove_dirs]
                                  iteration_name [events [events ...]]

Creates or removes directory structure for an iteration.

Positional Arguments
`iteration_name`	name of the iteration, i.e. “1”
`events`	If you only want to submit selected events. You can input more than one separated by a space. If none is specified, all will be taken
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`--remove_dirs`	Removes all directories related to the specified iteration.

lasif write_misfit ¶

usage: lasif write_misfit [-h] [--ipdb] [--weight_set_name WEIGHT_SET_NAME]
                              [--window_set_name WINDOW_SET_NAME]
                              iteration_name

Positional Arguments
`iteration_name`	current iteration
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`--weight_set_name`	Set of station and event weights
`--window_set_name`	name of the window set

lasif list_iterations ¶

usage: lasif list_iterations [-h] [--ipdb]

Creates directory structure for a new iteration.

Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.

lasif compare_misfits ¶

This function can be used with MPI

usage: lasif compare_misfits [-h] [--ipdb] [--weight_set_name WEIGHT_SET_NAME]
                                 [--print_events]
                                 from_iteration to_iteration [events [events ...]]

Compares the total misfit between two iterations.

Total misfit is used regardless of the similarity of the picked windows from each iteration. This might skew the results but should give a good idea unless the windows change excessively between iterations.

If windows are weighted in the calculation of the adjoint sources. That should translate into the calculated misfit value.

Positional Arguments
`from_iteration`	past iteration
`to_iteration`	current iteration
`events`	One or more events. If none given, all will be done.
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`--weight_set_name`	Set of station and event weights
`--print_events`	compare misfits for each event

lasif list_weight_sets ¶

usage: lasif list_weight_sets [-h] [--ipdb]

Print a list of all weight sets in the project.

Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.

lasif process_data ¶

This function can be used with MPI

usage: lasif process_data [-h] [--ipdb] [--iteration ITERATION]
                              [events [events ...]]

Launch data processing.

This function works with MPI. Don’t use too many cores, I/O quickly becomes the limiting factor. It also works without MPI but then only one core actually does any work.

Positional Arguments
`events`	One or more events. If none given, all will be done.
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`--iteration`	Take all events used in iteration

Misc Functions ¶

Misc

All functions that do not fit in one of the other categories.

lasif shell ¶

usage: lasif shell [-h] [--ipdb]

Drops you into a shell with an active communicator instance.

Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.

lasif tutorial ¶

usage: lasif tutorial [-h] [--ipdb]

Open the tutorial in a webbrowser.

Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.

Plotting Functions ¶

Plotting

Functions producing pictures.

lasif plot_domain ¶

usage: lasif plot_domain [-h] [--ipdb] [--save]

Plot the project’s domain on a map.

Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`--save`	Save the plot in a file

lasif plot_event ¶

usage: lasif plot_event [-h] [--ipdb] [--save] [--force_intersect]
                            [--force_no_intersect]
                            [--weight_set_name WEIGHT_SET_NAME]
                            event_name

Plot a single event including stations on a map.

Positional Arguments
`event_name`	name of the event to plot
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`--save`	Saves the plot in a file
`--force_intersect`	Force to plot only stations that recorded durng all events in the project, regardless of settings.
`--force_no_intersect`	Force to plot all stations that recorded during events, even if they are not present for all events, regardless of settings.
`--weight_set_name`	for stations to be color coded as a function of their respective weights

lasif plot_events ¶

usage: lasif plot_events [-h] [--ipdb] [--type {map,depth,time}]
                             [--iteration ITERATION] [--save]

Plot all events. This might need an extension to iterations.

type can be one of:

map (default) - a map view of the events
depth - a depth distribution histogram
time - a time distribution histogram

Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`--type {map (Default), depth, time}`	the type of plot. `map`: beachballs on a map, `depth`: depth distribution histogram, `time`: time distribution histogram
`--iteration`	Plot all events for an iteration
`--save`	Saves the plot in a file

lasif plot_raydensity ¶

usage: lasif plot_raydensity [-h] [--ipdb] [--iteration ITERATION]
                                 [--plot_stations]

Plot a binned raycoverage plot for all events.

Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`--iteration`	Only plot data from a specific iteration
`--plot_stations`	also plot the stations

lasif plot_section ¶

usage: lasif plot_section [-h] [--ipdb] [--num_bins NUM_BINS]
                              [--traces_per_bin TRACES_PER_BIN]
                              event_name

Plot a binned section plot of the processed data for an event.

Positional Arguments
`event_name`	name of the event to plot
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`--num_bins`	number of bins to be used for binning the event-station offsets
`--traces_per_bin`	number of traces per bin

lasif plot_stf ¶

usage: lasif plot_stf [-h] [--ipdb] [--unfiltered]

Plot the source time function for one iteration.

Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`--unfiltered`	Add this tag if you want to plot an unfiltered STF

lasif plot_window_statistics ¶

usage: lasif plot_window_statistics [-h] [--ipdb] [--save]
                                        [--iteration ITERATION]
                                        window_set_name [events [events ...]]

Plot the selected windows.

Positional Arguments
`window_set_name`	name of the window set
`events`	One or more events. If none given, all will be done.
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`--save`	Saves the plot in a file
`--iteration`	Take all events used in iteration

lasif plot_windows ¶

usage: lasif plot_windows [-h] [--ipdb] [--distance_bins DISTANCE_BINS]
                              event_name window_set_name

Plot the selected windows.

Positional Arguments
`event_name`	name of the event
`window_set_name`	name of the window set
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`--distance_bins`	The number of bins on the distance axis for the combined plot.

Project Management Functions ¶

Project Management

Functions dealing with LASIF projects as a whole.

lasif info ¶

usage: lasif info [-h] [--ipdb]

Print a summary of the project.

Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.

lasif init_project ¶

usage: lasif init_project [-h] [--ipdb] folder_path

Create a new project.

Positional Arguments
`folder_path`	where to create the project
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.

lasif validate_data ¶

usage: lasif validate_data [-h] [--ipdb]
                               [--data_and_station_file_availability] [--raypaths]
                               [--full]

Validate the data currently in the project.

This commands walks through all available data and checks it for validity. It furthermore does some sanity checks to detect common problems. These should be fixed.

By default is only checks some things. A full check is recommended but potentially takes a very long time.

Things the command does:

Event files:

Validate against QuakeML 1.2 scheme.
Make sure they contain at least one origin, magnitude and focal mechanism object.
Check for duplicate ids amongst all QuakeML files.
Some simply sanity checks so that the event depth is reasonable and the moment tensor values as well. This is rather fragile and mainly intended to detect values specified in wrong units.

Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.
`--data_and_station_file_availability`	asserts that all stations have corresponding station files and all stations have waveforms. Very slow.
`--raypaths`	assert that all raypaths are within the set boundaries. Very slow.
`--full`	run all validations.

lasif clean_up ¶

usage: lasif clean_up [-h] [--ipdb] clean_up_file

Clean up the LASIF project.

The required file can be created with lasif validate_data command.

Positional Arguments
`clean_up_file`	path of clean-up file
Optional Arguments
`-h`, `--help`	show this help message and exit
`--ipdb`	If true, a debugger will be launched upon encountering an exception. Requires ipdb.