--------------------- In Situ Lake Temperature Database ------------------------
------------------------ Grant Number NA21OAR4590177 ---------------------------
--------- Email Troy Sorensen with any questions at trsoren@umich.edu ----------
-------------------------- Last Updated 08/09/2023 -----------------------------

  This directory contains water temperature data from a variety of in situ
sources for many large lakes across North America from 2000 through 2022. 
Some lakes have multiple observing platforms at different locations, and some 
platforms record temperatures at multiple depths. Some data is accessed through 
files that are downloaded in this directory, while other data is accessed
via API.
  This database was developed by Troy Sorensen, research assistant within the 
School of Environment and Sustainability at University of Michigan.
Our project was funded through NOAAs Joint Technology Transfer Initiative. The
purpose of our research was to evaluate lake temperature representation within
NOAAs operational weather models, and this database was developed to provide 
validation data for this purpose. It is being published to provide a cohesive
dataset of lake temperatures for other researchers to use for their own lake
temperature validation studies. 
  All code included in this database was written by Troy Sorensen on MacOS 
using R version 4.2.1 and the R package dataRetrieval_2.7.11. 
  
  
The organization of this directory is as follows:  

  
raw_data/:
  This directory contains the raw downloaded water temperature data in whatever
  format it was originally received in. The directory is divided into 
  subdirectories for each lake. Note that there is not a directory in raw_data 
  for many of the lakes in this database; this is because many lakes data were
  obtained via API using the dataRetrieval package.
The following lakes are included in raw_data:
	- champlain
	- flathead
	- mcconaughy
	- mead
	- mendota
	- mono
	- oneida
	- pontchartrain
	- pyramid
	- sebago
	- tahoe
	- washington
	- winnipesaukee
      
    
final_data/: 
  This directory contains subdirectories for each lake in the database. 
  Each lake subdirectory contains the following items:
  data/:
    This subdirectory contains csv files with data for each water temperature 
    sensor on the lake. There is a unique csv file for each location and depth.
    Files are named according to the convention ABCXX_YY.csv, where ABC is a 
    three letter code for the lake, XX is a unique 2-digit identifier for the 
    latitude/longitude location of the site, and YY is a 2-digit identifier for 
    the depth of that sensor. 
    Every csv follows the same format with 2 columns: a "dateTime"" column with 
    the date and time of the observation in UTC, and a "temp" column with the 
    temperature in degrees Celsius. This data is recorded at the highest 
    temporal resolution available for any given sensor.
  lake_metadata.csv:
    Each row of this file contains metadata on the sensors listed in the "data" 
    subdirectory. The file contains 4 columns: "name", "depth(m)", "lat", "lon".
    "name" is the name of the csv file within "data" for this sensor. 
    "depth" is the depth of this sensor in meters.
    "lat" and "lon" are the decimal coordinates of this sensor.
  lake.R:
    This is the R script that was used to read the raw temperature data from
    raw_data/ or via API and convert it to the common csv format detailed above.
    See this file to see the data source for this lake. Note that if the user 
    does not alter the file paths specified in the script, then each script must
    be run from the base directory. 
The following lakes are included in final_data with the corresponding codes:
	- champlain       CHA
	- clear           CLE
	- devils          DEV
	- flathead        FLA
	- great salt      GSL
	- houston         HOU
	- lewisville      LEW
	- malheur         MAL
	- marion          MAR
	- mcconaughy      MCC
	- mead            MEA
	- mendota         MEN
	- mono            MON
	- okeechobee      OKE
	- oneida          ONE
	- pontchartrain   PON
	- pyramid         PYR
	- red             RED
	- sakakawea       SAK
	- sebago          SEB
	- seneca          SEN
	- tahoe           TAH
	- tawakoni        TAW
	- upper klamath   UPK
	- utah            UTA
	- walker          WAL
	- washington      WAS
	- winnebago       WIN
	- winnipesaukee   WIP
    
    
scripts/:
  This directory contains two example scripts for working with this data. 
  merge_metadata.R reads the lake_metadata.csv file for each lake and merges
  them all into one single csv file with a column for each sensor. 
  Plot_all_data plots all of the data in this database in a single plot to give
  an overview of the data availability and quality for each lake.