hvsrpy - A Python package for horizontal-to-vertical spectral ratio processing

Joseph P. Vantassel, The University of Texas at Austin

Table of Contents

---

• About hvsrpy
• Why use hvsrpy
• A Comparison of hvsrpy with Geopsy
• Getting Started
• Additional Comparisons between hvsrpy and Geopsy
  • Multiple Windows
  • Single Window

About hvsrpy

---

hvsrpy is a Python package for performing horizontal-to-vertical spectral ratio (HVSR) processing. hvsrpy was developed by Joseph P. Vantassel with contributions from Dana M. Brannon under the supervision of Professor Brady R. Cox at The University of Texas at Austin. The automated frequency-domain window-rejection algorithm and lognormal statistics implemented in hvsrpy are detailed in Cox et al. (2020). The statistical approach to incorporate azimuth variability implemented in hvsrpy is detailed in Cheng et al. (2020). The approach to define statistics from spatially distributed HVSR measurements implemented in hvsrpy is detailed in Cheng et al. (2021).

If you use hvsrpy in your research or consulting, we ask you please cite the following:

Joseph Vantassel. (2020). jpvantassel/hvsrpy: latest (Concept). Zenodo. http://doi.org/10.5281/zenodo.3666956

Note: For software, version specific citations should be preferred to general concept citations, such as that listed above. To generate a version specific citation for hvsrpy, please use the citation tool on the hvsrpy archive.

These works provide background for the calculations performed by hvsrpy.

Cox, B. R., Cheng, T., Vantassel, J. P., & Manuel, L. (2020). "A statistical representation and frequency-domain window-rejection algorithm for single-station HVSR measurements. Geophysical Journal International, 221(3), 2170–2183. https://doi.org/10.1093/gji/ggaa119

Cheng, T., Cox, B. R., Vantassel, J. P., and Manuel, L. (2020). "A statistical approach to account for azimuthal variability in single-station HVSR measurements." Geophysical Journal International, 223(2), 1040–1053. https://doi.org/10.1093/gji/ggaa342

Cheng, T., Hallal, M. M., Vantassel, J. P., and Cox, B. R., (2021). "Estimating Unbiased Statistics for Fundamental Site Frequency Using Spatially Distributed HVSR Measurements and Voronoi Tessellation. J. Geotech. Geoenviron. Eng. 147, 04021068. https://doi.org/10.1061/(ASCE)GT.1943-5606.0002551

SESAME. (2004). Guidelines for the Implementation of the H/V Spectral Ratio Technique on Ambient Vibrations Measurements, Processing, and Interpretation. European Commission - Research General Directorate, 62, European Commission - Research General Directorate.

hvsrpy would not exist without the help of many others. As a small display of gratitude, we thank them individually here.

Why use hvsrpy

---

hvsrpy contains features not currently available in any other commercial or open-source software, including:

• A lognormal distribution for the fundamental site frequency (f0) so the uncertainty in f0 can be represented consistently in frequency or period.
• Ability to use the geometric-mean, squared-average, or any azimuth of your choice.
• Easy access to the HVSR data from each time window (and azimuth in the case of azimuthal calculations), not only the mean/median curve.
• A method to calculate statistics on f0 that incorporates azimuthal variability.
• A method for developing rigorous and unbiased spatial statistics.
• A fully-automated frequency-domain window-rejection algorithm.
• Automatic checking of the SESAME (2004) peak reliability and clarity criteria.
• A command line interface for highly performant batch-style processing.

Example output from hvsrpy when considering the geometric-mean of the horizontal components

	Lognormal Median	Lognormal Standard Deviation
Fundamental Site Frequency, f0,GM	0.72	0.11
Fundamental Site Period, T0,GM	1.40	0.11

Example output from hvsrpy when considering azimuthal variability

	Lognormal Median	Lognormal Standard Deviation
Fundamental Site Frequency, f0,AZ	0.68	0.18
Fundamental Site Period, T0,AZ	1.48	0.18

Example output from hvsrpy when considering spatial variability

	Lognormal Median	Lognormal Standard Deviation
Fundamental Site Frequency, f0,XY	0.58	0.15
Fundamental Site Period, T0,XY	1.74	0.15

A comparison of hvsrpy with Geopsy

---

Some of the functionality available in hvsrpy overlaps with the popular open-source software Geopsy. Therefore, to encourage standardization, wherever their functionality coincides we have sought to ensure consistency. Two such comparisons are shown below. One for a single time window (left) and one for multiple time windows (right). Additional examples and the information necessary to reproduce them are provided at the end of this document.

Getting Started

---

Installing or Upgrading hvsrpy

1. If you do not have Python 3.6 or later installed, you will need to do so. A detailed set of instructions can be found here.

2. If you have not installed hvsrpy previously use pip install hvsrpy. If you are not familiar with pip, a useful tutorial can be found here. If you have an earlier version and would like to upgrade to the latest version of hvsrpy use pip install hvsrpy --upgrade.

3. Confirm that hvsrpy has installed/updated successfully by examining the last few lines of the text displayed in the console.

Using hvsrpy

1. Download the contents of the examples directory to any location of your choice.

2. Launch the Jupyter notebook (simple_hvsrpy_interface.ipynb) in the examples directory for a no-coding-required introduction to the basics of the hvsrpy package. If you have not installed Jupyter, detailed instructions can be found here.

3. Launch the Jupyter notebook (azimuthal_hvsrpy_interface.ipynb) in the examples directory to perform more rigorous calculations which incorporate azimuthal variability.

4. Enjoy!

Looking for more information

More information regarding HVSR processing and hvsrpy can be found here.

Additional Comparisons between hvsrpy and Geopsy

---

Multiple Windows

The examples in this section use the same settings applied to different noise records. The settings are provided in the Settings section and the name of each file is provided above the corresponding figure in the Results section. The noise records (i.e., .miniseed files) are provided in the examples directory and also as part of a large published data set (Cox and Vantassel, 2018).

Settings

• Window Length: 60 seconds
• Bandpass Filter Boolean: False
• Cosine Taper Width: 10% (i.e., 5% in Geopsy)
• Konno and Ohmachi Smoothing Coefficient: 40
• Resampling:
  • Minimum Frequency: 0.3 Hz
  • Maximum Frequency: 40 Hz
  • Number of Points: 2048
  • Sampling Type: 'log'
• Method for Combining Horizontal Components: 'squared-average'
• Distribution for f0 from Time Windows: 'normal'
• Distribution for Mean Curve: 'log-normal'

Multiple Window Results

File Name: UT.STN11.A2_C50.miniseed

File Name: UT.STN11.A2_C150.miniseed

File Name: UT.STN12.A2_C50.miniseed

File Name: UT.STN12.A2_C150.miniseed

Single Window

The examples in this section apply different settings to the same noise record (UT.STN11.A2_C50.miniseed). For brevity, the default settings are listed in the Default Settings section, with only the variations from these settings noted for each example.

Default Settings

• Window Length: 60 seconds
• Bandpass Filter Boolean: False
• Cosine Taper Width: 10% (i.e., 5% in Geopsy)
• Konno and Ohmachi Smoothing Coefficient: 40
• Resampling:
  • Minimum Frequency: 0.3 Hz
  • Maximum Frequency: 40 Hz
  • Number of Points: 2048
  • Sampling Type: 'log'
• Method for Combining Horizontal Components: 'squared-average'
• Distribution for f0 from Time Windows: 'normal'
• Distribution for Mean Curve: 'log-normal'

Single Window Results

Default Case: No variation from those settings listed above.

Window Length: 120 seconds.

Cosine Taper Width: 20 % (i.e., 10 % in Geopsy)

Cosine Taper Width: 0.2 % (i.e., 0.1 % in Geopsy)

Konno and Ohmachi Smoothing Coefficient: 10

Konno and Ohmachi Smoothing Coefficient: 80

Number of Points: 512

Number of Points: 4096