Using Legacy Newhall v1.6.1 Routines

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.

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().

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

# 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

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

cat(output$getFormattedMoistureCalendar())

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

Temperature calendar

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.

# 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.

# 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.

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.

detach("package:jNSMR")
options(jNSMR.JAR_SUFFIX = NULL)

- Detaching the Package