crssi_create_cmip_nf_files: Create CRSS natural flow input files from CMIP data
In rabutler/CRSSIO: Package to Manage the Input and Output of CRSS Data

Description Usage Arguments Details Value Examples

crssi_create_cmip_nf_files() creates individual trace files for CRSS from a netcdf file containing CMIP based natural flow data.

1 2	crssi_create_cmip_nf_files(iFile, oFolder, startYear, endYear = 2060, scenarioNumber, oFiles = nf_file_names(), overwriteFiles = FALSE)

`iFile`	Path to netcdf file containing the CMIP based natural inflow data. See 'Details'.
`oFolder`	Path to the top level directory where the trace folders and input files will be created. This folder should exist before using this function.
`startYear`	The year to start the trace files in. Data will be trimmed to start in this year.
`endYear`	The final year of data the trace files will contain.
`scenarioNumber`	The scenario number used as an identifier in CRSS. See 'Details.'
`oFiles`	The CRSS natural inflow file names to use for the individual traces files.
`overwriteFiles`	A boolean that determines whether or not the function should overwrite existing files. See 'Details'.

crssi_create_cmip_nf_files() will create individual trace files named by the oFiles argument for all traces that exist in iFile. Individual trace folders, e.g., trace1, trace2, traceN, are created for all traces found in iFile. iFile should be a netcdf file that contains a variable called naturalFlow. If it does not, then the function will error. The netcdf file should contain a 3-dimensional array in (trace, gageNumber, time) format.

The CMIP data currently exists for 1950 - 2099. If the user specifies years outside of this range, the function will abort. Because CRSS needs data to start in the year that the CRSS simulations begin, this function trims the data based on startYear and endYear, and correctly formats the trace files to begin in January of startYear and end in December of endYear.

scenarioNumber is specified by the user and is saved to the slot specified by the "crssio.supplyScenarioSlot" option. The following maps supply scenario names to the scenario numbers that should be used here. (See the CRSS model documentation for more details on the scenario number.) This function will error if the scenarioNumber provided is 1, 2, or 3 as these data are not created with this function.

1 = Observed Resampled
2 = Direct Paleo Resampled
3 = Paleo-conditioned
4 = CMIP3 Downscaled GCM Projected
5 = CMIP5 Downscaled GCM Projected, BCSD downscaling, quantile mapping secondary bias correction

In addition to the scenario number, the trace number, the hydrology increment, and the Sacramento Year Type index are created for each trace. The names of these slots are controlled by the "crssio.traceNumberSlot", "crssio.hydroIncrement", and "crssio.sacYTSlot" options, respectively. The Sacramento Year Type index is stored in the netcdf file with the natural flow files, and is created from a regression of a river gage in the Sacramento Basin. See the CRSS documentation for more details. Finally, a README file is created in oFolder that provides some metadata on the creation of the trace files.

oFiles sets the individual file names for the natural inflow locations. If you do not use nf_file_names(), oFiles should contain 29 strings: one for each of the natural inflow locations, and should be specified in the default order corresponding to the gages in nf_gage_names().

overwriteFiles allows the user to control whether existing files within the trace folders should be overwritten (default is they are not).

iFile is invisibly returned as the main purpose of the function is to write many files.

## Not run: 
crssi_create_cmip_nf_files(
  "cmip5_bcsd.nc",
  oFolder = "c:/model/CRSS/dmi/cmip5",
  startYear = 2018,
  endYear = 2060,
  overwriteFiles = TRUE
)

## End(Not run)