geanders/futureheatwaves

Functions to Identify and Characterize Heatwaves in Climate Projections

futureheatwaves's Issues

Check if we need .onLoad for Rcpp

Do we need something with .onLoad with Rcpp::loadRcppModules since we have C++ code? (See p.30 of "R Packages".)

Check if `processHistorical` is robust to directory file order

It seems like processHistorical could pull an ensemble member other than r1i1p1 if there were ever a historical ensemble member that was listed before that one in the user's climate data directory. Could that ever be the case, or is this a reasonable thing we can rely on? We could check with Dr. Barnes. If necessary, we may need to change processHistorical to grep for r1i1p1.

Can we remove `parseModel`?

I couldn't tell if it was being used anywhere. If so, let's remove it.

Allow netCDF input

This is something to do much later and will be a big fix, but it sounds like this package will be much more generalizable if we can change in input directly from netCDF files.

Default file names for `tasFilenames`, etc

Consider giving coordinateFilenames, tasFilenames, and timeFilenames defaults of our file names for gen_hw_set to make our runs easier. I don't feel strongly about this, though-- up to you, Colin.

Test custom features

Make sure that custom options for the period of projections and the reference period for thresholds work as wanted.

Change to package::function syntax

Make sure to add dplyr:: before all the dplyr functions.

Make `acquireDirectoryStructure` more robust for other users

Currently, acquireDirectoryStructure will only work for others if they have the exact same file names as we do. We should ask Dr. Barnes if this is a reasonable assumption. If not, we'll need to add an option where other users can specify the names for their final time, tas, and latitude_longitude files within each ensemble-member directory.

Consider making the threshold percentile a variable

Ultimately, if we did that, it would need to make it through to processHistorical and get into the probs arguments of the apply function with quantile there.

Address TODOs

TODOs still linger in nooks and crannies. Resolve them.

Fix referenceBounds argument for `gen_hw_set`

Right now, it looks like the package requires this to be a length-4 vector, if you're going to use it. It's currently required to have the following format: c(historical low bound, historical high bound, reference low bound, reference high bound).

This argument should allow the user to specify one and only one period to use as a reference when calculating relative temperature characteristics of heatwave. If it's not FALSE, it should have the following restrictions (that I can think of so far):

• should be a vector of length 2
• both values should be some form of numeric
• should not span historic and future projection periods (i.e., if one value is pre-2005, both must be)

Ensure we're following all suggestions for C++ code in packages

Check against suggestions at: http://r-pkgs.had.co.nz/src.html.

Create warning message that function writes new files

CRAN's usually picky about allowing packages that write new files and / or directories to the users computer, which we're doing. I think we at least need to have a message near the start of the create.heatwave.dataset function that tells the user that it will be writing new files and make the user choose to go forward with the function.

How to use ID heatwaves option for main

Uncomment zzz.R

There's a problem with Rcpp in R that won't let you use document while you have an .onLoad like we do here, so keep this commented out until we're done documenting the package, and then we can add back on. (This shouldn't be a problem when CRAN builds, just a problem with syncing up Rcpp and devtools.

Confim we have `createHwDataframe` if we are including RorCpp option

I couldn't find the function for identifying heatwaves under the R option of RorCPP.

Add funding support information if possible

Fix this error with `rcpDirs`

Error in data.frame(modelName, length(rcpDirs)) :
object 'rcpDirs' not found
6 data.frame(modelName, length(rcpDirs))
5 rbind(modelInfoAccumulator, newElement) at main.R#215
4 accumulators("append model information", data.frame(modelName,
length(rcpDirs))) at process.R#37
3 FUN(X[[i]], ...)
2 lapply(X = X, FUN = FUN, ...)
1 sapply(models, processModel, global, custom, accumulators)

Pick license

See if Colin is alright with an MIT license. If so, edit DESCRIPTION and add LICENSE file.

Only read `tas` for relevant grid points and times

We might be able to speed up processEnsemble a lot if we could find a way to have R only read in tas for the grid points and times we want.

`check_params` should not return `coordinateFilenames`...

... if there are no errors generated when running that function. Currently, if it's successful, it prints out this filename.

Confirm stable email address for Colin.

Change the DESCRIPTION file if the current email address will not be valid post-graduation.

Altered parameters of entry point function

Altered the parameters of the entry point function. This requires corresponding alteration in the parameter checking function.

`gen_hw_set` still sensitive to missing `/` at end of `out`

It no longer throws an error if you forget to put / at the end of the out directory name, but it doesn't put things in the right directory. Instead it pastes Heatwaves and Thresholds directory to the out name, so it creates multiple subdirectories in the parent directory of whatever you specified with out.

Change acceptable RCP bounds in `checkCustomBounds`

Currently, the RCP period has to have a lower year > = 2061 and an upper year <= 2080. This is too narrow-- we could have any years where we have data for the RCP projections (e.g., mid-21st century should be fine). Check dates of RCP data next time we have time dataframe read in and fix checks in checkCustomBounds to reflect all years CMIP generally has projection data for. (Also, check with Dr. Barnes-- will all CMIP model outputs have the same year range?)

Maps

Figure out whether to discard or keep the mapping functions. They are currently incomplete.

Check future end date default in `getBounds`

Is it pulling through Dec. 30 2080, or Dec. 30 2081? If the first, then is the Dec. 30 2004 default working correctly for the historical option of that function?

Acquire Directory Structure

Dr. Anderson,

There seems to be a problem in the acquireDirectoryStructure function. I'm a bit fatigued right now. I was wondering if you could take a look. This is the message:

Warning message:
In matrix(unlist(split_all), ncol = 4, byrow = TRUE) :
data length [1303] is not a sub-multiple or multiple of the number of rows [326]

It's a warning, not an error, but the end result of the function is an empty list.

Bug in C++ id heatwaves function

Identifying heatwaves at values below the cutoff threshold.

Return values

I just remembered that R functions always returns the last expression evaluated. Therefore, all functions have return values. How should the documentation reflect functions whose return values are not meant to be used? Additionally, what return values should a function have if it is one of those functions?

For gen_hw_set (the newly renamed 'main' function), I could just return a success or fail flag (0 or 1).

Keep the R / C++ option?

We'll need to decide if we want to keep the C++ option. Are you using it now, or did you not get around to integrating it with the main functions? I think, especially if we want to put this on CRAN, we'd need to do some special things if we're including C++ code (not a huge problem, just something to think about).

writeThresholds

Dr. Anderson,

Some time ago you instructed me to make the program output some of the thresholds for either each model or each ensemble. I believe this was for debugging purposes. Do you remember what this was about?

This question pertains to the writeThresholds function in IO.R. It is not implemented properly and I am not sure how it should be implemented.

We have `IDheatwavesR` in two places. Remove one.

Currently, it's in IDHeatwavesForCountry.R and extraidhw.R. I think we could probably remove the extraidhw.R, because it looks like there's already some documentation with the function definition in IDHeatwavesForCountry.R.

Change `parameterErrorChecking` to take out `setwd`

Let's see if we can use dir.exists here instead. That way we wouldn't be changing the user's environment.

Closure documentation

Dr. Anderson,

How do you think the closure functions should be documented?

Check that the `mode` for `dir.create` calls are what we want

This is all in IO.R, I think.

Confirm typo in roxygen2 documentation for `gen_hw_set`

We had, for the parameter RorCPP, that it ran R if the parameter was 1 and C++ if it was 0. I think I wrote this into the documentation, but now I'm thinking that I had it reversed and it should be 0 to run R and 1 to run C++. If it was correct to fix this as a type, would you close this issue?

Start time for historical

We're currently pulling starting Jan. 1, 1981 for the historical thresholds. Do we want to start there or Jan. 1, 1980? Check Keith's paper to be consistent with that.

`all` necessary in `preparation.R` functions?

I think that we're just passing the all object through a bunch of the functions in preparation.R without ever using it. I think we could lose it.

Document bcc1 example data

Notes from Dr. Barnes to incorporate:

From what I can tell its use is "unrestricted" (see here: http://cmip-pcmdi.llnl.gov/cmip5/availability.html). BTW, bcc1 stands for "Beijing Climate Center, China Meteorological Administration", so it the Chinese model.

Can we remove `plyr` from Imports?

I think we are now no longer using plyr, but double-check before we take it off the Imports list in DESCRIPTION.

Add another heatwave definition

Before we publish, we'll want to show how to pop in a different heatwave definition. This will require creating a function with an alternative heatwave definition and also documenting how to exchange it with the default definition.

Pull request limitation

Dr. Anderson,

Github only seems to be letting me issue a single pull request at a time. I have pending updates for the C++ part. You probably noticed that I did not merge your updates with mine before submitting the request. Let me know if you want me to merge your updates with my version and resubmit the pull request.

Have a function add trailing backslash rather than throw error

For the dataFolder variable, we can change one of the functions to check for the last backslash and add it if it doesn't exist, rather than returning an error.

Re-think `checkCustomBounds`

We need to work on this function some once we figure out exactly how we're going to use the custom time boundary values within the code. Right now it's doing some contradictory things, like failing if anything is not class 'double', but then later checking if some of the same things are FALSE-- you'd never get to the code checking for the FALSE if it were FALSE.

See, for example:

    # Check if bounds are the correct type
    if(typeof(histLow) != "double" | typeof(histHigh) != "double"){
      stop("Invalid type: histLow or histHigh. Stopping.")
    }
    if(typeof(rcpLow) != "double" | typeof(rcpHigh) != "double"){
      stop("Invalid type: rcpLow or rcpHigh. Stopping.")
    }

    # Check if bounds are in the correct range
    if(histLow != FALSE){
      if(histLow < 1981){
        stop(paste("Custom boundaries for threshold calculation fall out",
                   "of acceptable range. Stopping."))
      }
    }

    if(histHigh != FALSE){
      if(histHigh > 2004){
        stop(paste("Custom boundaries for threshold calculation fall out",
                   "of acceptable range. Stopping."))
      }
    }

I think it's best to wait and re-work until after we've figured out exactly how we want the boundary objects to work throughout the code.

Create smaller example dataset

I think we need to pick a few grid locations for the climate data sample we're currently using and limit our example data for the package to the climate data for those few grid points. The current data is way to big to include with a package we'd post online. I'd suggest we pick two grid points near East Coast cities (maybe near NYC and DC?) and then also limit our cities data to just the cities closest to those grid points in the climate data.

Add Description to DESCRIPTION

We'll probably want to do this pretty near the end.

Add package versions to DESCRIPTION

Add as current versions of packages we're using, e.g.:

dplyr (>= 0.4.3)

Make this change in DESCRIPTION when we list these under Imports:

Decide if we need a different way to measure distance

We'll want to look at the maps linking cities to grid points to see if we think we need to use something fancier than the Pythagorean theorem to calculate distances to find closest grid point to each community. Maybe great-circle distance? The maps should indicate whether our approximation is reasonable, at least for the US and for distances typical for climate grids.

Confirm maintainer

Check with Colin and confirm which of us will maintain the package. Change DESCRIPTION if necessary.