Writing and reading patterns and values from disk

Saving Folded Values with Patterns

Flattning makes it easy to save and load structured data to and from disk.

pattern = paragami.PatternDict()
pattern['num'] = paragami.NumericArrayPattern((1, 2))
pattern['mat'] = paragami.PSDSymmetricMatrixPattern(5)

val_folded = pattern.random()
extra = np.random.random(5)

outfile = tempfile.NamedTemporaryFile()
outfile_name = outfile.name
outfile.close()

paragami.save_folded(outfile_name, val_folded, pattern, extra=extra)

val_folded_loaded, pattern_loaded, data = \
    paragami.load_folded(outfile_name + '.npz')

# The loaded values match the saved values.
assert pattern == pattern_loaded
assert np.all(val_folded['num'] == val_folded_loaded['num'])
assert np.all(val_folded['mat'] == val_folded_loaded['mat'])
assert np.all(data['extra'] == extra)

paragami.pattern_containers.save_folded(file, folded_val, pattern, **argk)

Save a folded value to a file with its pattern.

Flatten a folded value and save it with its pattern to a file using numpy.savez. Additional keyword arguments will also be saved to the file.

Parameters:

file: String or file

Follows the conventions of numpy.savez. Note that the npz extension will be added if it is not present.

folded_val:

The folded value of a parameter.

pattern:

A paragami pattern for the folded value.

paragami.pattern_containers.load_folded(file)

Load a folded value and its pattern from a file together with any additional data.

Note that pattern must be registered with register_pattern_json to use load_folded.

Parameters:

file: String or file

A file or filename of data saved with save_folded.

Returns:

folded_val:

The folded value of the saved parameter.

pattern:

The paragami pattern of the saved parameter.

data:

The data as returned from np.load. Additional saved values will exist as keys of data.

Saving patterns

You can convert a particular pattern class to and from JSON using the to_json and from_json methods.

>>> pattern = paragami.NumericArrayPattern(shape=(2, 3))
>>>
>>> # ``pattern_json_string`` is a JSON string that can be written to a file.
>>> pattern_json_string = pattern.to_json()
>>>
>>> # ``same_pattern`` is identical to ``pattern``.
>>> same_pattern = paragami.NumericArrayPattern.from_json(pattern_json_string)

However, in order to use from_json, you need to know which pattern the JSON string was generated from. In order to decode generic JSON strings, one can use get_pattern_from_json.

>>> pattern_json_string = pattern.to_json()
>>> # ``same_pattern`` is identical to ``pattern``.
>>> same_pattern = paragami.get_pattern_from_json(pattern_json_string)

Before a pattern can be used with get_pattern_from_json, it needs to be registered with register_pattern_json. All the patterns in paragami are automatically registered, but if you define your own patterns they will have to be registered before they can be used with get_pattern_from_json.

paragami.pattern_containers.get_pattern_from_json(pattern_json)

Return the appropriate pattern from pattern_json.

The pattern must have been registered using register_pattern_json.

Parameters:

pattern_json: String

A JSON string as created with a pattern’s to_json method.

Returns:

The pattern instance encoded in the ``pattern_json`` string.

paragami.pattern_containers.register_pattern_json(pattern, allow_overwrite=False)

Register a pattern for automatic conversion from JSON.

Parameters:

pattern: A Pattern class

The pattern to register.

allow_overwrite: Boolean

If true, allow overwriting already-registered patterns.

Examples

>>> class MyCustomPattern(paragami.Pattern):
>>>    ... definitions ...
>>>
>>> paragami.register_pattern_json(paragmi.MyCustomPattern)
>>>
>>> my_pattern = MyCustomPattern(...)
>>> my_pattern_json = my_pattern.to_json()
>>>
>>> # ``my_pattern_from_json`` should be identical to ``my_pattern``.
>>> my_pattern_from_json = paragami.get_pattern_from_json(my_pattern_json)