Add citation guidance to tutorial

[rrohwer]

I would be really helpful if there were citation instructions in the package tutorial. I have found instructions here: https://help.waterdata.usgs.gov/faq/miscellaneous/how-to-cite-usgs-water-data-for-the-nation-waterdata.usgs.gov-in-a-publication but is is not clear how to find all the information after using the dataRetrieval package instead of searching through the website.

Thank you for considering this addition, and for the extremely helpful package! Robin

[rrohwer]

And I might add, it would be more helpful to see an example in .bib format as opposed to just an example citation, since most people use citation managers. OK thanks again!

[ldecicco-USGS]

Yeah, the old tutorial that had that information was moved recently. Here's the same information:

https://rconnect.usgs.gov/NMC_dataRetrieval_1/dataRetrieval_1.html#/dataretrieval-citation

The normal documentation does have this: https://doi-usgs.github.io/dataRetrieval/authors.html#citation But since that page is autogenerated, I don't think I can edit it to include how to cite NWIS and WQP directly.

You can get a BibTeX format for the dataRetrieval package like this:

citation("dataRetrieval")
To cite dataRetrieval in publications, please use:

  De Cicco, L.A., Hirsch, R.M., Lorenz, D., Watkins, W.D.,
  Johnson, M., 2023, dataRetrieval: R packages for
  discovering and retrieving water data available from
  Federal hydrologic web services, v.2.7.13,
  doi:10.5066/P9X4L3GE

A BibTeX entry for LaTeX users is

  @Manual{,
    author = {Laura DeCicco and Robert Hirsch and David Lorenz and David Watkins and Mike Johnson},
    title = {dataRetrieval: R packages for discovering and retrieving water data available from U.S. federal hydrologic web services},
    publisher = {U.S. Geological Survey},
    address = {Reston, VA},
    version = {2.7.13},
    institution = {U.S. Geological Survey},
    year = {2023},
    doi = {10.5066/P9X4L3GE},
    url = {https://code.usgs.gov/water/dataRetrieval},
  }
# or:
utils::toBibtex(citation("dataRetrieval"))

However I know that's not what you need when you are citing NWIS and WQP.

There is an attribute "queryTime" to any dataRetrieval results that will let you accurately construct the NWIS/WQP citations:

rawDailyQ <- readNWISdv("04085427", "00060",  "2012-01-01", "2012-06-30")
attr(rawDailyQ, "queryTime")
[1] "2024-01-15 13:29:56 CST"
attr(rawDailyQ, "url")
[1] "https://waterservices.usgs.gov/nwis/dv/?site=04085427&format=waterml,1.1&ParameterCd=00060&StatCd=00003&startDT=2012-01-01&endDT=2012-06-30"

NWIScitation <- paste0(
"U.S. Geological Survey, ",
format(attr(rawDailyQ, "queryTime"), "%Y"),
", National Water Information System data available on the World Wide Web (USGS Water Data for the Nation), accessed ",
format(attr(rawDailyQ, "queryTime"), "%b %d, %Y"),
", at http://waterdata.usgs.gov/nwis/. http://dx.doi.org/10.5066/F7P55KJN")
NWIScitation
"U.S. Geological Survey, 2024, National Water Information System data available on the World Wide Web (USGS Water Data for the Nation), accessed Jan 15, 2024, at http://waterdata.usgs.gov/nwis/. http://dx.doi.org/10.5066/F7P55KJN"

or WQP:

SC <- readWQPqw(siteNumbers = "USGS-05288705", parameterCd = "00300", convertType = FALSE)
WQPcitation <- paste0("National Water Quality Monitoring Council, ",
                      format(attr(SC, "queryTime"), "%Y"),
                      ", Water Quality Portal, accessed ",
                      format(attr(SC, "queryTime"), "%m, %d, %Y"),
                      ", ",
                      attr(SC, "url"), 
                      ", https://doi.org/10.5066/P9QRKUVJ.")
[1] "National Water Quality Monitoring Council, 2024, Water Quality Portal, accessed 01, 15, 2024, https://www.waterqualitydata.us/data/Result/search?siteid=USGS-05288705&pCode=00300&mimeType=tsv&zip=yes, https://doi.org/10.5066/P9QRKUVJ."

But yeah, we should get that information back in one of the tutorial docs on the main documentation page.