09. Azimuthal Data

Introduction

Usually, HVSR data is acquired using a three-component seismometer with geophones oriented orthogonally in three direction: one is oriented in the vertical (or "Z") direction, one is oriented East-West (usually called the "East" or "E" component), and one is oriented North-South (the "North" or "N" component).

Before the Horizontal power spectral density values are divided by the Vertical power spectral density values, the horizontal components are often combined using one of any number of methods (see the method parameter of the sprit.process_hvsr() function, for examples of different ways to combine the horizontal components).

One way to combine the horizontal components while also extracting more information about the directionality of strength of resonance of the fundamental frequency is to perform azimuthal calculations on the two horizontal components to derive a directional component. This process both combines the horizontal components so that we can perform a simple H/V analysis, and also provides useful information on the directional strength of the data.

The primary calculation of the azimuthal data has been adapted from methods specified in the hvsrpy library using the following code:

# hasMask is an indicator of whether the data is masked (i.e., gappy)
# nData is the data from the N-component trace of the main data stream
# eData is the data from the E-component trace of the main data stream
# az_rad is the azimuth angle in radians

import numpy as np
...
if True in hasMask:
    radial_comp_data = np.ma.array(np.add(nData * np.cos(az_rad), eData * np.sin(az_angle_rad)), mask=list(map(operator.and_, nMask, eMask)))
else:
    radial_comp_data = np.add(nData * np.cos(az_rad), eData * np.sin(az_rad))
...

This data is then added as a "radial" trace of the data with an ("R") component, and a location code noting the azimuth angle (in degrees). The azimuth angle (in degrees and radians) is also specified in the stats/metadata of the trace.

sprit.calculate_azimuth()

Azimuthal data is computed in SpRIT using the calculate_azimuth() function.

This can be done for a single azimuth (in the future, this single azimuth there will be an option to consider this as the combined "H" value) or multiple azimuths (at x degree interval, for example. This is the default behavior). If multiple azimuths are calculated, these can also be interpolated for visualization purposes using sprit.plot_azimuth() to show the amplitude of the H/V peak at all azimuths.

From the API documentation, the parameters for this function are:

• hvsr_data Input HVSR
  • Data with at least input_params() and fetch_data() performed.
• azimuth_type (Default='multiple')
  • What type of azimuthal measurement to make, by default ‘multiple’. If ‘multiple’ (or {‘multi’, ‘mult’, ‘m’}), will take a measurement at each angular step of azimuth_angle of unit azimuth_unit. If ‘single’ (or {‘sing’, ‘s’}), will take a single azimuthal measurement at angle specified in azimuth_angle.
• azimuth_angle (Default = 30)
  • If azimuth_type='multiple', this is the angular step (in unit azimuth_unit) of each of the azimuthal measurements. If azimuth_type='single' this is the angle (in unit azimuth_unit) of the single calculated azimuthal measruement. By default 30.
• azimuth_unit (Default='degrees')
  • Angular unit used to specify azimuth_angle parameter. By default ‘degrees’. If ‘degrees’ (or {‘deg’, ‘d’}), will use degrees. If ‘radians’ (or {‘rad’, ‘r’}), will use radians.
• show_az_plot (Default=False)
  • Whether to show azimuthal plot, by default False.
• verbose (Default=False)
  • Whether to print terminal output, by default False

Calculate azimuth during sprit.run()

During sprit.run(), the default azimuthal calculations (see below) will be performed if the azimuthal_calculation argument is set to True:

sprit.run('sample1', azimuthal_calculation=True)

The calculate_azimuth() function can also be called if any of the parameters are set within the sprit.run() call. For example, the following will trigger the calculate_azimuth() function to be called with default values for all parameters, except azimuth_angle, which will be set to 45 (degrees in this case):

sprit.run('sample2', azimuth_angle=45)

Vizualization

Azimuthal data can be visualized in various ways natively in the sprit pacakge.

plot_azimuth()

There is a dedicated function sprit.plot_azimuth() specifically for plotting azimuthal data. The parameters for this function are:

• hvsr_data

  • An HVSRData or HVSRBatch object that has gone through the sprit.process_hvsr() step of processing and which has azimuthal data.

• show_azimuth_peaks (Default = False)

  • Whether to display the peak value at each azimuth calculated on the chart, by default False

• interpolate_azimuths (Default = True)

  • Whether to interpolate the azimuth data to get a smoother plot. This is just for visualization and does not change underlying data. It takes a lot of time to process the data, but interpolation for vizualization can be computed fairly fast. By default True.

• show_azimuth_grid (Default = False)

  • Whether to display the grid on the chart, by default False

Example

plot_hvsr()

When sprit.plot_hvsr() is called, the azimuth plot made in sprit.plot_azimuth() will become a subplot of the larger plot made by the plot_hvsr() function. This is the expected behavior, for example, at the end of the sprit.run() if 'plot' is part of the report_format argument (which is the default behavior; in this case, if there is azimuthal data, the azimuthal subplot will automatically be included).

The plot_type parameter can be used to specify which plots and options are included in plot_hvsr() (see the Plotting Data wiki page for more information on the use of plot_hvsr()).

Example 1

sprit.plot_hvsr(hvsr_data, plot_type='HVSR COMP+ SPEC AZ)

will produce a plot with all the default plots (assuming there is azimuthal data). To customize these plots, you can include customization strings after each subplot name. To custo mize the azimuth plot to show the peak locations on the calculated azimuthal H/V data, the 'p' argument can be included in for the azimuthal subplot of the plot_type specification string:

An example of the output of this plot with azimuthal data generated every 45 degrees then interpolated is shown below:

Example 2

sprit.plot_hvsr(hvsr_data, plot_type='HVSR C+ SPEC AZ p -i')

All the azimuthal specification substrings and their purposes are shown below:

• 'p': shows a point at each calculated (not interpolated) azimuth peak
• 'g': shows emphasized grid lines on the azimuth plot
• '-i': prohibits interpolation (only shows the calculated azimuths, as determined by azimuth_angle (default = 30))
  • 'i': enables interpolation so that there is an interpolated azimuth at each degree interval (1 degree step)
    • This is the default, so usually ‘i’ is not needed.