m.cdo.download: Add a new addon for downloading NCEI (previouly NCDC)…

… Climate Data Online (CDO) (#963)

* m.cdo.download: Add a new addon for downloading NCEI (previouly NCDC) Climate Data Online

* Change PRCP examples to PRCP,AVG

* Change PRCP examples to PRCP,AVG

* Add a vector creation example

* Add a vector figure

* Add spaces in awk script

src/misc/m.cdo.download/Makefile

@@ -0,0 +1,7 @@
+MODULE_TOPDIR = ../..
+
+PGM = m.cdo.download
+
+include $(MODULE_TOPDIR)/include/Make/Script.make
+
+default: script

src/misc/m.cdo.download/m.cdo.download.html

@@ -0,0 +1,102 @@
+<h2>DESCRIPTION</h2>
+
+<em>m.cdo.download</em> downloads data from
+<a href="https://www.ncei.noaa.gov/cdo-web/webservices/v2">NCEI's Climate Data
+Online (CDO)</a> using their v2 API.
+
+<h2>NOTES</h2>
+
+This module uses <a href="https://www.ncei.noaa.gov/cdo-web/api/v2/">the CDO
+Web Services v2 API</a> to download CDO data.
+
+<h2>EXAMPLES</h2>
+
+<p>List available datasets:
+<div class="code"><pre>
+m.cdo.download fetch=datasets
+</pre></div>
+
+<p>List available dataset IDs without column names:
+<div class="code"><pre>
+m.cdo.download -c fetch=datasets fields=id
+</pre></div>
+
+<p>List available stations within (47.5204,-122.2047)-(47.6139,-122.1065):
+<div class="code"><pre>
+m.cdo.download fetch=stations extent=47.5204,-122.2047,47.6139,-122.1065
+</pre></div>
+
+<p>List available &quot;precipitation&quot; and &quot;average temperature&quot;
+data types:
+<div class="code"><pre>
+m.cdo.download fetch=datatypes field=id,mindate,maxdate,name |
+grep -i "|precipitation\||average temperature"
+</pre></div>
+
+<p>List 10 available stations with PRCP and TAVG data starting 2023-01-01:
+<div class="code"><pre>
+m.cdo.download fetch=stations datatypeid=PRCP,TAVG startdate=2023-01-01 limit=10
+</pre></div>
+
+<p>Fetch daily PRCP and TAVG data for a station with mindate &le; 2023-01-01 and
+save it into a file:
+<div class="code"><pre>
+# find dataset IDs for data types PRCP and TAVG; let's use GHCND (Daily Summary)
+m.cdo.download fetch=datasets datatypeid=PRCP,TAVG
+
+# find the first station ID with mindate &le; 2023-01-01
+stationid=$(m.cdo.download -c fetch=stations datatypeid=PRCP,TAVG \
+	startdate=2023-01-01 fields=id limit=1)
+
+# fetch actual data and save it to data.txt
+m.cdo.download fetch=data datasetid=GHCND datatypeid=PRCP,TAVG \
+	stationid=$stationid startdate=2023-01-01 enddate=2023-10-15 \
+	output=data.txt
+</pre></div>
+
+<p>Create a point vector map with all stations:
+<div class="code"><pre>
+# from a latlong location
+
+# download metadata for all stations
+m.cdo.download stations output=cdo_stations.txt
+
+# import cdo_stations.txt
+xy=$(awk -F'|' '{
+	if (NR == 1) {
+		for (i = 1; i &lt;= NF; i++)
+			if ($i == &quot;latitude&quot;)
+				latind = i
+			else if ($i == "quot;longitude"quot;)
+				lonind = i
+		printf &quot;x=%s y=%s&quot;, lonind, latind
+		exit
+	}
+}' cdo_stations.txt)
+v.in.ascii input=cdo_stations.txt output=cdo_stations skip=1 $xy
+
+# rename columns
+old_cols=$(db.columns table=cdo_stations exclude=cat)
+new_cols=$(head -1 cdo_stations.txt | sed 's/|/ /g')
+
+for old_new in $(echo $old_cols $new_cols |
+	awk '{
+		n = NF / 2
+		for (i = 1; i &lt;= n; i++)
+			printf &quot;%s,%s\n&quot;, $i, $(i + n)
+	}'); do
+	v.db.renamecolumn map=cdo_stations column=$old_new
+done
+</pre></div>
+
+<img src="m_cdo_download_cdo_stations.png" alt="CDO stations">
+
+<h2>SEE ALSO</h2>
+
+<em>
+<a href="m.tnm.download.html">m.tnm.download</a>
+</em>
+
+<h2>AUTHOR</h2>
+
+<a href="mailto:grass4u@gmail com">Huidae Cho</a>, New Mexico State University