Package 'GMSE'

The name of the landscape being changed

The name of the original landscape replacing

The layer that is being affected on the landscape

The resources array produced by the resource function within GMSE

The landscape array on which interactions between resources and agents occur

The vector of parameters that hold global and dynamic parameter values used by GMSE

The array of agents produced in the main gmse() function

The type of resources being observed (default = 1)

Minimum age of the resource being sampled (default = 1)

The type of agent doing the observing (default = 0)

The category of agent type (first 4 columns) doing observing; this will almost always be 1, so type 0 agents (managers, of which there is always one by default) will be affected

Whether or not agents are moved during the run of anecodtal

The type of model being applied (Currently only individual-based – i.e., 'agent-based' – models are allowed)

The observation array produced by the observation function within GMSE

The array of agents produced in the main gmse() function

The resources array produced by the resource function within GMSE

The landscape array on which interactions between resources and agents occur

The vector of parameters that hold global and dynamic parameter values used by GMSE

The distance within which agents are able to observe resources on the landscape

The number of times that resources are observed in the observation model of GMSE

The resources array produced by the resource function within GMSE

The array of resource observations from the observation model, used to estimate abundance of resources

The first layer of the 3D landscape array, which indicates values of terrain for plotting (as of now, terrain values have no effect on the simulation and only exist for display purposes)

The full list showing all layers of the landscape in each time step of GMSE

The third layer of the 3D landscape array, which indicates agent ownership of the land

The array of agents produced in the main gmse() function

The vector of parameters that hold global and dynamic parameter values used by GMSE

A three dimensional array of agent (manager and stakeholder) actions

A three dimensional array of cost values for agent (manager and stakeholder) actions

The distance that an agent can see on a landscape

The number of times that resources are sampled per time step

The resources array produced by the resource function within GMSE

The array of resource observations from the observation model, used to estimate abundance of resources

The first layer of the 3D landscape array, which indicates values of terrain for plotting (as of now, terrain values have no effect on the simulation and only exist for display purposes)

The full list showing all layers of the landscape in each time step of GMSE

The third layer of the 3D landscape array, which indicates agent ownership of the land

The array of agents produced in the main gmse() function

The vector of parameters that hold global and dynamic parameter values used by GMSE

A three dimensional array of cost values for agent (manager and stakeholder) actions

A three dimensional array of agent (manager and stakeholder) actions

The array of resource observations from the observation model, used to estimate abundance of resources

The vector of parameters that hold global and dynamic parameter values used by GMSE

The agents array holding agents' information

The landscape on which some cells are owned

Column in which the total number of owned cells in AGENTS is added

Layer of the landscape array where ownership information is held

Column in which the ID of an agent is held in the AGENTS array

The array of resource observations from the observation model, used to estimate abundance of resources

The vector of parameters that hold global and dynamic parameter values used by GMSE

This parameter determines the distance around an agent's location within which it can observe resources.

The landscape array on which interactions between resources and agents occur

This value sets the maximum number of time steps for a simulation. There are no constraints for length of time that a simulation can run. The default is 40 time steps.

This value sets the number of cells on the x dimension of the landscape (i.e., the number of columns in the landscape array; this can also be thought of as the x-axis when the landscape image is plotted). There is no maximum, but the minimum dimension of a landscape is 2 cells. The default is 100 cells.

This value sets the number of cells on the y dimension of the landscape (i.e., the number of columns in the landscape array; this can also be thought of as the y-axis when the landscape image is plotted). There is no maximum, but the minimum dimension of a landscape is 2 cells. The default is 100 cells.

This value determines how far resources move during a time step. Exact movement is probabilistic and partly affected by 'res_move_type' settings. Under default settings, during each time step, resources move from zero to res_movement cells away from their starting cell in any direction. Hence res_movement is the maximum distance away from a resources starting cell that it can move in a time step; other types of resource movement, however, interpret res_movement differently to get the raw distance moved (see res_move_type). The default value is 20.

This value is the density-independent and user-independent probability of a resource being removed (e.g., dying) during a time step in the resource model. Under default settings, this value is set to zero, with resource removal being determined entirely by carrying capacity on resource survival, and by user actions.

This value is the baseline population growth rate of resources. Each resource in the simulation produces Poisson(lambda) offspring in one time step within the resource model. The value of lambda might be increased or decreased by user actions, and juvenile survival can potentially be decreased by a carrying capacity placed on birth. The default value is 0.3, meaning that the average resource produces one offspring every three time steps.

This value determines how far agents (managers and stakeholders) can see on the landscape. At the moment, this affects only the sampling ability of managers in the observation model for density-based and transect-based estimates of resource abundance. In these types of estimates, when managers have a higher agent_view, they are capable of observing a larger area of landscape and therefore of getting a larger (in the case of density-based estimation) or more efficient (in the case of transect-based estimation) sample of resources from which to estimate total resource abundance. The default value of agent_view is 10, so agents can see 10 cells away from their current cell in any direction.

This value determines how far agents can move. At the moment, this does not affect much in the simulation because agent movement does not affect agent actions (interactions with resources can be limited to stakeholder's owned land, but do not currently depend on where an agent is on the landscape – effectively assuming that agents are mobile enough to do what they want to do to resources). The one exception is for density-based estimation, which can be biased by low values of agent_move by causing the manager to sample the same (or nearby) landscape cells to estimate total resource abundance; if resources are spatially autocorrelated, then managers might over or under-estimate total abundance. Therefore, as a default, this value is set to 50 so that managers can move to any cell on a (torus) landscape in a time step, removing any bias for density sampling.

This value is the carrying capacity on new resources added per time step (e.g., birth). If more offspring are born in a time step than res_birth_K, then offspring are randomly removed from the population until offspring born equals res_birth_K. By default, carrying capacity is effectively applied to death instead of birth, so the default value of res_birth_K is set to 100000 (and hence not enacted because the number of births is never this high).

This value is the carrying capacity on resources in the population. Carrying capacity is realised by an increase in mortality probability as resource abundance approaches res_death_K. In each time step, realised mortality probability equals the number of resources over carrying capacity divided by the number of resources (i.e., [resource count - carrying capacity] / resource count). Hence, as the resource abundance increases above carrying capcity, mortality probability also increases in proportion, generating some stochasticity in resource survival. Note that carrying capacity is independent of user actions; if a user culls a resource this culling is applied after mortality probability due to carrying capacity has already been calculated. The default value for res_death_K is 2000.

This determines what happens at the edge of the landscape. Currently there is only one option (value 1), which causes the landscape to wrap around as a torus (effectively removing the edge); resources that leave off of one side of the landscape will reappear on the other side of the landscape.

This determines the type of movement that resources do. There are four different movement options: (0) No movement – resources are sessile, (1) Uniform movement in any direction up to 'res_movement' cells away during a time step. Movement direction is random and the cell distance moved is randomly selected from zero to 'res_movement'. (2) Poisson selected movement in the x and y dimensions where distance in each direction is determined by Poisson(res_movement) and direction (e.g., left versus right) is randomly selected for each dimension. This type of movement tends to look a bit odd with low 'res_movement' values because it results in very little diagonal movement. It also is not especially biologically realistic, so should probably not be used without a good reason. (3) Uniform movement in any direction up to 'res_movement' cells away during a a time step 'res_movement' times. In other words, the 'res_movement' variable of each resource is acting to determine the times that a resource moves in a time step and the maximum distance it travels each time it moves. This type of movement has been simulated in ecological models, particularly plant-pollinator systems. The default movement type is (1).

The type of resource addition (birth) that occurs. Currently, the only value allowed is 2, which causes all resources to produce Poisson(lambda) offspring each time step, where 'lambda' is the population growth rate also set as an argument in gmse simulations.

The type of resource removal (death) that occurs. A value of (1) causes death to be entirely density-independent and with a probability of 'removal_pr' for each resource (which may be further affected by agent actions or interactions with landscape cells). A value of (2) causes death to be entirely density-dependent (though potentially independently affected by agents and landscape), with mortality probability calculated based on the carrying capacity 'res_death_K' set in as an argument in gmse simulations. A value of (3) allows for both density-dependent (affected by 'res_death_K') and density-independent (affected by 'removal_pr') effects on resource removal. The default 'res_death_type' is (2); values of (1) must be used carefully because it can result in exponential growth that leads to massive population sizes that slow down simulations.

The type of observation sampling of resources being done by managers in the observation model. There are currently four options for sampling. (0) Density-based sampling, in which managers sample all resources within some subset of the landscape; the size of this subset is all of the resources within a distance of 'agent_view' from the cell of the manager. Managers sample 'times_observe' subsets, where 'times_observe' is a parameter value set in the gmse simulation. Managers then extrapolate the density of resources in the subset to estimate the total number of resources on a landscape. (1) Mark-recapture estimate of the popluation, in which managers randomly sample 'fixed_mark' resources (without replacement) in the population without any spatial bias (if there are fewer than 'fixed_mark' resources, managers sample all resources). The manager then randomly samples 'fixed_recapt' resources (without replacement), again without any spatial bias. A Chapman estimate is then used in the manager model to estimate population size from these mark-recapture data. (2) Transect-based sampling (linear), in which a manager samples an entire row of the landscape and counts the resources on the row, then moves onto the next row of the landscape until the entire landscape has been covered. The number of cells in each row (i.e., the height) equals 'agent_view', so fewer transects are needed if agents can see farther. If 'res_move_obs == TRUE', then resources can move on the landscape between each transect sampling, potentially causing observation error if some resources are double counted or not counted at all due to movement. If 'res_move_obs == FALSE', then this type of observation should produce no error, and resource estimation will be exact. (3) Transect-based sampling (block), in which a manager samples a block of the landscape and counts the resources in the block, then moves on to the next (equally sized) block until the entire landscape has been covered. Blocks are square, with the length of each side equaling 'agent_view', so fewer blocks are needed if agents can see farther. If 'res_move_obs == TRUE', then resources can move on the landscape between each block sampling, potentially causing observation error if some resources are double counted or not counted at all due to movement. If 'res_move_obs == FALSE', then this type of observation should produce no error, and resource estimation will be exact. The default observation type is 0 for density-based sampling.

This parameter affects mark-recapture observation (i.e., applies only when observe_type == 1). Its value defines how many resources will be marked in each time step as part of a mark-recapture population size estimate.

This parameter affects mark-recapture observation (i.e., applies only when observe_type == 1). Its value defines how many resources will be (re)captured in each time step as part of a mark-recapture population size estimate.

This parameter defines how many times a manager will make observations within the observation model; it applies only to density-based sampling ('observe_type = 0') and mark-recapture sampling ('observe_type = 1'). In the former case, the value determines how many times the manager goes out to sample resources from a subset of the landscape. In the latter case, the value determines how many times the manager goes out to attempt to find new resources to mark or recapture (hence its value must be greater than 'fixed_observe').

This determines the type of movement that agents do. The four different movement types of agents are identical to those of resources: : (0) No movement – agents are sessile, (1) Uniform movement in any direction up to 'agent_move' cells away during a time step. Movement direction is random and the cell distance moved is randomly selected from zero to 'agent_move'. (2) Poisson selected movement in the x and y dimensions where distance in each direction is determined by Poisson(agent_move) and direction (e.g., left versus right) is randomly selected for each dimension. This type of movement tends to look a bit odd with low 'agent_move' values because it results in very little diagonal movement. It also is not especially realistic, so should probably not be used without a good reason. (3) Uniform movement in any direction up to 'agent_move' cells away during a a time step 'agent_move' times. In other words, the 'agent_move' variable of each agent is acting to determine the times that an agent moves in a time step and the maximum distance it travels each time it moves. This type of movement has been simulated in ecological models, particularly plant-pollinator systems. The default movement type is (1).

This value defines the minimum age at which resources are recorded and acted upon by agents; below this age, resources are ignored. The default value of this parameter is 0. Note that the population might appear to go over carrying capacity regularly because carrying capacity is not realised until the next resource model if it applies to the death of resource (this is not a problem for the simulation itself, it just needs to be noted). If the value is set to 1, then offspring just produced during a time step (age = 0) are not observed or acted upon by agents.

This is a TRUE or FALSE value that defines whether or not resources are to move between 'times_observe' times being observed. The default value is TRUE, but if the option is set to FALSE then it shuts down all resource movement during sampling (making 'observe_type = 2' and 'observe_type = 3' error free).

This is a TRUE or FALSE value that defines whether distance in the simulation should be judged as number of cells away or the actual Euclidean distance between points (e.g., if the landscape were interpreted as a map). The default is set to FALSE, and until GMSE is capable of reading in real-world maps, I don't think there is any good reason to set it to TRUE.

This is a TRUE or FALSE value that determines whether or not the simulation results will be plotted. The default is TRUE. If plotted, then a function is called to show the dynamics of resources and agent actinos over time. The plotted function plots the dynamics of GMSE resource, observation, managemer, and user models in six separate sub-panels. (1) Upper left panel: Shows the locations of resources on the landscape (black dots); landscape terrain is also shown in brown, but at the moment, this is only cosmetic and does not reflect anything occurring in the model. (2) Upper right panel: Shows ownership of land by agents; land is divided proportional based on parameters set in gmse() and colours correspond with other subplots. If agent utilities and actions are restricted to land ('land_ownership' in the gmse() function), then this gives some idea of where actions are being performed and where resources are affecting the landscape. (3) Middle left panel: Shows the actual population abundance (black solid line) and the population abundance estimated by the manager (blue solid line) over time. The dotted red line shows the resource carrying capacity (death-based) and the dotted blue line shows the target for resource abundance as set in the gmse() function; the orange line shows the total percent yield of the landscape (i.e., 100 percent means that resources have not decreased yield at all, 0 percent means that resources have completely destroyed all yield). (4) Middle right panel: Shows the raw landscape yield for each stakeholder (can be ignored if 'land_ownership' is FALSE) over time; colours correspond to land ownership shown in the upper right panel. (5) Lower left panel: The cost of stakeholders performing actions over time, as set by the manager. (6) Lower right panel: The total number of actions performed by all stakeholders over time.

This is a TRUE or FALSE value that determines whether the simulation will be halted each time step after 'start_hunting' time steps to ask the user how many resources they want to hunt (some management information is given to help make this choice). This feature will be expanded upon in later versions. Right now, the human is playing the role of agent number 2, the first stake-holder in the simulation. By default, this value is set to FALSE.

The time step in which the human (*not* the simulated agent) is allowed to start hunting if 'hunt = TRUE'. The default value is 95.

The fraction of remaining biomass (e.g. crop production) that a resource consumes while occupying a landscape cell. The default value is 0.5, so if one resource occupies the cell, then landscape production is halved, if two resources occupy the cell, then landscape production drops to 0.25; if three, then production drops to 0.125, etc.

The size of populations of agents in the genetic algorithm (not resources in the simulation). The actions of each agent in the simulation are duplicated 'ga_popsize' times, and this population of individual agent actions undergoes a process of natural selection to find an adaptive strategy. Selection is naturally stronger in larger populations, but a default population size of 100 is more than sufficient to find adaptive strategies.

The minimum number of generations in the genetic algorithms of the simulation (*not* the number of time steps in the simulation itself). The actions of each agent in the simulation are duplicated 'ga_popsize' times, and this population of individual agent actions undergoes a process of natural selection at least 'ga_mingen' times to find an adaptive strategy. If convergence criteria 'converge_crit' is set to a default value of 100, then the genetic algorithm will almost always continue for exactly 'ga_mingen' generations. The default value is 40, which is usually plenty for finding adaptive agent strategies – the objective is not to find optimal strategies, but strategies that are strongly in line with agent interests.

At the start of each genetic algorithm, 'ga_popsize' replicate agents are produced; 'ga_seedrep' of these replicates are *exact* replicates, while the rest have random actions to introduce variation into the population. Because adaptive agent strategies are not likely to change wildly from one generation to the next, it is highly recommended to use some value of 'ga_seedrep' greater than zero; the default value is 20, which does a good job of finding adaptive strategies.

In the genetic algorithm, fitnesses are assigned to different agent strategies and compete in a tournament to be selected into the next generation. The tournament samples 'ga_sampleK' strategies at random and with replacement from the population of 'ga_popsize' to be included in the tournament. The default value is 20.

In the genetic algorithm, fitnesses are assigned to different agent strategies and compete in a tournament to be selected into the next generation. The tournament samples 'ga_sampleK' strategies at random and with replacement from the population of 'ga_popsize' to be included in the tournament, and from these randomly selected strategies, the top 'ga_chooseK' strategies are selected. The default value is 2, so the top 10 percent of the random sample in a tournament makes it into the next generation (note that multiple tournaments are run until 'ga_popsize' strategies are selected for the next generation).

In the genetic algorithm, this is the mutation rate of any action within an agent's strategy. When a mutation occurs, the action is either increased or decreased by a value of 1. If the action drops below zero, then the value after mutation is multiplied by -1.

In the genetic algorithm, this is the crossover rate of any action within an agent's strategy with a randomly selected different strategy in the population of size 'ga_popsize'.

This is a TRUE or FALSE value that defines whether or not agents should move at the end of each time step. The default value is TRUE.

This is the maximum age of resources. If resources reach this age, then they are removed in the resource model with a probability of 1. The default 'max_ages' is 5.

This is the mimimum cost of any action in the manager and user models. Higher values allow managers to have greater precision when setting policy. For example, managers believe (typically correctly) that they will double culling number by setting the cost of culling at 1 instead of 2. If actions always cost at least some minium value, then some increment just above that value is always available to more precisely affect user actions. Hence it is generally better to simply give everyone a bigger budget and set a minimum cost, giving more precision to managers to fine tune policy. The default value of minimum_cost is therefore set to 10.

This is the total budget of each stakeholder for performing actions. The cost of performing an action is determined by the 'miminimum_cost' of actions, and the policy set by the manager. The default 'user_budget' is 1000. The maximum budget is 100000.

This is the total budget for the manager when setting policy. Higher budgets make it easier to restrict the actions of stakeholders; lower budgets make it more difficult for managers to limit the actions of stakeholders by setting policy. The default 'manager_budget' is 1000. The maximum budget is 10000.

This is the target resource abundance that the manager attempts to keep the population at; the default value is 1000.

This is the initial abundance of resources at the start of the simulation; the default is 1000.

This is a TRUE or FALSE value determining whether or not scaring is an option for managers and stakeholders. If so, then stakeholders that scare cause resources to be moved from their current landscape cell to a random cell on the landscape (note, it is possible that the resource could be scared back onto the stakeholder's own land again). The default value of this is FALSE.

This is a TRUE or FALSE value determining whether or not culling is an option for managers and stakeholders. If so, then stakeholders that cull cause the resource to be removed from the simulation permanently (i.e., killing the resource). The default value of this is TRUE.

This is a TRUE or FALSE value determining whether or not castration is an option for managers and stakeholders. If so, then stakeholders that castrate do not remove the resource from the simulation, but prohibit the resource from reproducing by setting its 'lambda' value to zero. The default value of this is FALSE.

This is a TRUE or FALSE value determining whether or not feeding is an option for managers and stakeholders. If so, then stakeholders that feed increase a resource's growth rate (lambda) for one time step by 100 percent. The default value of this is FALSE.

This is a TRUE or FALSE value determining whether or not feeding is an option for managers and stakeholders. If so, then stakeholders that help_offspring increase a resource's offspring production for one time step by one (i.e., one more offspring is produced). The default value of this is FALSE.

This is a TRUE or FALSE value determining whether or not tending crops on the landscape is allowed for stakeholders. If so, then stakeholders can increase one cells yield by 50 percent for each action to 'tend_crops'. Actions on the landscape cannot be regulated by managers, so the cost of this action is always 'minimum_cost'. The default value of this is FALSE.

The per landscape cell proportional increase in crop yield when stakeholders take one action to increase yield on their landscape. The default value is set to 0.5 (i.e., a 50 percent increase in yield on a cell).

This is a TRUE or FALSE value determining whether or not killing crops on the landscape is allowed for stakeholders. If so, then stakeholders can remove the crop yield on a cell completely for each action to 'kill_crops'. Actions on the landscape cannot be regulated by managers, so the cost of this action is always 'minimum_cost'.

This is the number of stakeholders in a simulation; there is always one manager, plus any natural number of stakeholders.

This value moderates the caution a manager has when changing policy by assuming that at least 'manage_caution' of each possible action will always be performed by stakeholders. I manager will therefore not ignore policy for one action because no stakeholder is engaging in it; the default value of 'manage_caution' is 1.

This value defines whether stakeholders own land and their actions are restricted to land that they own. If FALSE, then stakeholders can act on any landscape cell; if TRUE, then agents can only act on their own cells. The default of this value is FALSE.

This is the frequency with which policy is set by managers; a value of 1 means that policy is set in the manager model every time step; a value of 2 means that poilcy is set in the manager model every other time step, etc. The default value is 1.

This is the convergence criteria for terminating a genetic algorithm. After continuing for the minimum number of generations, ‘ga_mingen', the genetic algorithm will terminate if the convergence criteria is met. Usually making this criteria low doesn’t do much to improve adaptive strategies; the default value is 1, which means that the genetic algorithm will continue as long as there is greater than a 1 percent increase in strategy fitness.

This adjusts the sensitivity that a manager assumes their actions have with respect to changes in costs (their policy). For example, given a default 'manage_sense' value of 0.9, if the cost of culling resources doubles, then instead of a manager assuming the the number of culled resources per user will be cut in half, the manager will instead assume that the number of resources culled will be cut by one half times eight tenths. As a general rule, a value of ca 0.8 allows the manager to predict stake-holder responses to policy accurately; future versions of GMSE could allow managers to adjust this dynamically based on simulation history.

The proportion of the landscape that will be public, and not owned by stakeholders. The remaining proportion of the landscape will be evenly divided among stakeholders. Note that this option is only available when land_ownership == TRUE. The default value is 0.

If TRUE, all users will have identical actions; the genetic algorithm will find actions for one user and copy them for all users. This is a useful option if a lot of users are required but variation among user decisions can be ignored. The default value is FALSE.

The age below which resources are incapable of reproducing. The default value is 1.

This specifies a range around the value of ‘user_budget', such that the expected value of each user’s budget will be 'user_budget', with a uniform distribution plus or minus 'usr_budget_rng'. Note that the minimum 'usr_budget_rng' allowed is 1 regardless of the range set, and the maximum is always 100000. The default value for this argument is 0.

A value for the deviation of the estimated population from the manager target, below which manager will not update the policy. Recommended values are between 0 and 1, with the default value being 0.

A percentage of the initial budget manager will receive if policy was not updated last time step. Corresponds to the time, energy and money saved by waiting for a better time to update the policy. Budget bonuses are cumulative, so many time steps of not updating policy can cause a compounding increase in the budget bonus. The default value is 0.

This value defines the amount of yield on a landscape that an individual resource need to consume in a timestep to survive. The default value is 0 (i.e., no consumption is required for survival).

This value defines the amount of yield on a landscape that an individual resource need to produce one offspring. Resources will produce as many offspring as is possible given their yield in take; e.g., if a resource consumes between three and four times the amount of yield required for reproduction, then they will produce three offspring. The default value is 0 (i.e., no consumption is required for reproduction).

Number of searches that resources are allowed per time step for feeding on the landscape. Resources will move between times feeding based on whatever 'res_movement' and 'res_move_type' parameters are specified.

Defines the extent to which the amount of land ownership allocated among users varies when 'land_ownership = TRUE'. A default value of 0 places roughly equal landscape ownership, while increasing values (must be < 1) cause an exponential distribution of land ownership cell allocation.

For a focal user, the perceived effect of scaring one resource on the total number of resources affecting the user (e.g., if -1, then the user perceives scaring as removing the equivalent of one resource from their land; NA by default, and calculated from other argument inputs).

For a focal user, the perceived effect of culling one resource on the total number of resources affecting the user (e.g., if -1, then the user perceives culling as removing the equivalent of one resource; NA by default, and calculated from other argument inputs).

For a focal user, the perceived effect of castrating one resource on the total number of resources affecting the user (e.g., if -1, then the user perceives castration as removing the equivalent of one resource; NA by default, and calculated from other argument inputs).

For a focal user, the perceived effect of feeding one resource on the total number of resources affecting the user (e.g., if 1, then the user perceives feeding as adding the equivalent of one resource; NA by default, and calculated from other argument inputs).

For a focal user, the perceived effect of helping the offspring of one resource on the total number of resources affecting the user (e.g., if 1, then the user perceives helping offspring as adding the equivalent of one resource; NA by default, and calculated from other argument inputs).

For a focal user, the perceived effect of tending to crops on one cell of owned landscape the user's total crop yield (e.g., if 1, then the user perceives tending crop to increase crop yield on one of their landscape cells by 1; NA by default, and calculated from other argument inputs).

For a focal user, the perceived effect of destroying the crops on one cell of owned landscape on the user's total crop yield (e.g., if -1, then the user perceives killing crop to reduce their total crop yield on a landscape cell by 1; unlike other perceived actions, this is not additive. The value defines that absolute effect on crop yield predicted at a single cell, so -1 assumes a 100 per cent loss of yield. This is NA by default).

An increase in user budget caused by yield on their owned cells. The value of this parameter is multiplied by the user's total yield to get the user's budget increment (default 0). This argument can take any real value, but user budgets are always restricted to being between 1 and 100000. Where yield adjustments result in budgets < 1, the actual budget is set to 1. And where yield adjustments result in budgets > 100000, the actual budget is set to 100000.

An increase in manager budget caused by mean yield on user owned cells. The value of this parameter is multiplied by the users' mean total yield to get the manager's budget increment (default 0). This argument can take any real value, but manager budgets are always restricted to being between 1 and 100000. Where yield adjustments result in budgets < 1, the actual budget is set to 1. And where yield adjustments result in budgets > 100000, the actual budget is set to 100000.

A boolean parameter triggering the memorization of last time step's population size observation

A boolean parameter. Default TRUE: bonus is reset to zero after a time step of policy update. FALSE: reset to zero only when the costs decreased last time step.

A boolean parameter. Determines if the manager feeds the evolutionary algorithm with a prediction of population trajectory (TRUE) or the regular latest observation (FALSE). Default FALSE.

Determines whether simulated annealing should be used in place of the genetic algorithm for agent decision-making. If TRUE, then simulated annealing is used for users. If FALSE, then the genetic algorithm is used.

Determines whether simulated annealing should be used in place of the genetic algorithm for agent decision-making. If TRUE, then simulated annealing is used for managers If FALSE, then the genetic algorithm is used.

Sets the maximum value of iterations for the simulated annealing algorithm

Sets the magnitude of the maximum mutation in the genetic algorithm in terms of how many actions that an agent tries increases or decreases (e.g., mutation causes 1 to mu_magnitude more or fewer culling actions)

The function specifying the resource model. By default, the individual-based resource model from gmse is called with default parameter values. User-defined functions must either return an unnamed matrix or vector, or return a named list in which one list element is named either 'resource_array' or 'resource_vector', and arrays must follow the format of GMSE in terms of column number and type (if there is only one resource type, then the model can also just return a scalar value).

The function specifying the observation model. By default, the individual-based observation model from gmse is called with default parameter values. User-defined functions must either return an unnamed matrix or vector, or return a named list in which one list element is named either 'observation_array' or 'observation_vector', and arrays must follow the format of GMSE in terms of column number and type (if there is only one resource type, then the model can also just return a scalar value).

The function specifying the manager model. By default, the individual-based manager model that calls the genetic algorithm from gmse is used with default parameter values. User-defined functions must either return an unnamed matrix or vector, or return a named list in which one list element is named either 'manager_array' or 'manager_vector', and arrays must follow the (3 dimensional) format of the 'COST' array in GMSE in terms of column numbers and types, with appropriate rows for interactions and layers for agents (see documentation of GMSE for constructing these, if desired). User defined manager outputs will be recognised as costs by the default user model in gmse, but can be interpreted differently (e.g., total allowable catch) if specifying a custom user model.

The function specifying the user model. By default, the individual-based user model that calls the genetic algorithm from gmse is used with default parameter values. User-defined functions must either return an unnamed matrix or vector, or return a named list in which one list element is named either 'user_array' or 'user_vector', and arrays must follow the (3 dimensional) format of the 'ACTION' array in GMSE in terms of column numbers and types, with appropriate rows for interactions and layers for agents (see documentation of GMSE for constructing these, if desired).

How the output should be organised. The default 'basic' attempts to distill results down to their key values from submodel outputs, including resource abundances and estimates, and manager policy and actions. An option 'custom' simply returns a large list that includes the output of every submodel. Any other option (e.g. 'none') will return a large list with all of the input, output, and parameters used to run gmse_apply. This list will also include a list element named 'basic_output', which will display the default results.

A an existing list of results from gmse_apply, produced by setting 'get_res = TRUE' to be included in the function. The parameter and data structures from the previous run will be applied to the new run of gmse_apply, thereby making it easy to loop multiple generations. Additional arguments passed to '...' will over-ride those stored in the old list, allowing global parameter values to be updated (e.g., sub-models used, management options, genetic algorithm parameters). Note that if these arguments are passed, the function will attempt to work with them even if it means removing previous list elements (e.g., if a new number of stakeholders is passed through stakeholder = new_value, then an entirely new AGENT array and user and manager arrays will need to be built).

Arguments passed to user-defined functions, and passed to modify default parameter values that would otherwise be called for gmse default models. Any argument that can be passed to gmse can be specified explicitly, just as if it were an argument to gmse. Similarly, any argument taken by a user-defined function should be specified, though the function will work if the user-defined function has a default that is not specified explicitly.

The full list as returned by the gmse function.

An existing gmse_apply_summary output structure to append to. This should be a matrix with number of columns equal to the length of 'include'. If NULL, a matrix with a single row with just the summary of given 'data' gmse_apply() output is returned.

A character vector listing which gmse_apply values should be reported/summarised. Currently allowable values are "res","obs","culls","scares","castrations","feeds","helps","tend_crops", "kill_crops","cull_cost","scare_cost", and "yield". Note that for all actions and yield, the statistic returned is the sum across users; for cull_cost and scare_cost the returned values are the mean costs across users. Can be NULL; if so, if 'output' is also NULL, all possible values are returned. If 'output' is not NULL, only the values already present in 'ouput' are returned, in the same column order.

The number of replicate simulations to be run

Passes to gmse_table. If TRUE, then results from all time steps of the simulation are returned; if FALSE (default), then only results from the last time step of each simulation is returned.

Passes to gmse_table. If TRUE (default), then action options (e.g., scaring, culling, etc.) that are not available are not included in the results summary. If FALSE, then they are included as 'NA'

Parameter values to be passed to the gmse function

The full list as returned by the gmse function

The output of a 'gmse' simulation.

Whether or not to hide results from policy options when creating the resulting table. If 'TRUE' (default), then policy and user actions that are not allowed in a simulation will not be placed as columns. If 'FALSE', then these columns will be placed with values of 'NA'.

Whether or not results from each time step from the simulation should be individually placed as a row in the resulting table ('TRUE' by default). If 'FALSE', then only the last row will be placed.

A single time step of resources from GMSE

The landscape array on which interactions between resources and agents occur

The type of model being applied (Currently only individual-based – i.e., 'agent-based' – models are allowed)

This is the number of agents that are set in the model; agent number does not change during the simulation, and each agent has a unique ID

A vector of how many agents there are of each type (element). The sum of this vector needs to equal the agent_number so that each agent can correctly be assigned a type. Currently, GMSE assumes that there are only two types of agents: managers (type 0) and stakeholders (type 1), and only one manager exists. Future versions of GMSE will allow for different options as requested.

This parameter affects the movement of agents each time step. There are multiple types of movement (see obs_move_type in the gmse function), but this parameter determines the distance in cells that an agent will move. Agent movement is generally less important than resource movement, and typically does not affect how agents interact with resources

This parameter determines the distance around an agent's location within which it can observe resources. This is relevant for some (but not not all) types of observation in the observation model, particularly for density-based estimation (observe_type = 0 in the gmse() function).

The number of rows (y-axis) on the simulated landscape; agents are randomly placed somewhere on the landscape array

The number of columns (x-axis) on the simulated landscape; agents are randomly placed somewhere on the landscape array

This is a TRUE or FALSE value determining whether or not scaring is an option for managers and stakeholders. If so, then stakeholders that scare cause resources to be moved from their current landscape cell to a random cell on the landscape (note, it is possible that the resource could be scared back onto the stakeholder's own land again). The default value of this is FALSE.

This is a TRUE or FALSE value determining whether or not culling is an option for managers and stakeholders. If so, then stakeholders that cull cause the resource to be removed from the simulation permanently (i.e., killing the resource). The default value of this is TRUE.

This is a TRUE or FALSE value determining whether or not castration is an option for managers and stakeholders. If so, then stakeholders that castrate do not remove the resource from the simulation, but prohibit the resource from reproducing by setting its 'lambda' value to zero. The default value of this is FALSE.

This is a TRUE or FALSE value determining whether or not feeding is an option for managers and stakeholders. If so, then stakeholders that feed increase a resource's growth rate (lambda) for one time step by 100 percent. The default value of this is FALSE.

This is a TRUE or FALSE value determining whether or not feeding is an option for managers and stakeholders. If so, then stakeholders that help_offspring increase a resource's offspring production for one time step by one (i.e., one more offspring is produced). The default value of this is FALSE.

This is a TRUE or FALSE value determining whether or not tending crops on the landscape is allowed for stakeholders. If so, then stakeholders can increase one cells yield by 50 percent for each action to 'tend_crops'. Actions on the landscape cannot be regulated by managers, so the cost of this action is always 'minimum_cost'. The default value of this is FALSE.

This is a TRUE or FALSE value determining whether or not killing crops on the landscape is allowed for stakeholders. If so, then stakeholders can remove the crop yield on a cell completely for each action to 'kill_crops'. Actions on the landscape cannot be regulated by managers, so the cost of this action is always 'minimum_cost'.

For a focal user, the perceived effect of scaring one resource on the total number of resources affecting the user

For a focal user, the perceived effect of culling one resource on the total number of resources affecting the user

For a focal user, the perceived effect of castrating one resource on the total number of resources affecting the user

For a focal user, the perceived effect of feeding one resource on the total number of resources affecting the user

For a focal user, the perceived effect of helping the offspring of one resource on the total number of resources affecting the user

For a focal user, the perceived effect of tending to crops on one cell of owned landscape the user's total crop yield

For a focal user, the perceived effect of destroying the crops on one cell of owned landscape on the user's total crop yield

This adjusts the sensitivity that a manager assumes their actions have with respect to changes in costs (their policy). For example, given a 'manage_sense' value of 0.9, if the cost of culling resources doubles, then instead of a manager assuming the the number of culled resources per user will be cut in half, the manager will instead assume that the number of resources culled will be cut by one half times eight tenths. As a general rule, a value of ca 0.8 allows the manager to predict stake-holder responses to policy accurately; future versions of GMSE could allow managers to adjust this dynamically based on simulation history.

This value is the baseline population growth rate of resources. Each resource in the simulation produces Poisson(lambda) offspring in one time step within the resource model. The value of lambda might be increased or decreased by user actions, and juvenile survival can potentially be decreased by a carrying capacity placed on birth. The default value is 0.3, meaning that the average resource produces one offspring every three time steps.

The fraction of remaining biomass (e.g. crop production) that a resource consumes while occupying a landscape cell. The default value is 0.5, so if one resource occupies the cell, then landscape production is halved, if two resources occupy the cell, then landscape production drops to 0.25; if three, then production drops to 0.125, etc.

How much from a landscape does an individual resource need to produce one offspring (default 0)?

The per landscape cell proportional increase in crop yield when stakeholders take one action to increase yield on their landscape. The default value is set to 0.5 (i.e., a 50 percent increase in yield on a cell).

Number of searches that resources are allowed per time step for feeding on the landscape. Resources will move between times feeding based on whatever 'res_movement' and 'res_move_type' parameters are specified.

The landscape on which some cells are owned. This needs to have been created with the make_landscape, or be a three dimensional array in which the third layer of the array corresponds to owned cells

The array of agents produced in the main gmse() function

The resources array produced by the resource function within GMSE

A binary vector produced by the GMSE function defining what types of stakeholder interactions with resources (scaring, culling, castration, feeding, help_offspring) are permitted

A binary vector produced by the GMSE function defining what types of stakeholder interactions with the landscape (tend_crops, kill_crops) are permitted

The minimum cost that any agent (stakeholder or manager) incurrs for performing one action. This value is also set as an option in the main gmse() function (minimum_cost). This cost is recommended to be set to a value of 10, which gives managers increased precision when adjusting costs. For example, if the mimimum cost for a stakeholder performing an action is low, then a small change in the mimimum cost could halve or double the number of actions performed from the manager's perspective, with no options in between; hence the benefit of having a high mimimum cost combined with a higher agent budget (see the main gmse() function)

The resources array produced by the resource function within GMSE

The landscape array on which interactions between resources and agents occur

The proportion of a landscape cell that a resource consumes

The amount that a resource needs to consume to survive a time step

The amount that a resource needs to consume to produce one offspring

The number of times a resource moves to feed on a cell in a time step

The resources array produced by the resource function within GMSE

The landscape array on which interactions between resources and agents occur

The type of model being applied (Currently only individual-based – i.e., 'agent-based' – models are allowed)

The dimension of the other side of the landscape (e.g., Longitude)

The dimension of one side of the landscape (e.g., Latitude)

Scalar or vector of all possible types of landscape cells

Mean cell value (e.g., defining crop output on a cell)

Standard devation of cell values on a landscape

The maximum value of a cell

The minimum value of a cell

The number of layers in the 3D landscape (should usually be 3)

A TRUE or FALSE whether land should be owned by stakeholders

The number of stakeholders in the model that own land

The proportion of landscape cells that are not owned

Does distribution of land vary among users? >=0, <1

The type of model being applied (Currently only individual-based – i.e., 'agent-based' – models are allowed)

The total number of resources being initialised (e.g., the population size of the resource at the first time step)

The number of resource types that exist. Currently, only one resource type is recommended, but future versions of GMSE will include multiple resource types if requested

The number of rows (y-axis) on the simulated landscape; resources are randomly placed somewhere on the landscape array

The number of columns (x-axis) on the simulated landscape; resources are randomly placed somewhere on the landscape array

This parameter affects the movement of resources each time step. There are multiple types of movement (see res_move_type in the gmse function), but this parameter determines the distance in cells that a resource will move

This parameter sets the baseline probability of resource removal (death) per time step; this probability can be affected by user actions or carrying capacity, so a probability of zero does not ensure that resources will necessarily persist until the end of the simulation

This is the parameter for Poisson random sampling affecting birthrate; each resource gives birth to Poisson(lambda) offspring in the resource model

Rate at which resource consumes crops on landscape; consumption affects the landscape by decreasing values on the landscape array (which may, e.g., be interpreted as crop production being decreased), and might also affect resource demographic parameters depending on other global options set in GMSE

Maximum age allowed for a resource to be (in time steps)

Number of times a resource moves on a landscape during a single time step in search of food

The array of agents produced in the main gmse() function

The resources array produced by the resource function within GMSE

The resources array produced by the resource function within GMSE

The array of agents produced in the main gmse() function

The landscape array on which interactions between resources and agents occur

The vector of parameters that hold global and dynamic parameter values used by GMSE

A three dimensional array of cost values for agent (manager and stakeholder) actions

A three dimensional array of agent (manager and stakeholder) actions

An interaction (Jacobian) matrix of resources & landscape layer effects

Interaction table indexing types with the INTERACT matrix

The array of resource observations from the observation model, used to estimate abundance of resources

The type of model being applied (Currently only individual-based – i.e., 'agent-based' – models are allowed)

The agents array

The budget of a manager

What is the budget of a user

Uniform range of users budgets

Column where the budget is located

The resources array produced by the resource function within GMSE

The landscape array on which interactions between resources and agents occur

The vector of parameters that hold global and dynamic parameter values used by GMSE

The array of agents produced in the main gmse() function

Interaction table indexing types with the INTERACT matrix

Fixed number of individuals marked? (A number, or FALSE)

Number of times that the observations are made (e.g., managers go out sampling n times in an area of the landscape)

Minimum age of the resource being sampled (default = 1)

The type of agent doing the observing (default = 0)

The category of agent type (first 4 columns) doing observing; this will almost always be 1, so type 0 agents (managers, of which there is always one by default) will perform the observations

The type of method used to do the observing. For types of observation exist: (1) Density based observation, where observers count all of the resources within a subset of the landscape (the manager function can then later estimate total resource number from this estimate). (2) Mark-recapture based observation, where observers tag a fixed number of randomly sampled resources on the landscape some number of ‘times'; some of these resources marks are later interpreted as marks (’fixed_mark') while the rest are interpreted as recaptures. (3) Transect based observation, where observers sample a linear transect, observing all resources on the transect one row of landscape cells at a time, until all landscape cells are sampled; between samples, resources might move generating observation error. (4) Block based sampling, which is very similar to Transect based sampling; here observers instead sample square blocks of a landscape, counting resources one block at a time, until the whole landscape is sampled; between samples resources might move generating observation error.

Defines whether or not resources move during observation (default = FALSE). Note that if this is FALSE, then observation methods (observe_type) 3 and 4 produce no observation error

The type of model being applied (Currently only individual-based – i.e., 'agent-based' – models are allowed)

The number of cells on the X dimension of the landscape

The number of cells on the Y dimension of the landscape

Number of owners among which landscape cells will be divided

The amount of land that will not be owned

Does distribution of land vary among users? >=0, <1

Output from gmse to be plotted.

Output from gmse to be plotted.

The resources array produced by the resource function within GMSE

The landscape array on which interactions between resources and agents occur

The vector of parameters that hold global and dynamic parameter values used by GMSE

The type of model being applied (Currently only individual-based – i.e., 'agent-based' – models are allowed)

The resources array produced by the resource function within GMSE

The array of agents produced in the main gmse() function

The landscape array on which interactions between resources and agents occur

The vector of parameters that hold global and dynamic parameter values used by GMSE

A three dimensional array of cost values for agent (manager and stakeholder) actions

ACTION A three dimensional array of agent (manager and stakeholder) actions

An interaction (Jacobian) matrix of resources & landscape layer effects

Interaction table indexing types with the INTERACT matrix

The type of model being applied (Currently only individual-based – i.e., 'agent-based' – models are allowed)

Vector of agent IDs to use (including -1 and -2, which indicate direct actions to the landscape and resources, respectively)

The number of agents to use (length of agent_IDs)

The number of unique resource types (cols 2-4 of RESOURCES); for now, this should always be 1