firecrown.updatable =================== .. py:module:: firecrown.updatable .. autoapi-nested-parse:: Parameters that can be updated, and collections of them. Abstract class :class:`Updatable` is the base class from which any class in Firecrown that supports updating from a :class:`ParamsMap` should inherit. Such classes are expected to change state only in through their implementation of :meth:`_update` (including any other private methods used to implement :meth:`_update`). Other functions should not change the data of :class:`Updatable` objects. :class:`UpdatableCollection` is a subclass of the built-in list. It implements the :class:`Updatable` interface by calling :meth:`update()` on each element it contains. The :meth:`append()` method is overridden to make sure that only objects which are of a type that implements :class:`Updatable` can be appended to the list. Attributes ---------- .. autoapisummary:: firecrown.updatable.GeneralUpdatable firecrown.updatable.T Exceptions ---------- .. autoapisummary:: firecrown.updatable.MissingSamplerParameterError Classes ------- .. autoapisummary:: firecrown.updatable.Updatable firecrown.updatable.UpdatableCollection Functions --------- .. autoapisummary:: firecrown.updatable.get_default_params firecrown.updatable.get_default_params_map Module Contents --------------- .. py:type:: GeneralUpdatable :canonical: Union['Updatable', 'UpdatableCollection'] .. py:exception:: MissingSamplerParameterError(parameter) Bases: :py:obj:`RuntimeError` .. autoapi-inheritance-diagram:: firecrown.updatable.MissingSamplerParameterError :parts: 1 Error for when a required parameter is missing. Raised when an Updatable fails to be updated because the ParamsMap supplied for the update is missing a parameter that should have been provided by the sampler. .. py:attribute:: parameter .. py:class:: Updatable(parameter_prefix = None) Bases: :py:obj:`abc.ABC` .. autoapi-inheritance-diagram:: firecrown.updatable.Updatable :parts: 1 Abstract class Updatable is the base class for Updatable objects in Firecrown. Any class in Firecrown that supports updating from a ParamsMap should inherit from :class:`Updatable`. Such classes are expected to change state only in through their implementation of _update (including any other private methods used to implement _update). Other functions should not change the data of Updatable objects. .. py:attribute:: parameter_prefix :type: None | str :value: None .. py:method:: __setattr__(key, value) Set the attribute named :attr:`key` to the supplied `value`. There is special handling for two types: :class:`SamplerParameter` and :class:`InternalParameter`. We also keep track of all :class:`Updatable` instance variables added, appending a reference to each to :attr:`self._updatables` as well as storing the attribute directly. :param key: name of the attribute :param value: value for the attribute .. py:method:: set_parameter(key, value) Sets the parameter to the given value. Assure this InternalParameter or SamplerParameter has not already been set, and then set it. :param key: name of the attribute :param value: value for the attribute .. py:method:: set_internal_parameter(key, value) Assure this InternalParameter has not already been set, and then set it. :param key: name of the attribute :param value: value for the attribute .. py:method:: set_sampler_parameter(value) Assure this SamplerParameter has not already been set, and then set it. :param value: value for the attribute .. py:method:: update(params) Update self by calling to prepare for the next MCMC sample. We first update the values of sampler parameters from the values in `params`. An error will be raised if any of self's sampler parameters can not be found in `params` or if any internal parameters are provided in `params`. We then use the `params` to update each contained :class:`Updatable` or :class:`UpdatableCollection` object. The method :meth:`_update` is called to give subclasses an opportunity to do any other preparation for the next MCMC sample. :param params: new parameter values .. py:method:: is_updated() Determine if the object has been updated. A default-constructed Updatable has not been updated. After `update`, but before `reset`, has been called the object is updated. After `reset` has been called, the object is not currently updated. :return: True if the object is currently updated, and False if not. .. py:method:: reset() Reset the updatable. Clean up self by clearing the _updated status and reseting all internals. We call the abstract method _reset to allow derived classes to clean up any additional internals. Each MCMC framework connector should call this after handling an MCMC sample. .. py:method:: required_parameters() Returns all information about parameters required by this object. This object returned contains the information for all parameters defined in the implementing class, and any additional parameters. :return: a RequiredParameters object containing all relevant parameters .. py:method:: get_params_names() Return the names of the parameters required by this object. The order of the returned names is arbitrary. :return: a list of parameter names .. py:method:: get_derived_parameters() Returns a collection of derived parameters. This occurs once per iteration of the statistical analysis. First call returns the DerivedParameterCollection, further calls return None. :return: a collection of derived parameters, or None .. py:data:: T .. py:class:: UpdatableCollection(iterable = None) Bases: :py:obj:`collections.UserList`\ [\ :py:obj:`T`\ ], :py:obj:`Generic`\ [\ :py:obj:`T`\ ] .. autoapi-inheritance-diagram:: firecrown.updatable.UpdatableCollection :parts: 1 Class that represents a collection of updatable objects. UpdatableCollection is a list of Updatable objects and is itself supports :meth:`update` and :meth:`reset` (although it does not inherit from :class:`Updatable`). Every item in an UpdatableCollection must itself be :class:`Updatable`. Calling :meth:`update` on the collection results in every item in the collection being updated. .. py:method:: update(params) Update self by calling update() on each contained item. :param params: new parameter values for each contained item .. py:method:: is_updated() Returns whether this updatable has been updated. Return True if the object is currently updated, and False if not. A default-constructed Updatable has not been updated. After `update`, but before `reset`, has been called the object is updated. After `reset` has been called, the object is not currently updated. .. py:method:: reset() Resets self by calling reset() on each contained item. .. py:method:: required_parameters() Return a RequiredParameters object. The RequiredParameters object is formed by concatenating the RequiredParameters of each contained item. .. py:method:: get_derived_parameters() Get all derived parameters if any. .. py:method:: append(item) Append the given item to self. If the item is not Updatable a TypeError is raised. :param item: new item to be appended to the list .. py:method:: __setitem__(key, value) Set self[key] to value; raise TypeError if Value is not Updatable. .. py:function:: get_default_params(*args) Get a ParamsMap with the default values of all parameters in the updatables. :param args: updatables to get the default parameters from :return: a ParamsMap with the default values of all parameters .. py:function:: get_default_params_map(*args) Get a ParamsMap with the default values of all parameters in the updatables. :param args: updatables to get the default parameters from :return: a ParamsMap with the default values of all parameters