Added ufloat_from_sample function

CHANGES.rst

@@ -12,6 +12,7 @@ Changes
    time. Now such a function can be imported but if the user attempts to
    execute it, a `NotImplementedError` is raised indicating that the
    function can't be used because `numpy` couldn't be imported.
+- Added `uncertainties.ufloat_from_sample()` to create a ufloat from a random sample of a variable.
 
 Fixes:
 

doc/user_guide.rst

@@ -534,6 +534,12 @@ manner**.  This is what the :func:`nominal_value` and
 >>> uncertainties.std_dev(3)
 0.0
 
+Numbers with uncertainties can be found from samples of numbers 
+without uncertainties using :func:`ufloat_from_sample`. This is
+an estimate of the true value of the number and its uncertainty.
+The currently implemented "gaussian" method returns the mean and the error on the
+mean, so it works best for large samples that are normally distributed.
+
 Finally, a utility method is provided that directly yields the
 `standard score <http://en.wikipedia.org/wiki/Standard_score>`_
 (number of standard deviations) between a number and a result with

tests/test_uncertainties.py

@@ -27,6 +27,8 @@
 except ImportError:
     np = None
 
+if np != None:
+    from uncertainties.unumpy.core import nominal_values,std_devs
 
 def test_value_construction():
     """
@@ -146,6 +148,71 @@ def test_ufloat_fromstr():
         assert numbers_close(num.std_dev, values[1])
         assert num.tag == "test variable"
 
+def test_ufloat_from_sample():
+    "Test genarating a number with an uncertainty from a sample"
+
+    #the test imputs for the sample paramiter
+    test_samples=[
+        [-1.5,-0.5,0,0.5,1.5] #test standard list input
+    ]
+
+    #the test imputs for the other arguments
+    optional_args=[{}]
+
+    #the expected nominal values
+    expected_n=[0]
+
+    #expected standard deviations
+    expected_s=[0.5]
+
+    if np != None:
+        #include extra tests for numpy arrays
+        test_samples+=[
+            np.array([-1.5,-0.5,0,0.5,1.5]),
+            np.array([
+                    [-3,    -1,     0,      1,      3],
+                    [-1.5,  -0.5,   0,      0.5,    1.5],
+                    [-0.75, -0.25,  0,      0.25,   0.75],
+                    [0,     0,      0,      0,      0],
+                    [1.5,   0.5,    0,      -0.5,   -1.5]  
+                ]),
+            np.array([
+                    [-3,    -1,     0,      1,      3],
+                    [-1.5,  -0.5,   0,      0.5,    1.5],
+                    [-0.75, -0.25,  0,      0.25,   0.75],
+                    [0,     0,      0,      0,      0],
+                    [1.5,   0.5,    0,      -0.5,   -1.5]  
+                ])
+        ]
+        optional_args+=[
+            {},
+            {'axis':0},
+            {'axis':1}
+        ]
+        expected_n+=[
+            0,
+            [-0.75,-0.25,0.0,0.25,0.75],
+            [0, 0, 0, 0, 0]
+        ]
+        expected_s+=[
+            0.5,
+            [0.75,0.25,0.0,0.25,0.75],
+            [1, 0.5, 0.25, 0, 0.5]
+
+        ]
+
+
+    #run the tests
+    for i,sample in enumerate(test_samples):
+
+        num=uncert_core.ufloat_from_sample(sample,**(optional_args[i]))
+
+        #check nominal values
+        assert(np.allclose(nominal_values(num),expected_n[i]))
+
+        #check standard deviations
+        assert(np.allclose(std_devs(num),expected_s[i]))
+
 
 ###############################################################################
 

uncertainties/core.py

@@ -17,6 +17,9 @@
 from builtins import str, zip, range, object
 from math import sqrt, isfinite  # Optimization: no attribute look-up
 
+from statistics import mean as stats_mean
+from statistics import stdev as stats_stdev
+
 import copy
 import collections
 
@@ -71,7 +74,6 @@
 except ImportError:
     numpy = None
 
-
 def correlated_values(nom_values, covariance_mat, tags=None):
     """
     Return numbers with uncertainties (AffineScalarFunc objects)
@@ -1004,6 +1006,76 @@ def ufloat_fromstr(representation, tag=None):
     (nom, std) = str_to_number_with_uncert(representation.strip())
     return ufloat(nom, std, tag)
 
+def ufloat_from_sample(sample, method="gaussian", axis=None):
+    '''
+    Converts a collection of values into a ufloat.
+
+    Arguments:
+    ----------
+    sample: list or numpy array of numbers
+        The sample of values
+
+    method: optional string
+        The method used to calculate the ufloat. currently, only 
+        the 'gaussian' method is implemented.
+
+        gaussian: The nominal value is the mean of the sample. 
+        The standard deviation is the error on the mean. This 
+        method assumes that the sample follows a gaussian 
+        distribution, and works best for large samples. This 
+        method works well to find an estimate of a fixed value 
+        that has been measured multiuple times with some random 
+        error.
+
+    axis: integer or None
+        Only when the sample is a numpy array. The axis along 
+        which the ufloats are computed. If None (the default value)
+        the sample is the whole flattened array. 
+
+    '''
+
+    if method=="gaussian":
+
+        if numpy is None:
+            #if numpy is not present, use pythons statistics functions instead
+            mean_value=stats_mean(sample)
+            error_on_mean=stats_stdev(sample)/sqrt(len(sample)-1)
+
+            return ufloat(mean_value,error_on_mean)
+
+        else:
+            #if numpy is present, use the faster numpy functions that can handle a wider range of inputs
+            mean_value=numpy.mean(sample, axis=axis)
+
+            #the size of each sample being collected
+            sample_size=0
+
+            if axis == None: 
+                sample_size=numpy.size(sample)
+            else:
+                sample_size=numpy.shape(sample)[axis]
+
+            error_on_mean=numpy.std(sample, ddof=1, axis=axis)/numpy.sqrt(sample_size)
+
+            if len(numpy.shape(mean_value))==0:
+                # if the output is a single ufloat
+                return ufloat(mean_value,error_on_mean)
+            else:
+                #if the output is an array of ufloats (duplicate of code from unnumpy.core.uarray to avoid circular import)
+                return numpy.vectorize(
+                    # ! Looking up uncert_core.Variable beforehand through
+                    # '_Variable = uncert_core.Variable' does not result in a
+                    # significant speed up:
+                    lambda v, s: Variable(v, s),
+                    otypes=[object],
+                    )(mean_value, error_on_mean)
+    else:
+        msg={
+            "{} is not one of the implemented methods".format(method)
+        }
+        raise ValueError(msg)
+
+
 
 def ufloat(nominal_value, std_dev=None, tag=None):
     """