Skip to content

Commit

Permalink
Updating hyperlinks for NGL and API use case documentation (#50)
Browse files Browse the repository at this point in the history 
* Add files via upload

* Delete docs/brandenberg/apiusecases/output_9_1.png

* Delete docs/brandenberg/apiusecases/output_11_1.png

* Delete docs/brandenberg/apiusecases/output_7_1.png

* Delete docs/brandenberg/apiusecases/output_8_0.png

* Update usecase.md

* Update usecase.md

* Create license.md

* Update usecase.md

Adjusting heading levels for use cases so they fall under "Implementation"

* Update usecase.md

* Update usecase.md

* Update usecase.md

* Update usecase.md

* Update usecase.md

* Update usecase.md

* Update usecase.md

* Update usecase.md

Updating hyperlinks and adding table with links to notebooks

* Update usecase.md

* Update usecase.md

* Update usecase.md

* Update usecase.md

* Update usecase.md

---------

Co-authored-by: Krishna Kumar <[email protected]>
  • Loading branch information
@sjbrandenberg @kks32
sjbrandenberg and kks32 authored Oct 18, 2023
1 parent 22274a2 commit 3fd0cb4
Show file tree
Hide file tree
Showing 2 changed files with 71 additions and 25 deletions.
20 changes: 10 additions & 10 deletions docs/brandenberg/apiusecases/usecase.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,27 +17,27 @@ Key Words: API, Application Programming Interface, Jupyter, Python, requests, US
<tr>
<td>NASA astronomy photo of the day</td>
<td>io, json, requests, pillow</td>
<td><a href="https://jupyter.designsafe-ci.org/hub/user-redirect/notebooks/CommunityData/Use%20Case%20Products/APIs/api_background.ipynb"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a></td>
<td><a href="https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Use%20Case%20Products/APIs/api_background.ipynb"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a></td>
</tr>
<tr>
<td>US Census map</td>
<td>folium, geopandas, requests, json, getpass</td>
<td><a href="https://jupyter.designsafe-ci.org/hub/user-redirect/notebooks/CommunityData/Use%20Case%20Products/APIs/us_census_api.ipynb"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a></td>
<td><a href="https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Use%20Case%20Products/APIs/us_census_api.ipynb"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a></td>
</tr>
<tr>
<td>USGS map of recent earthquakes</td>
<td>folium, geopandas, requests, json</td>
<td><a href="https://jupyter.designsafe-ci.org/hub/user-redirect/notebooks/CommunityData/Use%20Case%20Products/APIs/usgs_recent_earthquakes_api.ipynb"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a></td>
<td><a href="https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Use%20Case%20Products/APIs/usgs_recent_earthquakes_api.ipynb"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a></td>
</tr>
<tr>
<td>USGS Shakemap contours</td>
<td>folium, geopandas, requests, json, pandas</td>
<td><a href="https://jupyter.designsafe-ci.org/hub/user-redirect/notebooks/CommunityData/Use%20Case%20Products/APIs/usgs_shakemap_api.ipynb"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a></td>
<td><a href="https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Use%20Case%20Products/APIs/usgs_shakemap_api.ipynb"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a></td>
</tr>
<tr>
<td>NOAA hourly wind data</td>
<td>folium, matplotlib, requests, json</td>
<td><a href="https://jupyter.designsafe-ci.org/hub/user-redirect/notebooks/CommunityData/Use%20Case%20Products/APIs/noaa_api.ipynb"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a></td>
<td><a href="https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Use%20Case%20Products/APIs/noaa_api.ipynb"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a></td>
</tr>
</table>

Expand Down Expand Up @@ -73,7 +73,7 @@ The use cases below provide a description of each API followed by code required

### NASA Astronomy Picture of the Day

<a href="https://jupyter.designsafe-ci.org/hub/user-redirect/notebooks/CommunityData/Use%20Case%20Products/APIs/api_background.ipynb"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a>
<a href="https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Use%20Case%20Products/APIs/api_background.ipynb"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a>

NASA maintains a number of open API's to make NASA data, including imagery, available to the public. Here we focus on the Astronomy Picture of the Day, or APOD. Many of NASA's API's require an API key, which can be obtained by signing up through their form at https://api.nasa.gov/. We have elected to use APOD because a demo key can be used to retrieve photos. Therefore this example will work for users who do not have a NASA API token. Below is an example query.

Expand Down Expand Up @@ -136,7 +136,7 @@ Description: Do you see the horse's head? What you are seeing is not the famous

### US Census Map

<a href="https://jupyter.designsafe-ci.org/hub/user-redirect/notebooks/CommunityData/Use%20Case%20Products/APIs/us_census_api.ipynb"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a>
<a href="https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Use%20Case%20Products/APIs/us_census_api.ipynb"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a>

This use case demonstrates how to pull data from a US Census API request and plot it using Folium. The Jupyter notebook is more heavily annotated and divided into cells. This page presents an abridged version highlighting key details. Details about the US Census API can be found at https://www.census.gov/data/developers/guidance/api-user-guide.html. This use case focuses on the American Community Survey (ACS) https://www.census.gov/programs-surveys/acs, which is a survey conducted by the US Census which details housing and population counts for the nation. A US Census API Key is required to use this use case product. So go over to https://api.census.gov/data/key_signup.html and get your API key now! We'll be here when you get back.

Expand Down Expand Up @@ -211,7 +211,7 @@ display(pop_map)

### USGS recent earthquake map

<a href="https://jupyter.designsafe-ci.org/hub/user-redirect/notebooks/CommunityData/Use%20Case%20Products/APIs/usgs_recent_earthquakes_api.ipynb"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a>
<a href="https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Use%20Case%20Products/APIs/usgs_recent_earthquakes_api.ipynb"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a>

This Jupyter notebook demonstrates the USGS API for retrieving details of earthquakes over a certain magntiude that occured over a specific time period. The goal of this notebook is to take the USGS hourly/weekly/monthly earthquake RSS feed ( https://earthquake.usgs.gov/earthquakes/feed/) and plot the earthquakes and their relevant magnitudes using the Folium Python package(https://python-visualization.github.io/folium/). This API does not require a key.

Expand Down Expand Up @@ -258,7 +258,7 @@ my_map

### USGS Shakemap contours

<a href="https://jupyter.designsafe-ci.org/hub/user-redirect/notebooks/CommunityData/Use%20Case%20Products/APIs/usgs_shakemap_api.ipynb"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a>
<a href="https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Use%20Case%20Products/APIs/usgs_shakemap_api.ipynb"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a>

This Jupyter notebook will walk through how to access an USGS Shakemap API. The goal of this example is to use an API request to retrieve a USGS Shakemap (https://earthquake.usgs.gov/data/shakemap/) and plot the shakemap for the earthquake using a Python Package called Folium (https://python-visualization.github.io/folium/)

Expand Down Expand Up @@ -306,7 +306,7 @@ m

### NOAA hourly wind data

<a href="https://jupyter.designsafe-ci.org/hub/user-redirect/notebooks/CommunityData/Use%20Case%20Products/APIs/noaa_api.ipynb"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a>
<a href="https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/Use%20Case%20Products/APIs/noaa_api.ipynb"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a>

The following use case will detail data from the NOAA Co-OPS Data Retrieval API. You can learn more information here :https://api.tidesandcurrents.noaa.gov/api/prod/. Data regarding tidal/water levels, wind data, temperature data, air temperature/pressure, conductivity, visibility, humidity, and salinity are available. The locations where data is availble is based on buoy and instrumentation location. Predictions as well as reviewed NOAA data is available to users.

Expand Down
76 changes: 61 additions & 15 deletions docs/brandenberg/usecase.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,63 @@

The example makes use of the following DesignSafe resources:

[Jupyter notebooks on DS Juypterhub](https://www.designsafe-ci.org/rw/workspace/#!/Jupyter::Analysis){target=_blank}<br/>
[NGL Database](https://www.nextgenerationliquefaction.org/){target=_blank}<br/>
<table>
<tr>
<th>Notebook</th>
<th>Link</th>
</tr>
<tr>
<td>
Example Queries
</td>
<td>
<a href="https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/NGL/ExampleQueries.ipynb" target="_blank"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a>
</td>
</tr>
<tr>
<td>
Cone Penetration Test Viewer
</td>
<td>
<a href="https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/NGL/CPT_viewer.ipynb" target="_blank"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a>
</td>
</tr>
<tr>
<td>
V<sub>S</sub> (Invasive) Test Viewer
</td>
<td>
<a href="https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/NGL/VS_Invasive_viewer.ipynb" target="_blank"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a>
</td>
</tr>
<tr>
<td>
October 2021 DesignSafe Webinar
</td>
<td>
<a href="https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/NGL/DesignSafe_Webinar_Oct2021.ipynb" target="_blank"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a>
</td>
</tr>
<tr>
<td>
Direct Simple Shear Viewer
</td>
<td>
<a href="https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/NGL/DSS_Viewer.ipynb" target="_blank"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a>
</td>
</tr>
</table>

The NGL database can be accessed at <a href="https://www.nextgenerationliquefaction.org/" target="_blank">https://www.nextgenerationliquefaction.org/</a>

## Background
### Citations and Licensing

* Please cite [Zimmaro, P., et al. (2019)](https://doi.org/10.21222/C2J040){target=_blank} to acknowledge the use of the NGL Database. Data in the NGL database has been gathered from [these](https://nextgenerationliquefaction.org/citations.php){target=_blank} published sources. If you use specific data in the database, please cite the original source.
* Please cite [Zimmaro, P., et al. (2019)](https://doi.org/10.21222/C2J040) to acknowledge the use of the NGL Database. Data in the NGL database has been gathered from [these](https://nextgenerationliquefaction.org/citations.php) published sources. If you use specific data in the database, please cite the original source.

* Please cite [Rathje et al. (2017)](https://doi.org/10.1061/(ASCE)NH.1527-6996.0000246){target=_blank} to acknowledge the use of DesignSafe resources.
* Please cite [Rathje et al. (2017)](https://doi.org/10.1061/(ASCE)NH.1527-6996.0000246) to acknowledge the use of DesignSafe resources.

* This software is distributed under the [GNU General Public License](https://www.gnu.org/licenses/gpl-3.0.html){target=_blank}.
* This software is distributed under the [GNU General Public License](https://www.gnu.org/licenses/gpl-3.0.html).


### Description
Expand All @@ -28,7 +74,7 @@ substantially larger, more consistent, and more reliable source of liquefaction
Based on this database, we will create probabilistic models that provide hazard- and risk-consistent bases
for assessing liquefaction susceptibility, the potential for liquefaction to be triggered in susceptible soils,
and the likely consequences. NGL is committed to an open and objective evaluation and integration of data,
models and methods, as recommended in a 2016 National Academies [report](https://www.nap.edu/catalog/23474/state-of-the-art-and-practice-in-the-assessment-of-earthquake-induced-soil-liquefaction-and-its-consequences){target=_blank}.
models and methods, as recommended in a 2016 National Academies [report](https://www.nap.edu/catalog/23474/state-of-the-art-and-practice-in-the-assessment-of-earthquake-induced-soil-liquefaction-and-its-consequences).

The evaluation and integration of the data into new models and methods will be clear and transparent. Following these principles will ensure
that the resulting liquefaction susceptibility, triggering, and consequence models are reliable, robust and
Expand All @@ -38,7 +84,7 @@ critical infrastructure projects.
The NGL database is populated through a web interface at www.nextgenerationliquefaction.org/. The web interface
provides limited capabilities for users to interact with data. Users are able to view and download data,
but they cannot use the GUI to develop an end-to-end workflow to make scientific inferences and draw conclusions
from the data. To facilitate end-to-end workflows, the NGL database is replicated daily to [DesignSafe](https://www.designsafe-ci.org){target=_blank}, where
from the data. To facilitate end-to-end workflows, the NGL database is replicated daily to [DesignSafe](https://www.designsafe-ci.org), where
users can interact with it using Jupyter notebooks.

## Understanding the Database Schema
Expand All @@ -47,7 +93,7 @@ The NGL database is organized into tables that are related to each other via key
you will need to understand the organizational structure of the database, called the schema. The database
schema is documented at the following URL:

[https://nextgenerationliquefaction.org/schema/index.html](https://nextgenerationliquefaction.org/schema/index.html){target=_blank}
[https://nextgenerationliquefaction.org/schema/index.html](https://nextgenerationliquefaction.org/schema/index.html)

## Querying Data via Jupyter Notebooks

Expand Down Expand Up @@ -81,7 +127,7 @@ This notebook contains example queries to illustrate how to extract data from th
5. Query information about BORH table
6. Query counts of cone penetration test data, boreholes, surface wave measurements, invasive shear wave velocity measurements, liquefaction observations, and non-liquefaction observations

[ExampleQueries.ipynb](https://jupyter.designsafe-ci.org/user/name/tree/CommunityData/NGL/ExampleQueries.ipynb){target=_blank}
<a href="https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/NGL/ExampleQueries.ipynb" target="_blank"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a>

## Cone Penetration Test Viewer

Expand All @@ -96,7 +142,7 @@ The cone penetration test viewer demonstrates the following:

Cone penetration test data plotted in the notebook include tip resistance, sleeve friction, and pore pressure. In some cases, sleeve friction and pore pressure are not measured, in which case the plots are empty.

[CPT_viewer.ipynb](https://jupyter.designsafe-ci.org/user/name/tree/CommunityData/NGL/CPT_viewer.ipynb){target=_blank}
<a href="https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/NGL/CPT_viewer.ipynb" target="_blank"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a>


## V<sub>S</sub> (Invasive) Test Viewer
Expand All @@ -110,7 +156,7 @@ The V<sub>s</sub> (Invasive) Test Viewer demonstrates the following:
5. Using the ipywidgets "observe" feature to call functions when users select a widget value
6. Plotting data from the selected invasive geophysical test using matplotlib

[VS_Invasive_viewer.ipynb](https://jupyter.designsafe-ci.org/user/name/tree/CommunityData/NGL/VS_Invasive_viewer.ipynb){target=_blank}
<a href="https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/NGL/VS_Invasive_viewer.ipynb" target="_blank"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a>


## October 2021 DesignSafe Webinar
Expand All @@ -125,11 +171,11 @@ The notebook demonstrates the following:

Cone penetration test data plotted in the notebook include tip resistance, sleeve friction, and pore pressure. In some cases, sleeve friction and pore pressure are not measured, in which case the plots are empty.

[DesignSafe_Webinar_Oct2021.ipynb](https://jupyter.designsafe-ci.org/user/name/tree/CommunityData/NGL/DesignSafe_Webinar_Oct2021.ipynb){target=_blank}
<a href="https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/NGL/DesignSafe_Webinar_Oct2021.ipynb" target="_blank"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a>

[DesignSafe Webinar YouTube video](https://youtu.be/TNOPOU4lx5w){target=_blank}
[DesignSafe Webinar YouTube video](https://youtu.be/TNOPOU4lx5w)

[DesignSafe Workshop YouTube video](https://youtu.be/_nKpSqa1rso){target=_blank}
[DesignSafe Workshop YouTube video](https://youtu.be/_nKpSqa1rso)

## Direct Simple Shear Laboratory Test Viewer

Expand All @@ -143,4 +189,4 @@ The Direct Simple Shear Laboratory Test Viewer is a graphical interface that plo

Direct simple shear data plotted in the notebook include shear stress, shear strain, vertical stress, and vertical strain time series in the first plot. The second plot displays shear strain and void ratio versus vertical stress and void ratio, shear stress, and vertical stress ratio versus shear strain.

[DSS_Viewer.ipynb](https://jupyter.designsafe-ci.org/user/name/tree/CommunityData/NGL/DSS_Viewer.ipynb){target=_blank}
<a href="https://jupyter.designsafe-ci.org/hub/user-redirect/lab/tree/CommunityData/NGL/DSS_Viewer.ipynb" target="_blank"><img src="https://raw.githubusercontent.com/geoelements/LearnMPM/main/DesignSafe-Badge.svg"></a>

0 comments on commit 3fd0cb4

Please sign in to comment.