External simulators

This module can be used to easily interface pyabc with model simulations, summary statistics calculators and distance functions written in arbitrary programing languages, only requiring a specified command line interface and file input and output.

class pyabc.external.ExternalDistance(executable: str, file: str, fixed_args: List = None, suffix: str = None, prefix: str = 'dist_', dir: str = None, show_stdout: bool = False, show_stderr: bool = True, raise_on_error: bool = False)[source]

Bases: object

Use script and sumstat output files to compute the distance.

Format:

{executable} {file} sumstat_0={sumstat_0} sumstat_1={sumstat_1} target={loc}

The distance is written to a file, which is then read in (it must only contain a single float number).

__call__(sumstat_0, sumstat_1)[source]

Call self as a function.

__init__(executable: str, file: str, fixed_args: List = None, suffix: str = None, prefix: str = 'dist_', dir: str = None, show_stdout: bool = False, show_stderr: bool = True, raise_on_error: bool = False)[source]

Initialize self. See help(type(self)) for accurate signature.

class pyabc.external.ExternalHandler(executable: str, file: str = None, fixed_args: List = None, create_folder: bool = False, suffix: str = None, prefix: str = None, dir: str = None, show_stdout: bool = False, show_stderr: bool = True, raise_on_error: bool = False)[source]

Bases: object

Handler for calls to external scripts.

This is a convenience class for bundling repeated functionality.

__init__(executable: str, file: str = None, fixed_args: List = None, create_folder: bool = False, suffix: str = None, prefix: str = None, dir: str = None, show_stdout: bool = False, show_stderr: bool = True, raise_on_error: bool = False)[source]
Parameters
  • executable (str) – Name of the executable to call, e.g. bash, java or Rscript. The executable may be parameterized, e.g. appearances of {loc} in the string are replaced at runtime by the location of the output.

  • file (str) – Path to the file to be executed, e.g. a .sh, .java or .r file, or also a .xml file depending on the executable.

  • fixed_args (str, optional (default = None)) – Argument string to use every time.

  • create_folder (bool, optional (default = True)) – Whether the function should create a temporary directory. If False, only one temporary file is created.

  • prefix, dir (suffix,) – Specify suffix, prefix, or base directory for the created temporary files.

  • show_stderr (show_stdout,) – Whether to show or hide the stdout and stderr streams.

  • raise_on_error (bool, optional (default = False)) – Whether to raise when an error in the execution of the external script occurs, or just continue.

create_executable(loc)[source]

Parse and return executable.

Replaces instances of {loc} by the location loc.

create_loc()[source]

Create temporary file or folder.

Returns

loc – Path of the created file or folder.

Return type

str

run(args: List[str] = None, cmd: str = None, loc: str = None)[source]

Run the script for the given arguments.

Parameters
  • args (List[str], optional) – Arguments to pass to the external program, e.g. parameters.

  • cmd (str, optional) – If this is not None, then it is assumed to contain the full command to be executed via the shell (then args is ignored). Be aware of possible security implications of shell injection.

  • loc (str, optional) – Location for the output. If None is passed, one is created.

class pyabc.external.ExternalModel(executable: str, file: str, fixed_args: List = None, create_folder: bool = False, suffix: str = None, prefix: str = 'modelsim_', dir: str = None, show_stdout: bool = False, show_stderr: bool = True, raise_on_error: bool = False, name: str = 'ExternalModel')[source]

Bases: pyabc.model.Model

Interface to a model that is called via an external simulator.

Parameters are passed to the model as named command line arguments in the form

{executable} {file} {par1}={val1} {par2}={val2} … target={loc}

Here, {file} is the script that performs the model simulation, and {loc} is the name of a temporary file or folder that was created to store the simulated data.

Note

The generated temporary files are not automatically deleted, unless by the system e.g. in the /tmp directory upon restart.

__call__(pars: pyabc.parameters.Parameter)[source]

Call self as a function.

__init__(executable: str, file: str, fixed_args: List = None, create_folder: bool = False, suffix: str = None, prefix: str = 'modelsim_', dir: str = None, show_stdout: bool = False, show_stderr: bool = True, raise_on_error: bool = False, name: str = 'ExternalModel')[source]

Initialize the model.

Parameters
  • name (str, optional (default = "ExternalModel")) – As in pyabc.Model.name.

  • other parameters as in ExternalHandler. (All) –

sample(pars)[source]

Return a sample from the model evaluated at parameters pars. This can be raw data, or already summarized statistics thereof.

This method has to be implemented by any subclass.

Parameters

pars (Parameter) – Dictionary of parameters.

Returns

sample – The sampled data.

Return type

any

class pyabc.external.ExternalSumStat(executable: str, file: str, fixed_args: List = None, create_folder: bool = False, suffix: str = None, prefix: str = 'sumstat_', dir: str = None, show_stdout: bool = False, show_stderr: bool = True, raise_on_error: bool = False)[source]

Bases: object

Interface to an external calculator that takes the simulated model output and writes to file the summary statistics.

Format:

{executable} {file} model_output={model_output} target={loc}

Here, {file} is the path to the summary statistics computation script, {model_output} is the path to the previously generated model output, and {loc} is the destination to write te summary statistics to.

__call__(model_output)[source]

Create summary statistics from the model_output generated by the model.

__init__(executable: str, file: str, fixed_args: List = None, create_folder: bool = False, suffix: str = None, prefix: str = 'sumstat_', dir: str = None, show_stdout: bool = False, show_stderr: bool = True, raise_on_error: bool = False)[source]

Initialize self. See help(type(self)) for accurate signature.

class pyabc.external.R(source_file: str)[source]

Bases: object

Interface to R.

Parameters

source_file (str) – Path to the file which contains the definitions for the model, the summary statistics and the distance function as well as the observed data.

__init__(source_file: str)[source]

Initialize self. See help(type(self)) for accurate signature.

display_source_ipython()[source]

Convenience method to print the loaded source file as syntax highlighted HTML within IPython.

distance(function_name: str)[source]

The R-distance function.

Parameters

function_name (str) – Name of the function in the R script which defines the distance function.

Returns

distance – The distance function.

Return type

callable

model(function_name: str)[source]

The R-model.

Parameters

function_name (str) – Name of the function in the R script which defines the model.

Returns

model – The model.

Return type

callable

observation(name: str)[source]

The summary statistics of the observed data as defined in R.

Parameters

name (str) – Name of the named list defined in the R script which holds the observed data.

Returns

observation – A dictionary like object which holds the summary statistics of the observed data.

Return type

r named list

summary_statistics(function_name: str, is_py_model: bool = False)[source]

The R-summary statistics.

Parameters
  • function_name (str) – Name of the function in the R script which defines the summary statistics function.

  • is_py_model (bool) – Whether or not the model result is a python object. If True, then it is expected to be a dictionary that will be converted to a ListVector.

Returns

summary_statistics – The summary statistics function.

Return type

callable

pyabc.external.create_sum_stat(loc: str = '', returncode: int = 0)[source]

Create a summary statistics dictionary, as returned by the ExternalModel.

Can be used to encode the measured summary statistics, or also create a dummy summary statistic.

Parameters
  • loc (str, optional (default = '')) – Location of the summary statistics file or folder.

  • returncode (int, optional (default = 0)) – Defaults to 0, indicating correct execution. Should usually not be changed.

Returns

  • A dictionary with keys ‘loc’ and ‘returncode’ of the given

  • parameters.