Last modified 6 years ago Last modified on 2011-07-13 10:50:12

MSE Batch plugin user notes

10 Sept, 2010

13 July, 2011

Overview

The MSE Batch plugin runs the MSE (Management Strategy Evaluator) in batch mode from a command file. The command file runs the MSE changing input harvest rule parameters for each iteration and outputting data to file.

MSE parameters available through the command file.

  1. Number of MSE simulations
  2. End Year
  3. Assessment and Implementation error
  4. Primary Production forcing functions
  5. Primary Production forcing function variation
  6. Fleet Control types
    • 0 No controls imposed on fleet
    • 1 Weakset stock
    • 2 Highest value stock
    • 3 Selective fishery
  7. Harvest rules
    • Fishing Mortality
    • Total Allowable Catch
    • Target Fishing Mortality (hockey stick parameters)

How to run

Installing MSE Batch Plugin

  1. Download and latest version of EwE from the Ecopath.org website.
  2. Download and unzip the contents of MSEBatch Plugin Ver 6.2.0.713.zip into the same directory as EwE6.exe, the default setup location is "C:\Program Files\Ecopath with Ecosim 6\".
  3. Open the EwE interface and go to "Tools>Options>General" under "General option" check the "Download updates for plug-ins" and re-start EwE. This will update the MSEBatch plugin to the latest version.
  4. Open a model in EwE6 the MSE Batch plugin interface will be accessible from the Navigator tree under "Tools>Management procedures (MSE)>Output>MSE Batch"

MSE Batch interface
MSE Batch plugin interface.

Running the MSE Batch

The MSE Batch plugin interface provides a way to select command files and begin a batch run.

Select the command file using the 'Select command file..." button. Once a file has been selected it will be parsed to see if it can be run with the currently loaded EwE model and Ecosim scenario. If any errors are found in the file then an ERROR: message will shown in the output window. All errors must be fixed before the command file can run. In the case of a WARNING: message you can still run the command file however, you should address any issues that have warnings.

Once the Run has been started, by clicking the "Run" button, the output window will contain progress messages with the number of run completed out of the total. A run can be stopped by clicking the "Stop run" button. The batch process will wait for the current MSE run to completion before exiting. The output files specified in the command file will contain output for the completed runs.

MSE Batch iterations

The MSE Batch loops over Forcing Functions, Fleet Controls and Harvest Rules running the MSE for each set of parameters from the command file. Parameters not set by the command file will be left at the values loaded by the current Ecosim model.

Sample looping structure:

  For each Forcing Function 
    For each Fleet Control
      For each Harvest Rule 

        MSE run...
        WriteOuputFile...

      next Harvest Rule
    next Fleet Control
  next Forcing Function

Command file format

The command file is a CSV (coma separated values) file that contains tags. A tag is a predefined string of text that appears at the start of the line and is used to identify the line as valid input for the MSE module. After the data part of the tag there must be a least one empty entry to mark the end of the valid data. All data that appears after the empty entry will be ignored. For example

Control_File_Version,1.0,,,ignored comments,,,

Lines in the command file that do not contain a recognized tag will be ignored. This allows a command file to contain comments, notes or other non parameter information as long the line does not start with a valid tag. The order of the tags in the file is not important and the command file can contain as many lines as the user wants.

Tags

Control_File_Version

 Control_File_Version,1.0,,
  • Version number of the control file 1.0 for the current version. Used to identify parameters that may be in the file.

Model_Name

Model_Name,Some model.ewemdb,,,
  • File name of the EwE model
  • Used to check the command file against the currently loaded EwE model. If the models do not match a warning is issued.

Ecosim_Scenario

Ecosim_Scenario,Scenario1,,
  • Name of the Ecosim Scenario that the command file can work with. If the scenario name does not match a warning is issued. However, the command file can still be run.

Run_Type

Run_Type,1,,
  • Type of harvest rules to set for the current MSE Batch run. For each run of the MSE the harvest rules for the other Run_Type's will be set to zero.
  • Valid inputs,
    • 1 Fishing Mortality (Constant_F) sets the fishing mortality rates to a constant value for the run,
    • 2 Total Allowable Catch (Constant_Y) sets the catch to a constant value for the run,
    • 3 Target Fishing Mortality(Hockey stick) sets the fishing mortality using the Target Fishing Mortality rules,
    • 0 Any when this Run_Type option is set the harvest rules for other Run_Types will not be set to zero. Harvest rule values for groups not explicitly set by the command file will use the values in the currently load EwE model. This option allows for different types of harvest rules during the same MSE run.

Number_Sims

Number_Sims,50,,
  • Number of Ecosim simulation the MSE will run for each iteration. This is the 'Number of trials' parameter on the MSE run form.

Error_CV

Error_CV,0.3,,
  • Groups CV's in the MSE interface. See "Tools>Management procedures (MSE)>Input>Assessments>Group CV's"
  • Coefficient of variation for the observation and implementation error for the MSE stock assessment model.

Output_Directory

Output_Directory,C:\EwE data,,
  • Directory where the MSE batch output will be sent. The MSE batch will try to create the directory if it does not already exist.

End_Year

End_Year,-1,,
  • Last year (time step) that the harvest rules are applied during an Ecosim simulation.
  • Valid values
    • -1 Harvest rules will be applied for the complete simulation run.
    • > 0 Harvest rules will be stopped before the end of the run. For all years greater than End_Year the simulation will use the current Ecosim Fishing Effort.

PP_STDEV

PP_STDEV,0.5,,
  • One standard deviation for normal distribution of Primary Production variance.

PP

PP,1,Increasing,10,,
PP,2,Decreasing,10,,
  • Primary Production forcing function, from the currently loaded Ecosim model, to load for an MSE Batch iteration.
  • Each line in the command file loads a separate forcing function then loops over all the Fleet Controls and Harvest Rules applying the parameters from the file.
  • Valid inputs
    • Forcing function index for the currently load Ecosim model. See EwE Scientific Interface "Time dynamics (Ecoism)>Forcing function" for the currently loaded forcing functions and indexes.
    • Name of the forcing function. This is used to check the forcing function name in the file against the name in the EwE model. If they do not match then a warning will be posted but the run can still continue.
    • Ecosim group index to apply the forcing function to. Ecosim needs to know which primary production group to apply the forcing function to. If the Group index does not match a primary producer group in Ecosim then the MSE Batch will post an error and will not run.

Control_Type_INDEX & Control_Type

Control_Type_INDEX,1,2,3,,
Control_Type,2,0,0,,
Control_Type,0,2,0,,
Control_Type,0,0,2,,
  • Control types from the MSE interface. See "Tools>Management procedures (MSE)>Input>Regulatory>Control type".
  • Control_Type_INDEX and Control_Type tags need to appear in pairs. The Control_Type_INDEX is the index of the EwE fishing feet that the control will be applied to. Control_Type is the type of control that will be applied.
  • Control_Type Valid inputs.
    • 0 No controls will be imposed on the fleet.
    • 1 Weakest Stock controls will be imposed on the fleet by the stock with the greatest limitation.
    • 2 Highest Value controls will be imposed on the fleet by the stock with the highest market value, mortality rate of discards is set in "Input data>Fishery>Discard mortality rate".
    • 3 Selective fishery controls are imposed the same as Highest Value (2) except all the discards are assumed to survive.

Constant_F_INDEX & Constant_F

Constant_F_INDEX,10,,
Constant_F,0.1,,
Constant_F,0.2,,
Constant_F,0.3,,
Constant_F,0.4,,
Constant_F,0.5,,
  • Fixed fishing mortality from the MSE interface. See "Tools>Management procedures (MSE)>Inputs>Regulatory>Fixed F, Escapement,TAC"
  • Constant_F_INDEX and Constant_F tags need to appear in pairs. Constant_F_INDEX is the index of the group that the Constant_F value will apply to. Constant_F is the fishing mortality rate that will be applied for the duration of the simulation.
  • Constant_F_INDEX index of group that the F will be applied to. This only needs to include groups that are to have there quotas set. If a group index is not included then Fixed fishing mortality from the current EwE model will be used.
  • Constant_F fishing mortality on the group.

Constant_Y_INDEX & Constant_Y

Constant_Y_INDEX,10,15,,
Constant_Y,0.1,10.2,,
Constant_Y,0.2,11.2,,
Constant_Y,0.3,12.2,,
Constant_Y,0.4,13.2,,
Constant_Y,0.5,14.2,,
  • Total allowable catch from the MSE interface. See "Tools>Management procedures (MSE)>Inputs>Regulatory>Fixed F, Escapement,TAC".
  • Constant_Y_INDEX and Constant_Y tags need to appear in pairs. Constant_Y_INDEX is the group index that the Constant_Y value will be applied to. Constant_Y is the Yield that will be applied for the duration of the simulation.
  • Constant_Y_INDEX index of group that the value will be applied to. This only needs to include groups that are to have there quota set. If a group index is not included then Total allowable catch from the current EwE model will be used.
  • Constant_Y catch of the group in kg/km2/month. The MSE will set the quota on the group base on the Constant_Y value.

TFM_INDEX &TFM

TFM_INDEX,10,,
TFM,0.4,1.6,0,0.1,,,
TFM,0.4,1.6,0,0.2,,,
TFM,0.4,1.6,0,0.3,,,
  • Target fishing mortality in the MSE interface. See "Tools>Management procedures (MSE)>Inputs>Regulatory>Target fishing mortality"
  • TFM_INDEX and TFM tags need to appear in pairs. TFM_INDEX is the index of the group that the target fishing mortality harvest rule will apply to. TFM is the parameters of the rule.
  • TFM_INDEX index of group that the rule will be applied to. This only needs to include groups that are to have there quota set. If a group index is not included then target fishing mortality rate from the current EwE model will be used.
  • TFM four parameters making up the harvest rule.
    1. Biomass limit is the biomass of the group when the fishing mortality rate is at its minimum value (F Minimum).
    2. Biomass base is the biomass of the group when the fishing mortality rate is at its maximum value (F Max).
    3. F Minimum is the fishing mortality rate when the biomass is at or below Biomass limit. This is normally zero.
    4. F Max is the fishing mortality rate when biomass is greater the Biomass base. Maximum fishing mortality rate.
  • All four parameters must be supplied for each group.

Output types

Biomass_OUTPUT,1,,,
Consumption/Biomass_OUTPUT,0,,,
FeedingTime_OUTPUT,0,,,
FishingMortRate_OUTPUT,1,,,
PredationRates_OUTPUT,0,,,
CatchByGroup_OUTPUT,1,,,
  • Type of output to save for a MSE Batch run.
  • Outputs are save to the directory specified in the Output_Directory tag. The file name will be MSEBatch_{ouput type}_{Run type}_{EwE model name}.csv. So the output file for biomass with a run type of Constant F and a model name of Lab 4.ewedb will be "MSEBatch_Biomass_Constant_F_Lab 4.ewedb.csv".
  • Valid inputs.
    • 1 save the output type,
    • 0 output not saved.
  • Biomass_OUTPUT saves biomass to MSEBatch_Biomass_xxx.
  • Consumption/Biomass_OUTPUT saves consumpution/biomass to MSEBatch_QB_xxx.
  • !FeedingTime_OUTPUT saves feeding time to MSEBatch_FeedingTime_xxx.
  • !FishingMortRate_OUTPUT saves Ecopath yearly fishing mortality rate to MSEBatch_FishingMort_xxx.
  • !PredationRates_OUTPUT saves predation rate to MSEBatch_Pred_xxx.
  • !CatchByGroup_OUTPUT saves the sum of all catches on the group. This is the annual catch at the current time step or what the yearly catch would be if the biomass and F stay constant. Saves to MSEBatch_Catch_xxx.

Attachments