Writing data

Ocelot will write a lot of data during a model run. It will also cache some data that can be used across model runs.

Base directory for saving data

Ocelot uses the appdirs library to select an appropriate, platform-specific path for saving data:

  • On Windows: C:\Documents and Settings\<User>\Application Data\Local Settings\ocelot_project\Ocelot
  • On OS X: /Users/<User>/Library/Application Support/Ocelot
  • On Linux: /home/<User>/.local/share/Ocelot

Return base directory where cache and output data are saved.

Creates directory if it is not already present.

Caching data extracted from ecospold2 files

Extracting data from ecospold2 files is relatively expensive, and can take up to a few minutes. Ocelot will by cache the extracted data in order to speed up subsequent model runs. The cache directory is a subdirectory of the base directory, called "cache".

To disable the use of the cached data in a system model run, call system_model(..., use_cache=False).

Cache management functions

The following functions in ocelot.filesystem manage the cached data:


Return base directory where cache data (already extracted datasets) are saved.

Creates directory if it is not already present.


Check that the data in the cache directory for source directory data_path is still fresh.

Returns a boolean.


Return cached extracted data from directory data_path.

This function only loads the pickled cache data; use check_cache_directory to make sure cache is not expired.

ocelot.filesystem.cache_data(data, data_path)

Write extracted data from source directory data_path to cache directory for future use.

Model run output

Model runs are stored in a subdirectory of the base directory called "model-runs". However, a custom location for storing model run outputs can be specified in the environment variable OCELOT_OUTPUT. The environment variable will always take precedence over the default location. See your operating system manual for instructions on setting environment variables.


Get base directory for model run.

Try the environment variable OCELOT_OUTPUT first, fall back to the base directory plus model-runs.

Writing intermediate results

As a typical system model will include tens of transformation functions, intermediate results are not saved after every function. Instead, the default saving strategy to is save intermediate results after every five transformation functions. You can specify an alternative strategy in the system_model function (parameter save_strategy).

class ocelot.results.SaveStrategy(arg=None)

This class tells the system model when to save intermediate results.

Default strategy is to save after every five transformation functions.

Can be initialized using any of the following:

  • None: Use the default value (every five transformation functions).
  • a (where a is an integer): Save every a transformation functions.
  • a:b (a, b are integers): Save every intermediate result between transformation function number a and b (inclusive of a and b).
  • a:b:c (a, b, c are integers): Save every c intermediate result between transformation function number a and b (inclusive of a and b). For example, an input of 2:8:3 would save results after functions 2, 5, and 8.


>>> strat = SaveStrategy()  # same as SaveStrategy(5), default value
>>> strat(4)
>>> strat(5)
>>> strat = SaveStrategy("2:10:4")
>>> strat(2)
>>> strat(3)