Module simuOpt

Module simuOpt provides a function simuOpt.setOptions to control which simuPOP module to load, and how it is loaded, and a class simuOpt.Params that helps users manage simulation parameters.

When simuPOP is loaded, it checkes a few environmental variables (SIMUOPTIMIZED, SIMUALLELETYPE, and SIMUDEBUG) to determine which simuPOP module to load, and how to load it. More options can be set using the simuOpt.setOptions function. For example, you can suppress the banner message when simuPOP is loaded and require a minimal version of simuPOP for your script. simuPOP recognize the following commandline arguments

--optimized

Load the optimized version of a simuPOP module.

--gui=None|batch|interactive|True|wxPython|Tkinter

Whether or not use a graphical toolkit and which one to use. --gui=batch is usually used to run a script in batch mode (do not start a parameter input dialog and use all default values unless a parameter is specified from command line or a configuraiton file. If --gui=interactive, an interactive shell will be used to solicit input from users. Otherwise, simuPOP will try to use a graphical parameter input dialog, and falls to an interactive mode when no graphical Toolkit is available. Please refer to parameter gui for simuOpt.setOptions for details.

class params.Params provides a powerful way to handle commandline arguments. Briefly speaking, a Params object can be created from a list of parameter specification dictionaries. The parameters are then become attributes of this object. A number of functions are provided to determine values of these parameters using commandline arguments, a configuration file, or a parameter input dialog (using Tkinter or wxPython). Values of these parameters can be accessed as attributes, or extracted as a list or a dictionary. Note that the Params.getParam function automatically handles the following commandline arguments.

-h or --help

Print usage message.

--config=configFile

Read parameters from a configuration file configFile.

Function setOptions

simuOpt.setOptions(alleleType=None, optimized=None, gui=None, quiet=None, debug=None, version=None, revision=None, numThreads=None, plotter=None)

Set options before simuPOP is loaded to control which simuPOP module to load, and how the module should be loaded.

alleleType

Use the standard, binary,long or mutant allele version of the simuPOP module if alleleType is set to ‘short’, ‘binary’, ‘long’, ‘mutant’, or ‘lineage’ respectively. If this parameter is not set, this function will try to get its value from environmental variable SIMUALLELETYPE. The standard (short) module will be used if the environmental variable is not defined.

optimized

Load the optimized version of a module if this parameter is set to True and the standard version if it is set to False. If this parameter is not set (None), the optimized version will be used if environmental variable SIMUOPTIMIZED is defined. The standard version will be used otherwise.

gui

Whether or not use graphical user interfaces, which graphical toolkit to use and how to process parameters in non-GUI mode. If this parameter is None (default), this function will check environmental variable SIMUGUI or commandline option --gui for a value, and assume True if such an option is unavailable. If gui=True, simuPOP will use wxPython-based dialogs if wxPython is available, and use Tkinter-based dialogs if Tkinter is available and use an interactive shell if no graphical toolkit is available. gui='Tkinter' or 'wxPython' can be used to specify the graphical toolkit to use. If gui='interactive', a simuPOP script prompt users to input values of parameters. If gui='batch', default values of unspecified parameters will be used. In any case, commandline arguments and a configuration file specified by parameter –config will be processed. This option is usually left to None so that the same script can be run in both GUI and batch mode using commandline option --gui.

plotter

(Deprecated)

quiet

If set to True, suppress the banner message when a simuPOP module is loaded.

debug

A list of debug code (as string) that will be turned on when simuPOP is loaded. If this parameter is not set, a list of comma separated debug code specified in environmental variable SIMUDEBUG, if available, will be used. Note that setting debug=[] will remove any debug code that might have been by variable SIMUDEBUG.

version

A version string (e.g. 1.0.0) indicating the required version number for the simuPOP module to be loaded. simuPOP will fail to load if the installed version is older than the required version.

revision

Obsolete with the introduction of parameter version.

numThreads

Number of Threads that will be used to execute a simuPOP script. The values can be a positive number (number of threads) or 0 (all available cores of the computer, or whatever number set by environmental variable OMP_NUM_THREADS). If this parameter is not set, the number of threads will be set to 1, or a value set by environmental variable OMP_NUM_THREADS.