pyuncertainnumber.pba.pbox_free =============================== .. py:module:: pyuncertainnumber.pba.pbox_free Attributes ---------- .. autoapisummary:: pyuncertainnumber.pba.pbox_free.known_constraints Functions --------- .. autoapisummary:: pyuncertainnumber.pba.pbox_free.KS_bounds pyuncertainnumber.pba.pbox_free.known_properties pyuncertainnumber.pba.pbox_free.min_max pyuncertainnumber.pba.pbox_free.min_mean pyuncertainnumber.pba.pbox_free.mean_std pyuncertainnumber.pba.pbox_free.mean_var pyuncertainnumber.pba.pbox_free.min_max_mean pyuncertainnumber.pba.pbox_free.pos_mean_std pyuncertainnumber.pba.pbox_free.min_max_mode pyuncertainnumber.pba.pbox_free.min_max_median pyuncertainnumber.pba.pbox_free.min_max_mean_std pyuncertainnumber.pba.pbox_free.min_max_mean_var pyuncertainnumber.pba.pbox_free.from_percentiles Module Contents --------------- .. py:function:: KS_bounds(s: numpy.typing.ArrayLike, alpha: float, display=True, output_type='bounds') -> Union[tuple[pyuncertainnumber.pba.ecdf.eCDF_bundle], pyuncertainnumber.pba.pbox_abc.Pbox, pyuncertainnumber.UncertainNumber] construct free pbox from sample data by Kolmogorov-Smirnoff confidence bounds :param s: sample data, precise and imprecise :type s: ArrayLike :param dn: KS critical value at a significance level and sample size N; :type dn: float :param output_type: A choice between {'bounds', 'pbox', 'un'}, default='bounds' which returns two eCDF bundles as bounds; 'pbox' to return a pbox object; 'un' to return an uncertain number object. :type output_type: str :returns: a tuple of two CDF bounds, i.e. upper and lower (eCDF_bundle objects), or a Pbox object, or an UncertainNumber object the return type is controlled by the `output_type` argument. .. note:: By default the function returns two eCDF bundles as the extreme bounds. With the upper and lower bounds, a free pbox can be constructed. .. rubric:: Example >>> # both precise data (e.g. numpy array) and imprecise data (e.g. a vector of interval) are supported >>> precise_data = np.random.normal(0, 1, 100) # precise data case >>> ub, lb = pba.KS_bounds(precise_data, alpha=0.025, display=True) >>> # alternatively, an uncertain number or a p-box can be returned >>> pba.KS_bounds(precise_data, alpha=0.025, display=False, output_type='pbox') # return a pbox object >>> pba.KS_bounds(precise_data, alpha=0.025, display=False, output_type='un') # return an uncertain number object >>> # imprecise data case >>> impre_data = pba.I(lo = precise_data -0.5, hi = precise_data + 0.5) >>> ub, lb = pba.KS_bounds(impre_data, alpha=0.025, display=True) .. figure:: /_static/ks_bounds_demo.png :alt: ks_bounds :align: center :width: 50% Kolmogorov-Smirnoff confidence bounds illustration with precise and imprecise data. .. py:function:: known_properties(maximum=None, mean=None, median=None, minimum=None, mode=None, percentiles=None, std=None, var=None, family=None, **kwargs) -> pyuncertainnumber.characterisation.uncertainNumber.UncertainNumber Construct a uncertain number given known statistical properties served as constraints. :param maximum: maximum value of the variable :type maximum: number :param mean: mean value of the variable :type mean: number :param median: median value of the variable :type median: number :param minimum: minimum value of the variable :type minimum: number :param mode: mode value of the variable :type mode: number :param percentiles: dictionary of percentiles and their values, e.g. {0: 0, 0.1: 1, 0.5: 2, 0.9: pun.I(3,4), 1:5} :type percentiles: dict :param std: standard deviation of the variable :type std: number :param var: variance of the variable :type var: number :param family: name of the distribution family, e.g. 'normal', 'lognormal', 'uniform', 'triangular', etc. :type family: str :returns: uncertain number .. note:: It's also possible to directly call a function given the known information, such as ``pun.mean_std(mean=1, std=0.5)``. .. rubric:: Example >>> from pyuncertainnumber.pba import known_properties >>> known_properties( ... maximum = 2, ... mean = 1, ... var = 0.25, ... minimum=0, ... ) .. py:data:: known_constraints .. py:function:: min_max(minimum: numbers.Number, maximum: numbers.Number) -> pyuncertainnumber.characterisation.uncertainNumber.UncertainNumber | pyuncertainnumber.pba.pbox_abc.Pbox Equivalent to an interval object constructed as a nonparametric Pbox. :param minimum: Left end of box :param maximum: Right end of box :returns: UncertainNumber or Pbox .. tip:: Two types of return values are possible: - by default, a `UncertainNumber` is returned; - For low-level controls, if `return_construct=True` is specified, a `Pbox` is returned. .. rubric:: Example >>> from pyuncertainnumber.pba import min_max >>> min_max(0, 2) # return a UncertainNumber >>> min_max(0, 2, return_construct=True) # return a Pbox .. py:function:: min_mean(minimum, mean, steps=Params.steps) -> pyuncertainnumber.characterisation.uncertainNumber.UncertainNumber | pyuncertainnumber.pba.pbox_abc.Pbox Nonparametric pbox construction based on constraint of minimum and mean :param minimum: minimum value of the variable :type minimum: number :param mean: mean value of the variable :type mean: number :returns: UncertainNumber or Pbox .. tip:: Two types of return values are possible: - by default, a `UncertainNumber` is returned; - For low-level controls, if `return_construct=True` is specified, a `Pbox` is returned. .. rubric:: Example >>> from pyuncertainnumber.pba import min_mean >>> min_mean(0, 1) # return a UncertainNumber >>> min_mean(0, 1, return_construct=True) # return a Pbox .. py:function:: mean_std(mean: numbers.Number, std: numbers.Number, steps=Params.steps) -> pyuncertainnumber.characterisation.uncertainNumber.UncertainNumber | pyuncertainnumber.pba.pbox_abc.Pbox Nonparametric pbox construction based on constraint of mean and std :param mean: mean value of the variable :type mean: number :param std: std value of the variable :type std: number :returns: UncertainNumber or Pbox .. tip:: Two types of return values are possible: - by default, a `UncertainNumber` is returned; - For low-level controls, if `return_construct=True` is specified, a `Pbox` is returned. .. rubric:: Example >>> mean_std(1, 0.5) .. py:function:: mean_var(mean: numbers.Number, var: numbers.Number) -> pyuncertainnumber.characterisation.uncertainNumber.UncertainNumber | pyuncertainnumber.pba.pbox_abc.Pbox Nonparametric pbox construction based on constraint of mean and var :param mean: mean value of the variable :type mean: number :param vasr: var value of the variable :type vasr: number :returns: UncertainNumber or Pbox .. tip:: Two types of return values are possible: - by default, a `UncertainNumber` is returned; - For low-level controls, if `return_construct=True` is specified, a `Pbox` is returned. .. rubric:: Example >>> mean_var(1, 0.25) # return a UncertainNumber .. py:function:: min_max_mean(minimum: numbers.Number, maximum: numbers.Number, mean: numbers.Number, steps: int = Params.steps) -> pyuncertainnumber.characterisation.uncertainNumber.UncertainNumber | pyuncertainnumber.pba.pbox_abc.Pbox Generates a distribution-free p-box based upon the minimum, maximum and mean of the variable :param minimum: minimum value of the variable :type minimum: float :param maximum: maximum value of the variable :type maximum: float :param mean: mean value of the variable :type mean: float :returns: UncertainNumber or Pbox .. tip:: Two types of return values are possible: - by default, a `UncertainNumber` is returned; - For low-level controls, if `return_construct=True` is specified, a `Pbox` is returned. .. rubric:: Example >>> min_max_mean(0, 2, 1) .. py:function:: pos_mean_std(mean: numbers.Number, std: numbers.Number, steps=Params.steps) -> pyuncertainnumber.pba.pbox_abc.Pbox Generates a positive distribution-free p-box based upon the mean and standard deviation of the variable :param mean: mean of the variable :param std: standard deviation of the variable :returns: UncertainNumber or Pbox .. tip:: Two types of return values are possible: - by default, a `UncertainNumber` is returned; - For low-level controls, if `return_construct=True` is specified, a `Pbox` is returned. .. py:function:: min_max_mode(minimum: numbers.Number, maximum: numbers.Number, mode: numbers.Number, steps: int = Params.steps) -> pyuncertainnumber.characterisation.uncertainNumber.UncertainNumber | pyuncertainnumber.pba.pbox_abc.Pbox Nonparametric pbox construction based on constraint of mean and var :param minimum: minimum value of the variable :param maximum: maximum value of the variable :param mode: mode value of the variable :type mode: number :returns: UncertainNumber or Pbox .. tip:: Two types of return values are possible: - by default, a `UncertainNumber` is returned; - For low-level controls, if `return_construct=True` is specified, a `Pbox` is returned. .. rubric:: Example >>> min_max_mode(0, 2, 1) # return a UncertainNumber .. py:function:: min_max_median(minimum: numbers.Number, maximum: numbers.Number, median: numbers.Number, steps: int = Params.steps) -> pyuncertainnumber.characterisation.uncertainNumber.UncertainNumber | pyuncertainnumber.pba.pbox_abc.Pbox Generates a distribution-free p-box based upon the minimum, maximum and median of the variable :param minimum: minimum value of the variable :param maximum: maximum value of the variable :param median: median value of the variable :returns: UncertainNumber or Pbox .. tip:: Two types of return values are possible: - by default, a `UncertainNumber` is returned; - For low-level controls, if `return_construct=True` is specified, a `Pbox` is returned. .. rubric:: Example >>> min_max_median(0, 2, 1) # return a UncertainNumber .. py:function:: min_max_mean_std(minimum: numbers.Number, maximum: numbers.Number, mean: numbers.Number, std: numbers.Number, **kwargs) -> pyuncertainnumber.characterisation.uncertainNumber.UncertainNumber | pyuncertainnumber.pba.pbox_abc.Pbox Generates a distribution-free p-box based upon the minimum, maximum, mean and standard deviation of the variable :param maximum: maximum value of the variable :type maximum: number :param minimum: minimum value of the variable :type minimum: number :param std: standard deviation of the variable :type std: number :param var: variance of the variable :type var: number :returns: UncertainNumber or Pbox .. tip:: Two types of return values are possible: - by default, a `UncertainNumber` is returned; - For low-level controls, if `return_construct=True` is specified, a `Pbox` is returned. .. rubric:: Example >>> min_max_mean_std(0, 2, 1, 0.5) # return a UncertainNumber .. seealso:: :func:`min_max_mean_var` .. py:function:: min_max_mean_var(minimum: numbers.Number, maximum: numbers.Number, mean: numbers.Number, var: numbers.Number, **kwargs) -> pyuncertainnumber.characterisation.uncertainNumber.UncertainNumber | pyuncertainnumber.pba.pbox_abc.Pbox Generates a distribution-free p-box based upon the minimum, maximum, mean and standard deviation of the variable :param minimum: minimum value of the variable :type minimum: number :param maximum: maximum value of the variable :type maximum: number :param mean: mean value of the variable :type mean: number :param var: variance of the variable :type var: number .. tip:: Two types of return values are possible: - by default, a `UncertainNumber` is returned; - For low-level controls, if `return_construct=True` is specified, a `Pbox` is returned. .. rubric:: Example >>> min_max_mean_var(0, 2, 1, 0.25) # return a UncertainNumber .. admonition:: Implementation Equivalent to ``min_max_mean_std(minimum,maximum,mean,np.sqrt(var))`` .. seealso:: :func:`min_max_mean_std` .. py:function:: from_percentiles(percentiles: dict, steps: int = Params.steps) -> pyuncertainnumber.characterisation.uncertainNumber.UncertainNumber | pyuncertainnumber.pba.pbox_abc.Pbox yields a distribution-free p-box based on specified percentiles of the variable :param percentiles: dictionary of percentiles and their values (e.g. {0: 0, 0.1: 1, 0.5: 2, 0.9: I(3,4), 1:5}) :param steps: number of steps to use in the p-box .. note:: The percentiles dictionary is of the form {percentile: value}. Where value can either be a number or an I. If value is a number, the percentile is assumed to be a point percentile. If value is an I, the percentile is assumed to be an interval percentile. If no keys for 0 and 1 are given, ``-np.inf`` and ``np.inf`` are used respectively. This will result in a p-box that is not bounded and raise a warning. If the percentiles are not increasing, the percentiles will be intersected. This may not be desired behaviour. ValueError: If any of the percentiles are not between 0 and 1. :returns: UncertainNumber or Pbox .. tip:: Two types of return values are possible: - by default, a `UncertainNumber` is returned; - For low-level controls, if `return_construct=True` is specified, a `Pbox` is returned. .. rubric:: Example >>> pba.from_percentiles( >>> {0: 0, >>> 0.25: 0.5, >>> 0.5: pba.I(1,2), >>> 0.75: pba.I(1.5,2.5), >>> 1: 3}) >>> .display()