6.1. pypfilt

The pypfilt module provides top-level functions for running forecasts and simulating observations from simulation models.

pypfilt.load_instances(sources)

Iterate over scenario instances defined in one or more TOML sources.

Parameters:sources – A list of file-like objects and/or file paths. If sources is not a list, it will be treated as the only item of a list.
Return type:Iterator[Instance]
Examples:
>>> import pypfilt
>>> import pypfilt.build
>>> import pypfilt.examples.predation
>>> pypfilt.examples.predation.write_example_files()
>>> forecast_times = [1.0, 3.0, 5.0, 7.0, 9.0]
>>> config_file = 'predation.toml'
>>> data_file = 'output.hdf5'
>>> for instance in pypfilt.load_instances(config_file):
...     context = instance.build_context()
...     state = pypfilt.forecast(context, forecast_times,
...                              filename=data_file)
pypfilt.forecast(ctx, dates, filename)

Generate forecasts from various dates during a simulation.

Parameters:
  • ctx (pypfilt.build.Context) – The simulation context.
  • dates – The dates at which forecasts should be generated.
  • filename – The output file to generate (can be None).
Returns:

The simulation state for each forecast date.

Examples:
>>> from datetime import datetime
>>> import pypfilt
>>> import pypfilt.build
>>> import pypfilt.examples.predation
>>> pypfilt.examples.predation.write_example_files()
>>> config_file = 'predation-datetime.toml'
>>> fs_dates = [datetime(2017, 5, 5), datetime(2017, 5, 10)]
>>> data_file = 'output.hdf5'
>>> for instance in pypfilt.load_instances(config_file):
...     context = instance.build_context()
...     state = pypfilt.forecast(context, fs_dates, filename=data_file)
pypfilt.fit(ctx, filename)

Run a single estimation pass over the entire simulation period.

Parameters:
  • ctx (pypfilt.build.Context) – The simulation context.
  • filename – The output file to generate (can be None).
Returns:

The simulation state for the estimation pass.

Examples:
>>> import pypfilt
>>> import pypfilt.build
>>> import pypfilt.examples.predation
>>> pypfilt.examples.predation.write_example_files()
>>> config_file = 'predation.toml'
>>> data_file = 'output.hdf5'
>>> for instance in pypfilt.load_instances(config_file):
...     context = instance.build_context()
...     state = pypfilt.fit(context, filename=data_file)
pypfilt.simulate_from_model(instance, particles=1, common_prng_seed=False)

Simulate observations from a model.

Parameters:
  • instance (pypfilt.scenario.Instance) – The scenario instance.
  • particles – The number of particles; set this to None to use the number of particles defined in instance.
  • common_prng_seed – Whether the simulated observation tables should use a common PRNG seed to generate the simulated observations.
Returns:

A dictionary of simulated observation tables.

Return type:

Dict[str, numpy.ndarray]

Note

The instance should not be reused after calling this function. To prevent this from happening, the instance settings will be deleted.

Examples:
>>> import pypfilt
>>> import pypfilt.examples.predation
>>> pypfilt.examples.predation.write_example_files()
>>> config_file = 'predation.toml'
>>> for instance in pypfilt.load_instances(config_file):
...     obs_tables = pypfilt.simulate_from_model(instance, particles=1)
...     # Print the first four simulated 'x' observations.
...     x_obs = obs_tables['x']
...     print(x_obs[['date', 'value']][:4])
...     # Print the first four simulated 'y' observations.
...     y_obs = obs_tables['y']
...     print(y_obs[['date', 'value']][:4])
[(0., 1.35192613) (1., 1.54456968) (2., 1.92089402) (3., 1.21987828)]
[(0., -0.14294339) (1.,  0.51293146) (2.,  1.1426979 ) (3.,  0.83975596)]
>>> print(instance.settings)
{}

The pypfilt module also re-exports a number of items from sub-modules:

  • Model base classes: Model and Obs.
  • Summary statistic base classes: Monitor and Table.
  • Simulation time scales: Datetime and Scalar.
  • Simulation instances: Instance.
  • Simulation contexts: Context.