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
...     )
>>> # Remove the output file when it is no longer needed.
>>> import os
>>> os.remove(data_file)
pypfilt.forecast(ctx, times, filename)

Generate forecasts from various times during a simulation.

Parameters:

  • ctx (pypfilt.build.Context) – The simulation context.

  • times – The times at which forecasts should be generated.

  • filename – The output file to generate (can be None).

Returns:

The simulation results for each forecast.

Return type:

Results

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_times = [datetime(2017, 5, 5), datetime(2017, 5, 10)]
>>> data_file = 'output.hdf5'
>>> for instance in pypfilt.load_instances(config_file):
...     context = instance.build_context()
...     results = pypfilt.forecast(context, fs_times, filename=data_file)
>>> # Remove the example files when they are no longer needed.
>>> pypfilt.examples.predation.remove_example_files()
>>> # Remove the output file when it is no longer needed.
>>> import os
>>> os.remove(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 results for the estimation pass.

Return type:

Results

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()
...     results = pypfilt.fit(context, filename=data_file)
>>> # Remove the example files when they are no longer needed.
>>> pypfilt.examples.predation.remove_example_files()
>>> # Remove the output file when it is no longer needed.
>>> import os
>>> os.remove(data_file)
pypfilt.adaptive_fit(ctx, filename, save_when=None, save_to=None)

Run a series of adaptive fits over all observations.

Parameters:

  • ctx (pypfilt.build.Context) – The simulation context.

  • filename – The output file to generate (can be None).

  • save_when – Times at which to save the particle history matrix during the final estimation pass.

  • save_to – The filename for saving the particle history matrix.

Returns:

The simulation results for the estimation passes.

Return type:

Results

The fitting method must be defined in filter.adaptive_fit.method. The supported methods are:

  • "fit_effective_fraction": each pass tunes the observation models to achieve a target effective particle fraction.

  • "fixed_exponents": each pass raises the log-likelihoods to a fixed exponent.

pypfilt.simulate_from_model(instance, particles=1, observations=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.

  • observations – The number of observations to simulate for each particle, at each time unit.

  • 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. The dictionary will be empty if no observations were simulated (e.g., if no time-steps were performed).

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[:4])
...     # Print the first four simulated 'y' observations.
...     y_obs = obs_tables['y']
...     print(y_obs[:4])
[(0., 1.35192613) (1., 1.54453284) (2., 1.92039984) (3., 1.21684457)]
[(0., -0.14294339) (1.,  0.51294785) (2.,  1.14303379) (3.,  0.84072101)]
>>> print(instance.settings)
{}
>>> # Remove the example files when they are no longer needed.
>>> pypfilt.examples.predation.remove_example_files()

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