API Documentation

Project wide exceptions and warnings.

class lasif.exceptions.LASIFError[source]

Base exception class for LASIF.

class lasif.exceptions.LASIFNotFoundError[source]

Raised whenever something is not found inside the project.

class lasif.exceptions.LASIFWarning[source]

Base warning class for LASIF.

Contents:

An api to communicate directly with lasif functions without using the command line interface. Ideal interface for scripting.

copyright

Solvi Thrastarson (soelvi.thrastarson@erdw.ethz.ch), 2018

license

GNU General Public License, Version 3 (http://www.gnu.org/copyleft/gpl.html)

lasif.api.add_gcmt_events(lasif_root, count: int, min_mag: float, max_mag: float, min_dist: float, min_year: Optional[int] = None, max_year: Optional[int] = None, return_events: bool = False)[source]

Add events to the project.

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • count (int) – Nunber of events

  • min_mag (float) – Minimum magnitude

  • max_mag (float) – Maximum magnitude

  • min_dist (float) – Minimum distance between events in km

  • min_year (float, optional) – Year to start event search, defaults to None

  • max_year (float, optional) – Year to end event search, defaults to None

  • return_events (bool, optional) – If you want to return a list of the new events, defaults to False

lasif.api.add_spud_event(lasif_root, url: str)[source]

Adds events from the iris spud service, provided a link to the event

Parameters
lasif.api.calculate_adjoint_sources(lasif_root, iteration: str, window_set: str, weight_set: Optional[str] = None, events: Optional[Union[str, List[str]]] = None)[source]

Calculate adjoint sources for a given iteration

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • iteration (str) – name of iteration

  • window_set (str) – name of window set

  • weight_set (str, optional) – name of station weight set, defaults to None

  • events (Union[str, List[str]]) – Name of event or list of events. To get all events for the iteration, pass None, defaults to None

lasif.api.calculate_adjoint_sources_multiprocessing(lasif_root, iteration: str, window_set: str, weight_set: Optional[str] = None, events: Optional[Union[str, List[str]]] = None, num_processes: int = 16)[source]

Calculate adjoint sources for a given iteration This function uses multiprocessing for parallelization

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • iteration (str) – name of iteration

  • window_set (str) – name of window set

  • weight_set (str, optional) – name of station weight set, defaults to None

  • events (Union[str, List[str]]) – Name of event or list of events. To get all events for the iteration, pass None, defaults to None

  • num_processes (int) – The number of processes used in multiprocessing

lasif.api.calculate_validation_data_misfit(lasif_root, iteration: str, events: Optional[Union[str, List[str]]] = None)[source]

Calculates L2 full trace misfits for either a full iteration or a set of events within an iteration.

Returns a dictionary with misfits for each event as well as the total misfit

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • iteration (str, optional) – name of iteration to compute misfits for

  • events (Union[str, List[str]], optional) – An event or a list of events. To get all of them pass None, defaults to None

lasif.api.clean_up(lasif_root, clean_up_file: str, delete_outofbounds_events: bool = False)[source]

Clean up the lasif project. The required file can be created with the validate_data command.

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • clean_up_file (str) – path to clean-up file

  • delete_outofbounds_events (bool, optional) – Whether full event files should be deleted if the event is out of the domain, defaults to False.

lasif.api.compare_misfits(lasif_root, from_it: str, to_it: str, events: Optional[Union[str, List[str]]] = None, weight_set: Optional[str] = None, print_events: bool = False)[source]

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.

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • from_it (str) – evaluate misfit from this iteration

  • to_it (str) – to this iteration

  • events (Union[str, List[str]], optional) – An event or a list of events. To get all of them pass None, defaults to None

  • weight_set (str, optional) – Set of station and event weights, defaults to None

  • print_events (bool, optional) – compare misfits for each event, defaults to False

lasif.api.compute_station_weights(lasif_root, weight_set: str, events: Optional[Union[str, List[str]]] = None, iteration: Optional[str] = None)[source]

Compute weights for stations based on amount of neighbouring stations

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • weight_set (str) – name of weight set to compute into

  • events (Union[str, List[str]], optional) – An event or a list of events. To get all of them pass None, defaults to None

  • iteration (str, optional) – name of iteration to compute weights for, controls the events which are picked for computing weights for.

lasif.api.create_salvus_simulation(lasif_root: Union[str, object], event: str, iteration: str, mesh: Optional[Union[str, pathlib.Path, object]] = None, side_set: Optional[str] = None, type_of_simulation: str = 'forward')[source]

Create a Salvus simulation object based on simulation and salvus specific parameters specified in config file.

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root folder or the lasif communicator object

  • event (str) – Name of event

  • iteration (str) – Name of iteration

  • mesh (Union[str, pathlib.Path, object], optional) – Path to mesh or Salvus mesh object, if None it will use the domain file from config file, defaults to None

  • side_set (str, optional) – Name of side set on mesh to place receivers, defaults to None.

  • type_of_simulation (str, optional) – forward or adjoint, defaults to forward

Returns

Salvus simulation object

Return type

object

lasif.api.create_weight_set(lasif_root, weight_set: str)[source]

Create a new set of event and station weights

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • weight_set (str) – name of weight set

lasif.api.download_data(lasif_root, event_name: Optional[Union[str, List[str]]] = None, providers: Optional[List[str]] = None)[source]

Download available data for events

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • event_name (Union[str, List[str]], optional) – Name of event(s), if you want to pass all events, pass None, you can pass either an event or a list of events, defaults to None.

  • providers (List[str]) – A list of providers to download from, if nothing passed it will query all known providers that FDSN knows, defaults to None

lasif.api.event_info(lasif_root, event_name: str, verbose: bool = False)[source]

Print information about a single event

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • event_name (str) – Name of event

  • verbose (bool, optional) – Print station information as well, defaults to False

lasif.api.find_event_mesh(lasif_root, event: str)[source]

See if there is a version of the event mesh which has been constructed already but not moved to iteration folder. If there is no mesh there it will return False and correct path. Otherwise it returns true and the path.

Parameters
Returns

bool whether mesh exists and path to mesh

lasif.api.find_project_comm(folder)[source]

Will search upwards from the given folder until a folder containing a LASIF root structure is found. The absolute path to the root is returned.

Parameters

folder (Union[str, pathlib.Path, object]) – Path to folder where you want to search from

lasif.api.get_receivers(lasif_root, event: str, load_from_file: bool = False, write_to_file: bool = False)[source]

Get a list of receiver dictionaries which are compatible with Salvus. SalvusFlow can then use these dictionaries to place the receivers.

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – Path to project root

  • event (str) – Name of event which we want to find the receivers for

  • load_from_file (bool, optional) – If receivers are stored in a json file, defaults to False

  • write_to_file (bool, optional) – If list of receiver dictionaries should be written to file, defaults to False

lasif.api.get_simulation_mesh(lasif_root, event: str, iteration: str) → str[source]

In the multi mesh approach, each event has a unique mesh. This function returns the path of the correct mesh.

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – Path to project root

  • event (str) – Name of event

  • iteration (str) – Name of iteration

Returns

path to simulation mesh

Return type

str

lasif.api.get_source(lasif_root, event: str, iteration: str)[source]

Provide source information to give to Salvus

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – Path to project root

  • event (str) – Name of event which we want to find the source for

  • iteration (str) – Name of iteration

lasif.api.get_subset(lasif_root, events: List[str], count: int, existing_events: Optional[List[str]] = None)[source]

This function gets an optimally distributed subset of events from a larger group of events. The distribution is based on Mitchel’s best sampling algorithm. It’s possible to exclude events and have already picked events.

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – Path to project root

  • events (List[str]) – List of event names from which to choose from. These events must be known to LASIF.

  • count (int) – number of events to choose. (Size of subset)

  • existing_events (List[str]) – Events already in subset, They will be considered in spatial sampling, defaults to None

Returns

list of selected events, defaults to None

Return type

List[str], optional

lasif.api.init_project(project_path: Union[str, pathlib.Path])[source]

Create a new project

Parameters

project_path (Union[str, pathlib.Path]) – Path to project root directory. Can use absolute paths or relative paths from current working directory.

lasif.api.list_events(lasif_root, just_list: bool = True, iteration: Optional[str] = None, output: bool = True)[source]

Print a list of events in project

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • just_list (bool, optional) – Show only a plain list of events, if False it gives more information on the events, defaults to True

  • iteration (str, optional) – Show only events for specific iteration, defaults to None

  • output (bool, optional) – Do you want to output the list into a variable, defaults to True

lasif.api.list_iterations(lasif_root, output: bool = True)[source]

List iterations in project

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • output (bool, optional) – If the function should return the list, defaults to True

lasif.api.list_weight_sets(lasif_root)[source]

Print a list of all weight sets in the project.

Parameters

lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

lasif.api.open_gui(lasif_root)[source]

Open up the misfit gui

Parameters

lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

lasif.api.plot_all_rays(lasif_root, plot_stations: bool, iteration: Optional[str] = None, save: bool = True, intersection_override: Optional[bool] = None, inner_boundary: bool = False)[source]

Plot all the rays that are in the project or in a specific iteration. This is typically slower than the plot_raydensity function

Parameters

  • lasif_root (Union[pathlib.Path, str, object]) – Lasif root directory

  • plot_stations (bool) – True/False whether stations should be plotted

  • iteration (str, optional) – If you only want events from a certain iteration, if None is passed every event will be used, defaults to None

  • save (bool, optional) – Whether you want to save the figure, if False, it gets plotted and not saved, defaults to True

  • intersection_override (bool, optional) – boolean to require to have the same stations recording all events, i.e. the intersection of receiver sets. The intersection will consider two stations equal i.f.f. the station codes AND coordinates (LAT, LON, Z) are equal. If None is passed, the value use_only_intersection from the projects’ configuration file is used, defaults to None

lasif.api.plot_domain(lasif_root, save=False, inner_boundary=False)[source]

Plot the studied domain specified in config file

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory.

  • save (bool, optional) – save file, defaults to False

  • inner_boundary (bool, optional) – binary whether the inner boundary should be drawn Only works well for convex domains, defaults to False

lasif.api.plot_event(lasif_root, event_name: str, weight_set_name: Optional[str] = None, save: bool = False, intersection_override: Optional[bool] = None, inner_boundary: bool = False)[source]

Plot a single event including stations on a map. Events can be color coded based on their weight

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • event_name (str) – name of event to plot

  • weight_set_name (str, optional) – name of station weight set, defaults to None

  • save (bool, optional) – if figure should be saved, defaults to False

  • intersection_override (bool, optional) – boolean to require to have the same stations recording all events, i.e. the intersection of receiver sets. The intersection will consider two stations equal i.f.f. the station codes AND coordinates (LAT, LON, Z) are equal. If None is passed, the value use_only_intersection from the projects’ configuration file is used, defaults to None

  • inner_boundary (bool, optional) – binary whether the inner boundary should be drawn Only works well for convex domains, defaults to False

lasif.api.plot_events(lasif_root, type_of_plot: str = 'map', iteration: Optional[str] = None, save: bool = False, inner_boundary: bool = False)[source]

Plot a all events on the domain

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • type_of_plot (str, optional) – type of plot, options are ‘map’, ‘depth’ and ‘time’, defaults to ‘map’

  • iteration (str, optional) – plot all events of an iteration, defaults to None

  • save (bool, optional) – if figure should be saved, defaults to False

  • inner_boundary (bool, optional) – binary weather the inner boundary should be drawn Only works well for convex domains, defaults to False

lasif.api.plot_raydensity(lasif_root, plot_stations: bool, iteration: Optional[str] = None, save: bool = True, intersection_override: Optional[bool] = None)[source]

Plot a distribution of earthquakes and stations with great circle rays plotted underneath.

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – Lasif root directory

  • plot_stations (bool) – boolean argument whether stations should be plotted

  • iteration (str, optional) – If you only want events from a certain iteration, if None is passed every event will be used, defaults to None

  • save (bool, optional) – Whether you want to save the figure, if False, it gets plotted and not saved, defaults to True

  • intersection_override (bool, optional) – boolean to require to have the same stations recording all events, i.e. the intersection of receiver sets. The intersection will consider two stations equal i.f.f. the station codes AND coordinates (LAT, LON, Z) are equal. If None is passed, the value use_only_intersection from the projects’ configuration file is used, defaults to None

lasif.api.plot_station_misfits(lasif_root, event: str, iteration: str, save=False)[source]

Plot a map of a specific event where all the stations are colour coded by their respective misfit value. You need to compute adjoint sources for the respective iteration prior to making this plot. Keep in mind that station with no windows will not get plotted, these stations might be the ones with the largest misfits in reality

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – Lasif root directory or communicator object

  • event (str) – Name of event

  • iteration (str) – Name of iteration

  • save (bool, optional) – You want to save the plot?, defaults to False

lasif.api.plot_stf(lasif_root)[source]

Plot the source time function

Parameters

lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

lasif.api.plot_window_statistics(lasif_root, window_set: str, save: bool = False, events: Optional[Union[str, List[str]]] = None, iteration: Optional[str] = None)[source]

Plot some statistics related to windows in a specific set.

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • window_set (str) – name of window set

  • save (bool, optional) – Saves the plot in a file, defaults to False,

  • events (Union[str, List[str]], optional) – An event or a list of events. To get all of them pass None, defaults to None

  • iteration (str, optional) – Plot statistics related to events in a specific iteration , defaults to None

lasif.api.plot_windows(lasif_root, event_name: str, window_set: str, distance_bins: int = 500)[source]

Plot the selected windows for a specific event

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • event_name (str) – name of event

  • window_set (str) – name of window set

  • distance_bins (int) – number of bins on distance axis for combined plot

lasif.api.process_data(lasif_root, events: Optional[Union[str, List[str]]] = None, iteration: Optional[str] = None)[source]

Process recorded data

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • events (Union[str, List[str]], optional) – An event or a list of events. To get all of them pass None, defaults to None

  • iteration (str, optional) – Process data from events used in an iteration, defaults to None

lasif.api.project_info(lasif_root)[source]

Print a summary of the project

Parameters

lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

lasif.api.select_windows(lasif_root, iteration: str, window_set: str, events: Optional[Union[str, List[str]]] = None)[source]

Autoselect windows for a given iteration and event combination

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • iteration (str) – name of iteration

  • window_set (str) – name of window set

  • events (Union[str, List[str]], optional) – An event or a list of events. To get all of them pass None, defaults to None

lasif.api.select_windows_multiprocessing(lasif_root, iteration: str, window_set: str, events: Optional[Union[str, List[str]]] = None, num_processes: int = 16)[source]

Autoselect windows for a given iteration and event combination Uses Python’s multiprocessing for parallelization

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • iteration (str) – name of iteration

  • window_set (str) – name of window set

  • events (Union[str, List[str]], optional) – An event or a list of events. To get all of them pass None, defaults to None

  • num_processes (int) – The number of processes used in multiprocessing

lasif.api.set_up_iteration(lasif_root, iteration: str, events: Optional[Union[str, List[str]]] = None, event_specific: bool = False, remove_dirs: bool = False)[source]

Creates or removes directory structure for an iteration

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • iteration (str) – name of iteration

  • events (Union[str, List[str]], optional) – An event or a list of events. To get all of them pass None, defaults to None

  • event_specific (bool, optional) – If the inversion needs a specific model for each event, defaults to False

  • remove_dirs (bool, optional) – boolean value to remove dirs, defaults to False

lasif.api.submit_salvus_simulation(lasif_root: Union[str, object], simulations: Union[List[object], object]) → object[source]

Submit a Salvus simulation to the machine defined in config file with details specified in config file :param lasif_root: The Lasif communicator object or root file :type lasif_root: Union[str, pathlib.Path, object] :param simulations: Simulation object :type simulations: Union[List[object], object] :return: SalvusJob object or array of them :rtype: object

lasif.api.tutorial()[source]

Open the lasif tutorial in a web-browser.

lasif.api.update_catalog()[source]

Update GCMT catalog

lasif.api.validate_data(lasif_root, data_station_file_availability: bool = False, raypaths: bool = False, full: bool = False)[source]

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.

Parameters

  • lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory

  • data_station_file_availability (bool) – asserts that all stations have corresponding station files and all stations have waveforms, very slow.

  • raypaths (bool) – Assert that all raypaths are within the set boundaries. Very slow.

  • full (bool) – Run all validations

lasif.api.write_misfit(lasif_root, iteration, weight_set=None, window_set=None, events=None, include_stations=False)[source]

Write misfit for iteration :param lasif_root: path to lasif root directory :param iteration: name of iteration :param weight_set: name of weight set [optional] :param window_set: name of window set [optional] :param events: list of events [optional] :param include_stations: Write down station misfits? [optional]

lasif.api.write_stations_to_file(lasif_root)[source]

This function writes a csv file with station name and lat,lon locations

Parameters

lasif_root (Union[str, pathlib.Path, object]) – path to lasif root directory or communicator