3  Build an OM Object

This chapter describes the process to create an OM object and explore some of its properties.

3.1 Initialize OM

The OM() function is used to create a new Operating Model object (see ?OM). The contents of the OM can be specified with arguments to the OM function:

SimpleOM <- OM("Example OM",
  nYear = 30,
  pYear = 20,
  nSim = 48
)

or by using functions matching the names of the slots in the object.

For example, here we’ll change the number of independent stochastic simulations in our OM from the default nSim=48 to a small number so that the code runs very quickly:

nSim(SimpleOM)
[1] 48
nSim(SimpleOM) <- 5
nSim(SimpleOM)
[1] 5

Similarly, the number of historical years and projection years can be changed:

nYear(SimpleOM) <- 20
pYear(SimpleOM) <- 10

3.2 Years and Seasons

CurrentYear is the last historical year before the projections begin, and is automatically set to the current calendar year:

CurrentYear(SimpleOM)
[1] 2025

This can be over-written using either the CurrentYear argument in OM() or by assigning a new value to the SimpleOM object with CurrentYear():

CurrentYear(SimpleOM) <- 2020

The Years function can be used to return the values of the historical or projection years:

Years(SimpleOM, 'H') 
 [1] 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015
[16] 2016 2017 2018 2019 2020
Years(SimpleOM, 'P') 
 [1] 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030

Unless specified otherwise, operating models are constructed using annual time steps. Seasonality can be added to the model by assigning a value to the Seasons slot of the OM object:

Seasons(SimpleOM) <- 4 # 4-quarters
Years(SimpleOM, "H") |> head(8)
[1] 2001.000 2001.247 2001.496 2001.748 2002.000 2002.247 2002.496 2002.748

As shown above, Seasons changes the values of the historical and projection years into decimal years corresponding with the specified number of seasons within a year.

Avoid using assigning values with @

Almost all openMSE objects have been developed using the R S4 system.

S4 objects contain slots, named components of the object that can be accessed using the @ operator (this is analogous to using the $ symbol to access contents of S3 objects), for example:

slotNames(SimpleOM)
 [1] "Name"        "Agency"      "Author"      "Email"       "Region"     
 [6] "Latitude"    "Longitude"   "Sponsor"     "nSim"        "nYear"      
[11] "pYear"       "CurrentYear" "Stock"       "Fleet"       "Obs"        
[16] "Imp"         "Data"        "DataLag"     "CatchFrac"   "Allocation" 
[21] "EFactor"     "Complexes"   "SexPars"     "Relations"   "Interval"   
[26] "nReps"       "pStar"       "maxF"        "Seed"        "Seasons"    
[31] "Years"       "Control"     "Misc"        "Log"         "Source"     
SimpleOM@nSim
[1] 5

The @ symbol can be used to assign new values to slots, for example:

SimpleOM@nSim <- 5

However, while earlier versions of openMSE advocated using the @ symbol to access slots and assign new values, this practice is not recommended for openMSE 2.0.

Instead, users are encouraged to use the accessor and assignment functions that have been developed for each object class.

This is especially important when assigning new values, where the assignment functions may have side effects that will be missed if the @ symbol is used for assigning new values to an object.

For example, consider the Seasons assignment function:

`Seasons<-`
function(x, value) {
  CheckClass(x)
  x@Seasons <- value
  x@Years <- CalcYears(x@nYear, x@pYear, x@CurrentYear, x@Seasons)
  x
}
<bytecode: 0x000001d6ff1167e8>
<environment: namespace:MSEtool>

Note that in addition to assigning the new value to the Seasons slot, the Seasons assignment function also recalculates the values for the Years slot, a step that would have been missed if the new value was assigned directly using the @ symbol and would lead to unexpected errors.

If required, the lubridate package can be used to convert decimal years into dates (and back again):

SimpleOM |>
  Years() |>
  lubridate::date_decimal() |>
  lubridate::as_date() |>
  head()
[1] "2001-01-01" "2001-04-01" "2001-07-01" "2001-09-30" "2002-01-01"
[6] "2002-04-01"
Important

The Seasons value in the OM defines the number of historical and projection time steps, as well as the structure of the age classes for all stocks in the OM.

The accounting in openMSE always starts at the beginning of the first historical year (i.e., Years(SimpleOM)[1]) and moves sequentially through the annual or seasonal time steps in Years(SimpleOM).

All stocks must have the same time units as the OM. See the Ages section below for an example.

Additionally, because it is used to set up the time and age structure of the model, the Seasons value should not be changed once an operating model is constructed.

3.3 OM Metadata

3.4 Other Contents of the OM Object

OM objects can contain one or more Stock objects.