pysep.utils.io ============== .. py:module:: pysep.utils.io .. autoapi-nested-parse:: Read utilities for Pysep Functions --------- .. autoapisummary:: pysep.utils.io.read_yaml pysep.utils.io.read_sem pysep.utils.io.read_events_plus pysep.utils.io.read_specfem3d_cmtsolution_cartesian pysep.utils.io.read_specfem2d_source pysep.utils.io.read_forcesolution pysep.utils.io._get_resource_id pysep.utils.io.read_stations pysep.utils.io.read_event_file pysep.utils.io.read_asdfdataset pysep.utils.io.write_sem pysep.utils.io.write_pysep_station_file pysep.utils.io.write_stations_file pysep.utils.io.write_cat_to_event_list Module Contents --------------- .. py:function:: read_yaml(fid) Read a YAML file and return a dictionary :type fid: str :param fid: YAML file to read from :rtype: dict :return: YAML keys and variables in a dictionary .. py:function:: read_sem(fid, origintime='1970-01-01T00:00:00', source=None, stations=None, location='', precision=4, source_format='CMTSOLUTION') Specfem3D outputs seismograms to ASCII (.sem? or .sem.ascii) files. Converts SPECFEM synthetics into ObsPy Stream objects with the correct header information. If `source` and `stations` files are also provided, PySEP will write appropriate SAC headers to the underlying data. :type fid: str :param fid: path of the given ascii file :type origintime: obspy.UTCDateTime :param origintime: UTCDatetime object for the origintime of the event. If None given, defaults to dummy value of '1970-01-01T00:00:00' :type source: str :param source: optional SPECFEM source file (e.g., CMTSOLUTION, SOURCE) defining the event which generated the synthetics. Used to grab event information and append as SAC headers to the ObsPy Stream :type stations: str :param stations: optional STATIONS file defining the station locations for the SPECFEM generated synthetics, used to generate SAC headers :type location: str :param location: location value for a given station/component :type precision: int :param precision: dt precision determined by differencing two adjancent time steps in the underlying ascii text file. :rtype st: obspy.Stream.stream :return st: stream containing header and data info taken from ascii file .. py:function:: read_events_plus(fid, format, **kwargs) Addition to the base ObsPy.read_events() function that, in addition to the acceptable formats read by ObsPy, can also read the following: * SPECFEM2D SOURCE * SPECFEM3D/3D_GLOBE FORCESOLUTION * SPECFEM3D/3D_GLOBE CMTSOLUTION (both geographic and non-geographic) See the following link for acceptable ObsPy formats: See the following link for acceptable ObsPy formats: https://docs.obspy.org/packages/autogen/obspy.core.event.read_events.html :type fid: str :param fid: full path to the event file to be read :type format: str :param format: Expected format of the file (case-insensitive), available are - SOURCE - FORCESOLUTION - CMTSOLUTION - any of ObsPy's accepted arguments for ObsPy.read_events() :rtype: obspy.core.catalog.Catalog :return: Catalog which should only contain one event, read from the `fid` for the given `fmt` (format) .. py:function:: read_specfem3d_cmtsolution_cartesian(path_to_cmtsolution) Create a barebones ObsPy Event object from a SPECFEM3D CMTSOLUTION file with coordinates defined in cartesian. Required because ObsPy read_events() will throw a ValueError when CMTSOLUTIONS do not have geographically defined coordinates. .. py:function:: read_specfem2d_source(path_to_source, origin_time='1970-01-01T00:00:00') Create a barebones ObsPy Event object from a SPECFEM2D Source file, which only contains information required by Pyatoa. Only requires access to: event.preferred_origin(), event.preferred_magnitude() and event.preferred_moment_tensor(). Moment tensor is wrapped in try-except so we only need origin and magnitude. Modified from: https://docs.obspy.org/master/_modules/obspy/io/cmtsolution/ core.html#_internal_read_cmtsolution .. note:: Source files do not provide origin times so we just provide an arbitrary value but allow user to set time .. py:function:: read_forcesolution(path_to_forcesolution, origin_time='2000-01-01T00:00:00') Create a barebones Source object from a FORCESOLUTION Source file, which mimics the behavior of the more complex ObsPy Event object and can be used in the same way as an Event object. .. note:: Designed to read FORCESOLUTION files from SPECFEM3D/3D_GLOBE, which all have slightly different formats/keys :type path_to_forcesolution: str :param path_to_forcesolution: path to the FORCESOLUTION file :type origin_time: str :param origin_time: FORCESOLUTION files do not natively contain any information on origin time, which is required by ObsPy Event objects. The User can provide this information if it is important, or a default value of 2000-01-01T00:00:00 will be provided as a dummy variable to keep ObsPy happy :rtype: obspy.core.event.Event :return: Barebones ObsPy Event object which contains hypocentral location of FORCE, and the origin time defined by `origin_time` :raises KeyError: if the minimum required keys are not found in the file defined by `path_to_source` .. py:function:: _get_resource_id(name, res_type, tag=None) Helper function to create consistent resource ids, from ObsPy. Used to create resource ID's when generating Event objects .. py:function:: read_stations(path_to_stations) Convert a SPECFEM STATIONS file into an ObsPy Inventory object. Specfem3D STATION files contain no channel or location information, so the inventory can only go down to the station level. .. note:: This assumes a row structure for the station file is STA, NET, LAT [deg], LON [deg], ELEVATION [m], BURIAL [m] :type path_to_stations: str :param path_to_stations: the path to the STATIONS file that is associated with the Specfem3D DATA directory :rtype: obspy.core.inventory.Inventory :return: a station-level Inventory object :raises ValueError: if latitude and longitude values are not in geographic coordinates (i.e., in cartesian coordinates). Thrown by the init of the Station class. .. py:function:: read_event_file(fid) Read an event input file which is just a text file that should contain information on different events and their hypocenters :type fid: str :param fid: event input file :rtype: list of dict :return: parsed in event information .. py:function:: read_asdfdataset(path, evaluation) Read an ASDFDataSet created by a SeisFlows Pyaflowa inversion run. The dataset should contain observed and synthetic waveforms, and optionally contains misfit windows. Will return Streams with SAC headers .. note:: This function makes assumptions about the PyASDF data structure which is defined by the external package Pyatoa. If Pyatoa changes that structure, this function will break. :type path: str :param path: Path to the ASDF dataset to be read :type evaluation: str :param evaluation: evaluation to take synthetics from. These are saved following a format specified by Pyatoa, but usually follow the form iteration/step_count, e.g., i01s00 gives iteration 1, step count 0. Take a look at the waveform tags in `ASDFDataSet.waveforms[]` for tags following the 'synthetic_' prefix .. py:function:: write_sem(st, unit, path='./', time_offset=0) Write an ObsPy Stream in the two-column ASCII format that Specfem uses :type st: obspy.core.stream.Stream :param st: stream containing synthetic data to be written :type unit: str :param unit: the units of the synthetic data, used for file extension, must be 'd', 'v', 'a' for displacement, velocity, acceleration, resp. :type path: str :param path: path to save data to, defaults to cwd :type time_offset: float :param time_offset: optional argument to offset the time array. Sign matters e.g. time_offset=-20 means t0=-20 .. py:function:: write_pysep_station_file(inv, event, fid='./station_list.txt', order_station_list_by=None) Write a list of station codes, distances, etc. useful for understanding characterization of all collected stations :type event: obspy.core.event.Event :param event: optional user-provided event object which will force a skip over QuakeML/event searching :type inv: obspy.core.inventory.Inventory :param inv: optional user-provided inventory object which will force a skip over StationXML/inventory searching :type fid: str :param fid: name of the file to write to. defaults to ./station_list.txt :type order_station_list_by: str :param order_station_list_by: how to order the stations written to file. Available are: network, station, latitude, longitude, elevation, burial. If not given, order is determined by the internal sorting of the input Inventory .. py:function:: write_stations_file(inv, fid='./STATIONS', order_by=None, use_elevation=False, burials=None) Write a SPECFEM STATIONS file given an ObsPy inventory object .. note:: If topography is implemented in your mesh, elevation values should be set to 0 which means 'surface' in SPECFEM. .. note:: burial information is not contained in the ObsPy inventory so it is always set to a constant value, which can be given as input. default 0 :type inv: obspy.core.inventory.Inventory :param inv: Inventory object with station locations to write :type fid: str :param fid: path and file id to save the STATIONS file to. :type order_by: str :param order_by: how to order the stations written to file. Available are: network, station, latitude, longitude, elevation, burial. If not given, order is determined by the internal sorting of the input Inventory :type use_elevation: bool :param use_elevation: if True, sets the actual elevation value from the inventory. if False, sets elevation to 0. :type burials: list of float :param burials: If the User has burial information they want to be used as the last column. Length of `burials` must match the number of stations in the inventory when traversing by network and station .. py:function:: write_cat_to_event_list(cat, fid_out='event_input.txt') Writes out an event Catalog (ObsPy object) information to an ASCII file that PySEP can use for collecting data. The format of the output file is ORIGIN_TIME LONGITUDE LATITUDE DEPTH[KM] MAGNITUDE :type cat: obspy.core.catalog.Catalog :param cat: Catalog of events to write out :type fid_out: str :param fid_out: name of the output text file to be written. Defaults to 'event_input.txt'