---
title: "Using Legacy Newhall v1.6.1 Routines"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using Legacy Newhall v1.6.1 Routines}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  # skip 1.6.1 vignette in R CMD check on GHA
  eval = FALSE,
  collapse = TRUE,
  comment = "#>"
)
```

This vignette demonstrates setting a custom `jNSMR.JAR_SUFFIX` to force use of the legacy Java Newhall Model (version 1.6.1; released 2016/02/10). See official download here: https://www.nrcs.usda.gov/resources/education-and-teaching-materials/java-newhall-simulation-model-jnsm.

Before we load the library, set the `jNSMR.JAR_SUFFIX` option to indicate which JAR to load. The attach message indicates the JAR version loaded.

```{r setup, eval=FALSE}
options(jNSMR.JAR_SUFFIX = "-1.6.1")
library(jNSMR)
```

### Run the BASIC simulation model

Create a _NewhallDataset_ with `xml_NewhallDataset()` or `NewhallDataset()` and associated _NewhallDatasetMetadata_ with `NewhallDatasetMetadata()`.

```{r, eval=FALSE}
library(jNSMR)

# read single-station XML file (NewhallDataset + NewhallDatasetMetadata)
input_xml_file <- system.file("extdata/WILLIAMSPORT_1930_1930_input.xml", 
                              package = "jNSMR")[1]
input_xml <- xml_NewhallDataset(input_xml_file)

# or specify inputs directly to the constructor
input_direct <- NewhallDataset(stationName = "WILLIAMSPORT",
                               country = "US",
                               lat = 41.24,
                               lon = -76.92,
                               elev = 158.0,
                               allPrecipsDbl = c(44.2,40.39,113.54,96.77,95.0,98.55,
                                                 66.04,13.46,54.86,6.35,17.53,56.39),
                               allAirTempsDbl = c(-2.17,0.89,3.72,9.11,16.28,21.11,
                                                  22.83,21.94,19.78,10.5,5.33,-1.06),
                               pdbegin = 1930,
                               pdend = 1930,
                               smcsawc = 200.0)

# set minimal _NewhallDatasetMetadata_ for our constructed _NewhallDataset_
input_direct$setMetadata(NewhallDatasetMetadata(stationName = "WILLIAMSPORT"))
```

### Run single model from file or R object

```{r}
# run single model (from XML file--only with v1.6.1 JAR)
output_xml <- newhall_simulation(input_xml)

# run single model (from direct input)
output <- newhall_simulation(input_direct)
```

### Access references to Java objects containing results

Here we demonstrate how to use the `NewhallResults` object from `newhall_simulation()` to get various formatted statistics, calendars and other output from a single run of the model.


#### Moisture and temperature regime statistics


```{r, eval=FALSE}
cat(output$getFormattedStatistics())
```

    #> Number of Cumulative Days that the Moisture Control Section (MCS) is:
    #>   During one year is:
    #>     Dry: 67
    #>     MoistDry: 88
    #>     Moist: 205
    #>   When soil temp is above 5°C:
    #>     Dry: 48
    #>     MoistDry: 58
    #>     Moist: 118
    #> Highest number of consecutive days that the MCS is:
    #>   Moist in some parts:
    #>     Year: 293
    #>     Temp over 8°C: 166
    #>   Dry after summer solstice: 22
    #>   Moist after winter solstice: 105

#### Moisture calendar

```{r, eval=FALSE}
cat(output$getFormattedMoistureCalendar())
```

    #> 222222222222222333333333333333
    #> 333333333333333333333333333333
    #> 333333333333333333333333333333
    #> 333333333333333333333333333333
    #> 333333333333333333333333333333
    #> 333333333333333333333333333333
    #> 333333333333333333333333333333
    #> 333333333322222222222222222222
    #> 222222222222222222222222222222
    #> 222222221111111111111111111111
    #> 111111111111111111111111111111
    #> 111111111111111222222222222222

#### Temperature calendar

```{r}
cat(output$getFormattedTemperatureCalendar())
```

    #> ------------------------------
    #> ------------------------------
    #> ------------------------------
    #> ------------555555555588888888
    #> 888888888888888888888888888888
    #> 888888888888888888888888888888
    #> 888888888888888888888888888888
    #> 888888888888888888888888888888
    #> 888888888888888888888888888888
    #> 888888888888888888888888888888
    #> 88888888888888555555555555----
    #> ------------------------------

### Support for Newhall XML format for input and output


`newhall_XMLStringResultsExporter()` returns a character vector with XML based on an input and an output object.

```{r, eval=FALSE}
# inspect XML result format
cat(newhall_XMLStringResultsExporter(input_xml, output))
```

    #> <?xml version="1.0" encoding="UTF-8"?>
    #> <model>
    #>   <metadata>
    #>     <stninfo>
    #>       <nettype>HCN</nettype>
    #>       <stnname>WILLIAMSPORT</stnname>
    #>       <stnid />
    #>       <stnelev>158.0</stnelev>
    #>       <stateprov>PA</stateprov>
    #>       <country>US</country>
    #>     </stninfo>
    #>     <mlra>
    #>       <mlraname />
    #>       <mlraid>0</mlraid>
    #>     </mlra>
    #>     <cntinfo>
    #>       <cntper>
    #>         <firstname>FirstName</firstname>
    #>         <lastname>LastName</lastname>
    #>         <title>Researcher</title>
    #>       </cntper>
    #>       <cntorg>My Organization</cntorg>
    #>       <cntaddr>
    #>         <address />
    #>         <city />
    #>         <stateprov />
    #>         <postal />
    #>         <country />
    #>       </cntaddr>
    #>       <cntemail />
    #>       <cntphone />
    #>     </cntinfo>
    #>     <notes>
    #>       <note>gaps filled by interpolation of neighboring stations</note>
    #>     </notes>
    #>     <rundate>20230723</rundate>
    #>     <nsmver>1.6.1</nsmver>
    #>     <srcunitsys>english</srcunitsys>
    #>   </metadata>
    #>   <input>
    #>     <location>
    #>       <lat>41.24</lat>
    #>       <lon>-76.92</lon>
    #>       <usercoordfmt>DD</usercoordfmt>
    #>     </location>
    #>     <recordpd>
    #>       <pdtype>normal</pdtype>
    #>       <pdbegin>1930</pdbegin>
    #>       <pdend>1930</pdend>
    #>     </recordpd>
    #>     <precips>
    #>       <precip id="Jan">44.2</precip>
    #>       <precip id="Feb">40.39</precip>
    #>       <precip id="Mar">113.54</precip>
    #>       <precip id="Apr">96.77</precip>
    #>       <precip id="May">95.0</precip>
    #>       <precip id="Jun">98.55</precip>
    #>       <precip id="Jul">66.04</precip>
    #>       <precip id="Aug">13.46</precip>
    #>       <precip id="Sep">54.86</precip>
    #>       <precip id="Oct">6.35</precip>
    #>       <precip id="Nov">17.53</precip>
    #>       <precip id="Dec">56.39</precip>
    #>     </precips>
    #>     <airtemps>
    #>       <airtemp id="Jan">-2.17</airtemp>
    #>       <airtemp id="Feb">0.89</airtemp>
    #>       <airtemp id="Mar">3.72</airtemp>
    #>       <airtemp id="Apr">9.11</airtemp>
    #>       <airtemp id="May">16.28</airtemp>
    #>       <airtemp id="Jun">21.11</airtemp>
    #>       <airtemp id="Jul">22.83</airtemp>
    #>       <airtemp id="Aug">21.94</airtemp>
    #>       <airtemp id="Sep">19.78</airtemp>
    #>       <airtemp id="Oct">10.5</airtemp>
    #>       <airtemp id="Nov">5.33</airtemp>
    #>       <airtemp id="Dec">-1.06</airtemp>
    #>     </airtemps>
    #>     <smcsawc>200.0</smcsawc>
    #>     <soilairrel>
    #>       <ampltd>0.66</ampltd>
    #>       <maatmast>1.2</maatmast>
    #>     </soilairrel>
    #>   </input>
    #>   <output>
    #>     <smrclass>Ustic</smrclass>
    #>     <strclass>Mesic</strclass>
    #>     <subgrpmod>Wet Tempustic</subgrpmod>
    #>     <awb>13.12</awb>
    #>     <swb>-218.22</swb>
    #>     <smcstates>
    #>       <cumdays>
    #>         <yrdry>67</yrdry>
    #>         <yrmd>88</yrmd>
    #>         <yrmst>205</yrmst>
    #>         <bio5dry>48</bio5dry>
    #>         <bio5md>58</bio5md>
    #>         <bio5mst>118</bio5mst>
    #>       </cumdays>
    #>       <consdays>
    #>         <yrmst>293</yrmst>
    #>         <bio8mst>166</bio8mst>
    #>         <smrdry>22</smrdry>
    #>         <wtrmst>105</wtrmst>
    #>       </consdays>
    #>     </smcstates>
    #>     <pets>
    #>       <pet id="Jan">0.0</pet>
    #>       <pet id="Feb">1.49</pet>
    #>       <pet id="Mar">11.44</pet>
    #>       <pet id="Apr">38.55</pet>
    #>       <pet id="May">90.93</pet>
    #>       <pet id="Jun">127.6</pet>
    #>       <pet id="Jul">142.1</pet>
    #>       <pet id="Aug">126.57</pet>
    #>       <pet id="Sep">96.94</pet>
    #>       <pet id="Oct">39.95</pet>
    #>       <pet id="Nov">14.39</pet>
    #>       <pet id="Dec">0.0</pet>
    #>     </pets>
    #>     <calendars>
    #>       <tempcal>
    #>         <stlt5>
    #>           <beginday>1</beginday>
    #>           <endday>102</endday>
    #>         </stlt5>
    #>         <st5to8>
    #>           <beginday>103</beginday>
    #>           <endday>112</endday>
    #>         </st5to8>
    #>         <stgt8>
    #>           <beginday>113</beginday>
    #>           <endday>314</endday>
    #>         </stgt8>
    #>         <st5to8>
    #>           <beginday>315</beginday>
    #>           <endday>326</endday>
    #>         </st5to8>
    #>         <stlt5>
    #>           <beginday>327</beginday>
    #>           <endday>360</endday>
    #>         </stlt5>
    #>       </tempcal>
    #>       <moistcal>
    #>         <moistdry>
    #>           <beginday>1</beginday>
    #>           <endday>15</endday>
    #>         </moistdry>
    #>         <moist>
    #>           <beginday>16</beginday>
    #>           <endday>220</endday>
    #>         </moist>
    #>         <moistdry>
    #>           <beginday>221</beginday>
    #>           <endday>278</endday>
    #>         </moistdry>
    #>         <dry>
    #>           <beginday>279</beginday>
    #>           <endday>345</endday>
    #>         </dry>
    #>         <moistdry>
    #>           <beginday>346</beginday>
    #>           <endday>360</endday>
    #>         </moistdry>
    #>       </moistcal>
    #>     </calendars>
    #>   </output>
    #> </model>
    #> 

### XML File Output

This writes the "direct" input _NewhallDataset_ (`input_direct`) and result _NewhallResult_ (`output`) to an XML file with format as above. 

```{r, eval=FALSE}
# write XML results to file
newhall_XMLResultsExporter(dataset = input_direct,
                           result = output,
                           pathname = "misc/WILLIAMSPORT_1930_1930_export.xml")
```

### Graphical User Interface for individual runs via _newhall-1.6.1.jar_

`newhall_GUI()` is convenience method to open the Newhall GUI (single runs in v1.6.1 only) with the R package.

```{r, eval=FALSE}
newhall_GUI()
```

## Detaching the Package

If you need to switch back and forth between different versions of the model JAR file within a single R session, you will need to `detach()` the package and unset any options such as `jNSMR.JAR_SUFFIX` before reloading with a new JAR. 

```{r, eval=FALSE}
detach("package:jNSMR")
options(jNSMR.JAR_SUFFIX = NULL)
```
