quake-io

PyPI Downloads PyPI Version Commits since latest release

QuakeIO is a library of utilities for parsing and processing ground motion files. All data is serialized into a standardized JSON representation with a strictly defined schema. Interfaces are provided for Python, Matlab, and the command line. The following table summarizes the file formats which are currently supported:

Format Read Write Reference Data Type
[quakeio.]json ☑ ☑ schema any
csmip.v2 ☑ ☐ CSMIP C/S
csmip.zip ☑ ☐ E/R/C/S
eqsig ☑ ☑ eqsig
opensees ☐ ☑
PEER.NGA ☑ ☐

Design

Ground motion data is represented by compositions of the following data types/containers:

  1. QuakeSeries is an array-like data type which contains a single time series, and associated metadata like peak values and units. All data contained by this type is generally closely related to a single physical quantity or measurement. An example of a file format which parses to this type is the PEER NGA .AT2 file.
  2. QuakeComponent is a collection of QuakeSeries types which generally represents time series data (e.g. acceleration, velocity, displacement) which were collected in a single direction. An example of a file format that parses into this type is the CSMIP Volume 2 (.V2) spec.
  3. QuakeMotion is a collection of QuakeComponent types which all pertain to a single shared spatial location. The data contained by this type is generally free of any spatial variation.
  4. QuakeCollection is a collection of QuakeMotion types, often corresponding to a single site. An example of a file format that parses into this type is the CSMIP processed archive (.zip).

The core functionality of the library is exposed by the quakeio.read(filename, format=None) function. This function will return an object either of type (1), (2) or (3), depending on the format of the file that was parsed. For example, the return value of read when parsing a PEER NGA file (file extension .AT2), is a QuakeSeries with acceleration data. When parsing a CSMIP Volume 2 file the return is a QuakeComponent containing QuakeSeries instances for acceleration, velocity and displacement values, and when parsing a zip archive of such files, a QuakeCollection is returned.

When used via the Python library, these types are overloaded with mathematical operations allowing for concise and expressive post-processing. For example, given two QuakeMotion objects top and bot, representing the motion at the top and bottom of a bridge column, respectively, their relative motion is simply computed as follows:

>>> top - bot
QuakeMotion("Hayward")

The resulting QuakeMotion has acceleration, velocity and displacement components all equal to the respective difference between those of top and bot. These operations are further developed in Example:Hayward

Tooling and Standards

Verification, Validation, and Continuous Integration

The tests/ directory of the source code tree contains a suite of integration tests. An automated continuous integration workflow ensures that these tests are executed everytime that a change to the source code is pushed back to the upstream repository.

Command Line Interface

usage: quakeio [MODE] [OPTIONS] [FILE]
Options:
 
-f/--from FORMAT
-t/--to   FORMAT

MATLAB Interface

The Matlab interface utilizes the standard jsondecode function internally to read a JSON file and build a struct with fields corresponding to the Quake schemas.

Motion = quakeIO.read('csmip.zip')
Back to top