open_seismo_data_part1.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "47c85b4a",
   "metadata": {},
   "source": [
    "<img src=\"./images/SCEC_logo-2colors_BlueRed.png\" style=\"width:200px;\"/>\n",
    "\n",
    "# Open Science Data for Seismology\n",
    "\n",
    "This notebook introduces key open science data types in seismology and provides hands-on exercises for accessing and exploring these datasets.\n",
    "\n",
    "---\n",
    "\n",
    "## Earthquake Catalogs, Observed Seismograms, Fault Geometry Models, Seismic Velocity Models\n",
    "\n",
    "Seismology relies on diverse datasets to study the Earth's structure and seismic events:\n",
    "\n",
    "- **Earthquake Catalogs**: Databases of earthquake locations, magnitudes, and times (e.g., USGS, IRIS).\n",
    "- **Observed Seismograms**: Time-series data recorded by seismic stations.\n",
    "- **Fault Geometry Models**: Representations of fault surfaces in 3D.\n",
    "- **Seismic Velocity Models**: Maps of seismic wave speeds in the Earth's subsurface.\n",
    "\n",
    "---\n",
    "\n",
    "## Find, Select, Download, View\n",
    "\n",
    "Accessing seismological data involves these steps:\n",
    "1. **Find**: Locate datasets using platforms like IRIS DMC or USGS Earthquake Catalog.\n",
    "2. **Select**: Filter datasets based on criteria like location, time range, or magnitude.\n",
    "3. **Download**: Retrieve data in formats such as CSV, SAC, or NetCDF.\n",
    "4. **View**: Visualize data with tools like Python, ObsPy, or GIS software.\n",
    "\n",
    "This Jupyter notebook introduces the basic process of working with open science data by introducing four common steps of data access: Find, Select, Download, and View. These steps are taken when accessing most types of open-science data regardless of the specific data being accesssed, and they align with key principles of the FAIR data guidelines and the broader open science frameworks developed by researchers such as Wilkinson et al. and organizations like Research Data Alliance (RDA), Earth Science Information Partners (ESIP), and DataONE.\n",
    "\n",
    "---\n",
    "\n",
    "## Exercise One: Earthquake Catalog Data Access\n",
    "\n",
    "In this exercise, you will find earthquakes data service, select earthquakes of interest, download the earthquakes to your computer, and view the retrieved dataset.\n",
    "\n",
    "1. **Find**: Locate datasets using platforms like IRIS DMC or USGS Earthquake Catalog.\n",
    "\n",
    "Researchers can find earthquake catalogs using the open-data services of the U.S. Geological Survey. The U.S.G.S integrates information from a multiple seismic networks and provides open access to the resulting earthquake catalog through web interface and programmatic API.\n",
    "\n",
    "Other seismological data services also provide earthquake catalogs, which have special characteritics such as coverage region, coverage time period, magnitude completeness, and location methods.\n",
    "\n",
    "Exercises will show how to access research data used in seismological simulations. The workshop show how to find, retrieve and use open seismological data including earthquake catalogs, observed seismograms, fault geometry models, seismic velocity models.\n",
    "\n",
    "A list of additional earthquake catalogs is provided by USGS at this website:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b0f3cc13",
   "metadata": {},
   "outputs": [],
   "source": [
    "import webbrowser\n",
    "url = \"https://earthquake.usgs.gov/data/comcat/catalog/\"\n",
    "\n",
    "# Open the URL in the default web browser\n",
    "webbrowser.open(url)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e9ce8470",
   "metadata": {},
   "source": [
    "2. **Select**: Filter datasets based on criteria like location, time range, or magnitude.\n",
    "\n",
    "Researchers select the earthquakes they want in their catalog by defining parameters including region, start-date, end-date, minimum magnitude.\n",
    "\n",
    "Select catalog of interest, using default parameters:\n",
    "\n",
    "<ol>\n",
    "<li>Magnitude: 4.5+</li>\n",
    "<li>Date & Time: Past 30 Days</li>\n",
    "<li>Geographical Region: Conterminous US</li>\n",
    "</ol>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dc595664",
   "metadata": {},
   "outputs": [],
   "source": [
    "import webbrowser\n",
    "url = \"https://earthquake.usgs.gov/earthquakes/map/?extent=7.53676%2C-145.98633&extent=60.15244%2C-43.94531&range=search&timeZone=utc&search=%7B%22name%22%3A%22Search+Results%22%2C%22params%22%3A%7B%22starttime%22%3A%222024-12-07+00%3A00%3A00%22%2C%22endtime%22%3A%222024-12-14+23%3A59%3A59%22%2C%22maxlatitude%22%3A50%2C%22minlatitude%22%3A24.6%2C%22maxlongitude%22%3A-65%2C%22minlongitude%22%3A-125%2C%22minmagnitude%22%3A2.5%2C%22orderby%22%3A%22time%22%7D%7D\"\n",
    "# Open the URL in the default web browser\n",
    "webbrowser.open(url)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "991abedf",
   "metadata": {},
   "source": [
    "Using this selection critera on 15 Dec 2024, the resulting map shows 178 earthquakes meet these selection criteria.The results will differ depending on the day when you preform this query.\n",
    "\n",
    "<img src=\"./images/OS_30day_catalog.png\" style=\"width:500px;\"/>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f162d719-3e50-4c8d-b99c-496187056873",
   "metadata": {},
   "source": [
    "3. **Download**: Retrieve data in formats such as CSV, SAC, or NetCDF.\n",
    "Researchers can download the data for use on their computer. \n",
    "\n",
    "Computational models of earthquake processes will often require use of open science data sources. When downloading data, an important consideration is the data format. Make sure to identify how you will read a data format before you donwload a data in it.\n",
    "\n",
    "To download the results of a earthquake catalog query, use the USGS earthquake catalog search page, specify the same search paramters, but in this query add additional additional parameters to your data request. On the webpage, locate a section called Format Options. Specify the download format you want:\n",
    "\n",
    "**Output Options:**\n",
    "<ol>\n",
    "<li>Format: KML</li>\n",
    "<li>KML-Specific Options: Color by age</li>\n",
    "<li>Order By: Time - Newest First </li>\n",
    "<li>Limit Results: (leave blank) </li>\n",
    "</ol>\n",
    "\n",
    "Once you have selected these selection criteria, press the **search** near the bottom of the page, and it will retrieve your catalog and download it to a file called: **query.kml**\n",
    "\n",
    "You can open the **query.kml** file with google Chrome browser, or Google earth."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f7d97808",
   "metadata": {},
   "outputs": [],
   "source": [
    "import webbrowser\n",
    "url = \"https://earthquake.usgs.gov/earthquakes/search/\"\n",
    "\n",
    "# Open the URL in the default web browser\n",
    "webbrowser.open(url)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e462a7a2",
   "metadata": {},
   "source": [
    "\n",
    "4. **View**: Visualize data with tools like Python, ObsPy, or GIS software.\n",
    "\n",
    "Researchers view the data and metadata using platform and data specific tools. For earthquake catalogs, KML files can be read using Chrome Browser and Google Earth, good for visualizing the catalog. For processing the data, formats like Comma Separted Values (CSV) which can be read with text editors or spreadsheet software are often used to view data.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f0ec87f4",
   "metadata": {},
   "source": [
    "--- \n",
    "## Exercise Two: Observed Seismograms Data Access\n",
    "\n",
    "In this exercise, you will find earthquakes data service, select earthquakes of interest, download the earthquakes to your computer, and view the retrieved dataset.\n",
    "\n",
    "1. **Find**: Locate datasets using platforms like IRIS DMC or USGS Earthquake Catalog.\n",
    "\n",
    "Researchers can retrieve observed seismograms for significant earthquake for many stations using the U.S.G.S open data services. There is a wide variety of data access options, and researchers will select the most appropriate options based on their intended use of the seismograms.\n",
    "\n",
    "Other seismological data services also provide observed seismograms, including groups that focus on strong ground motion data used for civil engineering and earthquake engineering research."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "949f9a2f",
   "metadata": {},
   "outputs": [],
   "source": [
    "import webbrowser\n",
    "url = \"https://www.iris.edu/hq/programs/epo/resources_for_viewing_seismograms\"\n",
    "\n",
    "# Open the URL in the default web browser\n",
    "webbrowser.open(url)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b39bde79",
   "metadata": {},
   "source": [
    "2. **Select**: Filter datasets based on criteria like location, time range, or magnitude.\n",
    "\n",
    "Use EarthScope SAGE data service to retrieve seismograms for a specific event.\n",
    "IRIS URL Builder to specific data for a Northern California Mainshock:\n",
    "\n",
    "Researchers select the seismograms they want by defining parameters including earthquake, site, duration.\n",
    "\n",
    "\n",
    "For this exercise, we will retrieve observed seismograms for a recent Northern California Mendocino M7.0 Event, at a southern California station on campus at University of Southern California. This station is approximately 1000km from the earthquake epicenter.\n",
    "\n",
    "To help us gather the required *selection* information, visit the URL Builder to determine what information is needed. We are going to need both event information and station information in our selection:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5b3ab0b8",
   "metadata": {},
   "outputs": [],
   "source": [
    "import webbrowser\n",
    "url = \"https://service.iris.edu/fdsnws/dataselect/docs/1/builder/\"\n",
    "# Open the URL in the default web browser\n",
    "webbrowser.open(url)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5bbe1431",
   "metadata": {},
   "source": [
    "Based on this review, we can identify the following information is required in our seismogram data request:\n",
    "\n",
    "<ol>\n",
    "<li>Start_Time: </li>\n",
    "<li>End_time: </li>\n",
    "<li>Network: </li>\n",
    "<li>Station: </li>\n",
    "<li>Channel : </li>\n",
    "<li>Location: </li>\n",
    "<li>Quality: </li>\n",
    "<li>Format: </li>\n",
    "</ol>\n",
    "\n",
    "**Station Information**\n",
    "\n",
    "To find the required station and channel information, we can use the CISN Seismic Station Database:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "94eeef33",
   "metadata": {},
   "outputs": [],
   "source": [
    "import webbrowser\n",
    "url = \"https://service.scedc.caltech.edu/SCSNStationMap/station.html\"\n",
    "# Open the URL in the default web browser\n",
    "webbrowser.open(url)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f4cd2fe3",
   "metadata": {},
   "source": [
    "Collected this information for station USC:\n",
    "\n",
    "<ol>\n",
    "<li>Network: CI</li>\n",
    "<li>Station: USC</li>\n",
    "<li>Channel : BHZ (vertical broadband - 20 sps)</li>\n",
    "<li>Location: --</li>\n",
    "</ol>\n",
    "\n",
    "** Event Information **\n",
    "\n",
    "Now, visit the IRIS Event Page to determine the event origin time and collect the results to help us form our seismogram query."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "babf8e0f",
   "metadata": {},
   "outputs": [],
   "source": [
    "url = \"https://ds.iris.edu/ds/nodes/dmc/tools/event/11909383/\"\n",
    "# Open the URL in the default web browser\n",
    "webbrowser.open(url)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5a6bc463",
   "metadata": {},
   "source": [
    "3. **Download**: Retrieve data in formats such as CSV, SAC, or NetCDF.\n",
    "\n",
    "Researchers can download the data for use on their computer. Computational models of earthquake processes will often require use of open science data sources. When downloading data, an important consideration is the data format. Make sure to identify how you will read a data format before you donwload a data in it.\n",
    "\n",
    "For earthquake seismograms, researchers can specify ground motions by station time duration. Collection of seismograms from significant events are also available. The information required to retrieve our seismogram of interest, USC for the Mendacinon 7.0 uses these inputs:\n",
    "\n",
    "Event Page Information Event Time. For start time, use Earthquake Origin time. For large event, request 5 minutes of 20sps broadband vertical component velocity data (BHZ). USC Station and broadband 10Hz Channel is defined as:\n",
    "\n",
    "<ol>\n",
    "<li>Start_Time: 2024-12-05T18:44:21</li>\n",
    "<li>End_time: 2024-12-05T18:49:21</li>\n",
    "<li>Network: CI</li>\n",
    "<li>Station: USC</li>\n",
    "<li>Channel : BHZ (vertical broadband - 20 sps)</li>\n",
    "<li>Location: --</li>\n",
    "<li>Quality: -</li>\n",
    "<li>Format: GeoCSV</li>\n",
    "</ol>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8b2374fd",
   "metadata": {},
   "outputs": [],
   "source": [
    "import webbrowser\n",
    "url = \"https://service.iris.edu/fdsnws/dataselect/docs/1/builder/\"\n",
    "# Open the URL in the default web browser\n",
    "webbrowser.open(url)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1184f988",
   "metadata": {},
   "source": [
    "If the users fills in the URL Builder form, it produces a long URL that will retrieve the specified seismograms. The following URL retrieves the USC seismograms and downloads a file GeoCSV format seismogram file: **fdsnws-dataselect_2024-12-15t21_27_19z.csv ** (430 KB). This text file can be opened with multiple programs including a text editor."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cb637218",
   "metadata": {},
   "outputs": [],
   "source": [
    "import webbrowser\n",
    "seism_url = \"https://service.iris.edu/fdsnws/dataselect/1/query?net=CI&sta=USC&loc=--&cha=BHZ&starttime=2024-12-05T18:44:21&endtime=2024-12-05T18:49:21&format=geocsv&nodata=404\"\n",
    "webbrowser.open(seism_url)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ee327f70",
   "metadata": {},
   "source": [
    "4. **View**: Visualize data with tools like Python, ObsPy, or GIS software.\n",
    "\n",
    "Researchers view the data and metadata using platform and data specific tools. For seismograms, formats like GeoCSV can be read and plotted using programs like Excel. Seismologist often use seismogram specific visualization tools such as SAC, ObsPy, and others to view seismogram data."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ec7a2ac5",
   "metadata": {},
   "source": [
    "--- \n",
    "\n",
    "## Exercise Three: Fault Geometry Model Data Access\n",
    "\n",
    "In this exercise, you will find California Fault Geometry models and view the retrieved dataset.\n",
    "\n",
    "1. **Find**: Locate datasets using platforms like IRIS DMC or USGS Earthquake Catalog.\n",
    "\n",
    "Researchers can retrieve fault geometry files from the USGS and from other sources including SCEC. The fault geometry descriptions my include location of faults at the surface, or full 3D geometry files.\n",
    "\n",
    "Find fault geometry options at the USGS Fault Surface Geometry File:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f465a6bf-720c-433e-a47f-9b8d06a46b47",
   "metadata": {},
   "outputs": [],
   "source": [
    "import webbrowser\n",
    "url = \"https://www.usgs.gov/programs/earthquake-hazards/faults\"\n",
    "# Open the URL in the default web browser\n",
    "webbrowser.open(url)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "84e38eb5",
   "metadata": {},
   "source": [
    "2. **Select**: Filter datasets based on criteria like location, time range, or magnitude.\n",
    "\n",
    "Users select the fault of interest through a GUI Interface:\n",
    "\n",
    "3. **Download**: Retrieve data in formats such as CSV, SAC, or NetCDF.\n",
    "\n",
    "Researchers can download fault geometry files for use on their computer. A KMZ file containing conterminous US fault geometries is available through the USGS Web service.\n",
    "\n",
    "4. **View**: Visualize data with tools like Python, ObsPy, or GIS software.\n",
    "\n",
    "Researchers view the data and metadata using platform and data specific tools. For fault in KMZ format, google chrome can read the files. Many browsers will download the file from a given url. A short Python script to dowload the qfaults.kmz file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "32d48db0",
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests\n",
    "# URL of the .kmz file\n",
    "url = \"https://earthquake.usgs.gov/static/lfs/nshm/qfaults/qfaults.kmz\"\n",
    "\n",
    "# Local filename to save the file\n",
    "output_file = \"qfaults.kmz\"\n",
    "\n",
    "try:\n",
    "    # Send a GET request to the URL\n",
    "    response = requests.get(url, stream=True)\n",
    "\n",
    "    # Check if the request was successful\n",
    "    if response.status_code == 200:\n",
    "        # Save the content to a file\n",
    "        with open(output_file, \"wb\") as file:\n",
    "            for chunk in response.iter_content(chunk_size=8192):\n",
    "                file.write(chunk)\n",
    "        print(f\"File downloaded successfully as {output_file}\")\n",
    "    else:\n",
    "        print(f\"Failed to download file. HTTP Status Code: {response.status_code}\")\n",
    "except Exception as e:\n",
    "    print(f\"An error occurred: {e}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c7fdd946",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## Exercise Four: Seismic Velocity Model Data Access\n",
    "\n",
    "In this exercise, you will find informatoin about California seismic velocity models and view the retrieved dataset.\n",
    "\n",
    "1. **Find**: Locate datasets using platforms like IRIS DMC or USGS Earthquake Catalog.\n",
    "\n",
    "Researchers can retrieve seismic velocity model information for California from SCEC. SCEC's seismic velocity models are access through a web browser.\n",
    "\n",
    "Other seismological data services also provide access to Velocity Model information (e.g. USGS, EarthScope EMC, and CRESCENT CVM)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "12b32897",
   "metadata": {},
   "outputs": [],
   "source": [
    "import webbrowser\n",
    "url = \"http://moho.scec.org/UCVM_web/web/viewer.php\"\n",
    "# Open the URL in the default web browser\n",
    "webbrowser.open(url)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "181246aa",
   "metadata": {},
   "source": [
    "2. **Select**: Filter datasets based on criteria like location, time range, or magnitude.\n",
    "\n",
    "Users select the velocity model of interest, and the type of data they want (point, vertical profile, cross section etc) using a GUI Interface:\n",
    "\n",
    "<ol>\n",
    "<li> Model Type: CVM-H v15.1</li>\n",
    "<li> Z-mode: Depth</li>\n",
    "<li> 1D Vertical Profile </li>\n",
    "<li> Lat: 34.0334</li>\n",
    "<li> Long: -118.2855</li>\n",
    "<li> Z start: 0</li>\n",
    "<li> Z ends: 15000</li>\n",
    "<li> Z step: 1<li>\n",
    "<li> Material Properties: Vp,Vs, density</li>\n",
    "</ol>\n",
    "\n",
    "3. **Download**: Retrieve data in formats such as CSV, SAC, or NetCDF.\n",
    "\n",
    "Researchers can download seismic velocity model data in csv format.\n",
    "\n",
    "4. **View**: Visualize data with tools like Python, ObsPy, or GIS software.\n",
    "\n",
    "Researchers view the data and metadata using platform and data specific tools. For fault in KMZ format, google chrome can read the files."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e61613b4",
   "metadata": {},
   "outputs": [],
   "source": [
    "url = \"http://moho.scec.org/UCVM_web/web/viewer.php\"\n",
    "# Open the URL in the default web browser\n",
    "webbrowser.open(url)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9524febf",
   "metadata": {},
   "source": [
    "<img src=\"./images/UCVM_USC_V_Profile.png\" style=\"width:500px;\"/>\n",
    "\n",
    "<img src=\"./images/UCVM_21833515_v.png\" style=\"width:500px;\"/>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fd3546e4",
   "metadata": {},
   "source": [
    "**End of Exercise 1:**\n",
    "\n",
    "In the next exercise, we will review open seismological data access methods, using programmatic APIs.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "44f9b739-4612-4247-bb42-9dbd05bd1bdf",
   "metadata": {},
   "source": [
    "**Questions: software@scec.org**\\\n",
    "**Acknowledgements: SCEC, USC, UCSD, SDSC, UIUC, LMU, University of Bristol**\\\n",
    "**Software License: BSD-3**\\\n",
    "**Copyright Notice: CC by 4.0**\\"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0a6ae3c4",
   "metadata": {},
   "source": [
    "<img src=\"./images/ccby40.png\" style=\"width:200px;\"/>"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "quakeworx-workshop-env",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.21"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}