deadleaves.distributions ======================== .. py:module:: deadleaves.distributions Classes ------- .. autoapisummary:: deadleaves.distributions.DistSpec deadleaves.distributions.BaseDistribution deadleaves.distributions.PowerLaw deadleaves.distributions.Cosine deadleaves.distributions.ExpCosine deadleaves.distributions.Constant deadleaves.distributions.Image Functions --------- .. autoapisummary:: deadleaves.distributions.get_dist_kw Module Contents --------------- .. py:class:: DistSpec Distribution data class .. py:attribute:: cls :type: Type[torch.distributions.distribution.Distribution] Distribution class .. py:attribute:: required :type: set[str] Parameters of the distribution .. py:function:: get_dist_kw() -> dict[str, DistSpec] Return dictionary mapping keys to distribution classes and required parameters. .. py:class:: BaseDistribution(*args, **kwargs) Bases: :py:obj:`torch.distributions.distribution.Distribution` Base class for custom distributions Raises: NotImplementedError: Class contains empty methods for - initialization (__init__) - probability density function (pdf) - inverse cumulative function (icdf) .. py:attribute:: _batch_shape :type: torch.Size The shape over which parameters are batched. .. py:method:: _validate_args() Validate input arguments. Raises: ValueError .. py:method:: pdf(x: torch.Tensor) -> torch.Tensor :abstractmethod: Returns the probability density function evaluated at *x*. Args: x (torch.Tensor): Value(s) to evaluate. .. py:method:: cdf(x: torch.Tensor) -> torch.Tensor Returns (approximation of) the cumulative density function evaluated at *x*. If not implemented this method will compute the cdf as approximation via the pdf. Args: x (torch.Tensor): Value(s) to evaluate. .. py:method:: icdf(p: torch.Tensor) -> torch.Tensor :abstractmethod: Returns the inverse cumulative density function evaluated at *p*. Args: p (torch.Tensor): Probability value(s) to evaluate. .. py:method:: ppf(p: torch.Tensor) -> torch.Tensor Returns the percent point function, i.e. approximation of inverse cumulative function evaluated at *p*. Args: p (torch.Tensor): Probability value(s) to evaluate. .. py:method:: sample(n=1) -> torch.Tensor Generates a sample from the distribution. Args: n (int, optional): Number of samples. Defaults to 1. .. py:class:: PowerLaw(low: float, high: float, k: float = 3) Bases: :py:obj:`BaseDistribution` Distribution with density that follows the power law. Args: low (float): Minimal allowed value. high (float): Maximal allowed value. k (float, optional): Power law exponent. Defaults to 3. .. py:property:: arg_constraints :type: dict Returns a dictionary from argument names to :class:`~torch.distributions.constraints.Constraint` objects that should be satisfied by each argument of this distribution. Args that are not tensors need not appear in this dict. .. py:method:: __str__() -> str Returns a readable string representation of the object. .. py:property:: support Returns a :class:`~torch.distributions.constraints.Constraint` object representing this distribution's support. .. py:method:: pdf(x: torch.Tensor) -> torch.Tensor Returns the probability density function evaluated at *x*. Args: x (torch.Tensor): Value(s) to evaluate. .. py:method:: cdf(x: torch.Tensor) -> torch.Tensor Returns (approximation of) the cumulative density function evaluated at *x*. If not implemented this method will compute the cdf as approximation via the pdf. Args: x (torch.Tensor): Value(s) to evaluate. .. py:method:: icdf(p: torch.Tensor) -> torch.Tensor Returns the inverse cumulative density function evaluated at *p*. Args: p (torch.Tensor): Probability value(s) to evaluate. .. py:class:: Cosine(amplitude: float = 0.5, frequency: int = 4) Bases: :py:obj:`BaseDistribution` Distribution with density that follows the cosine Args: amplitude (float): Amplitude of cosine. Value must be between 0.0 and 1.0. Defaults to 0.5. frequency (int): Frequency of cosine. Defaults to 4, i.e. peaks at the cardinals. .. py:property:: support Returns a :class:`~torch.distributions.constraints.Constraint` object representing this distribution's support. .. py:property:: arg_constraints Returns a dictionary from argument names to :class:`~torch.distributions.constraints.Constraint` objects that should be satisfied by each argument of this distribution. Args that are not tensors need not appear in this dict. .. py:method:: __str__() -> str Returns a readable string representation of the object. .. py:method:: pdf(x: torch.Tensor) -> torch.Tensor Returns the probability density function evaluated at *x*. Args: x (torch.Tensor): Value(s) to evaluate. .. py:method:: cdf(x: torch.Tensor) -> torch.Tensor Returns (approximation of) the cumulative density function evaluated at *x*. If not implemented this method will compute the cdf as approximation via the pdf. Args: x (torch.Tensor): Value(s) to evaluate. .. py:class:: ExpCosine(frequency: int = 4, exponential_constant: float = 3) Bases: :py:obj:`BaseDistribution` Distribution with cosine density and exponential peaks. Args: frequency (int): Frequency of cosine. Defaults to 4, i.e. peaks at the cardinals. exponential_constant (float): Growth constant of exponential component. Larger values generate stronger peaks. Negative values invert the peaks. Defaults to 3. .. py:property:: support Returns a :class:`~torch.distributions.constraints.Constraint` object representing this distribution's support. .. py:property:: arg_constraints Returns a dictionary from argument names to :class:`~torch.distributions.constraints.Constraint` objects that should be satisfied by each argument of this distribution. Args that are not tensors need not appear in this dict. .. py:method:: __str__() -> str Returns a readable string representation of the object. .. py:method:: pdf(x: torch.Tensor) -> torch.Tensor Returns the probability density function evaluated at *x*. Args: x (torch.Tensor): Value(s) to evaluate. .. py:class:: Constant(value: float) Bases: :py:obj:`torch.distributions.distribution.Distribution` Distribution class which return a constant value. Args: value (float): Constant value to be return in each sampling. .. py:property:: arg_constraints Returns a dictionary from argument names to :class:`~torch.distributions.constraints.Constraint` objects that should be satisfied by each argument of this distribution. Args that are not tensors need not appear in this dict. .. py:property:: support Returns a :class:`~torch.distributions.constraints.Constraint` object representing this distribution's support. .. py:attribute:: _batch_shape :type: torch.Size The shape over which parameters are batched. .. py:attribute:: value :type: float .. py:method:: __str__() -> str Returns a readable string representation of the object. .. py:method:: pdf(x: torch.Tensor) -> torch.Tensor Returns the probability density function evaluated at *x*. Args: x (torch.Tensor): Value(s) to evaluate. .. py:method:: cdf(x: torch.Tensor) -> torch.Tensor Returns the cumulative density function evaluated at *x*. Args: x (torch.Tensor): Value(s) to evaluate. .. py:method:: icdf(p: torch.Tensor) -> torch.Tensor Returns the inverse cumulative density function evaluated at *p*. Args: p (torch.Tensor): Probability value(s) to evaluate. .. py:method:: sample(n=1) -> torch.Tensor Generates a sample from the distribution. Args: n (int, optional): Number of samples. Defaults to 1. .. py:class:: Image(dir: pathlib.Path | str) Bases: :py:obj:`torch.distributions.distribution.Distribution` Distribution to sample images uniformly from an image data set. Args: dir (Path | str): Path to image data set directory. .. py:property:: arg_constraints Returns a dictionary from argument names to :class:`~torch.distributions.constraints.Constraint` objects that should be satisfied by each argument of this distribution. Args that are not tensors need not appear in this dict. .. py:property:: support Returns a :class:`~torch.distributions.constraints.Constraint` object representing this distribution's support. .. py:attribute:: _batch_shape :type: torch.Size The shape over which parameters are batched. .. py:attribute:: dir :type: pathlib.Path | str Path to image data set directory. .. py:attribute:: files :type: list[pathlib.Path] List of image files in the directory. .. py:attribute:: n_files :type: int Number of image files. .. py:method:: __str__() -> str Returns a readable string representation of the object. .. py:method:: sample(n=1) -> list[pathlib.Path] Draws a sample from the available images. Args: n (int, optional): Number of samples. Defaults to 1.