From a92bc7041ae8bb7df5cf785d770c98a9cefea711 Mon Sep 17 00:00:00 2001 From: embrown Date: Thu, 29 Sep 2016 15:59:48 -0700 Subject: [PATCH 1/5] Beginning work on GenUtil documentation --- Lib/ASCII.py | 87 +++++++++++++++++++++++++++++++------------------ Lib/averager.py | 27 ++++++++++++--- 2 files changed, 77 insertions(+), 37 deletions(-) diff --git a/Lib/ASCII.py b/Lib/ASCII.py index de3e1e5..42b53a3 100644 --- a/Lib/ASCII.py +++ b/Lib/ASCII.py @@ -22,21 +22,30 @@ def make_var(lap,id=None,shape=None): return lap def readAscii( text_file ,header=0, ids=None, shape=None, next='------',separators=[';',',',':']): - """Reads data from an ascii file - Usage ::: - vars = genutil.ASCII.readAscii( text_file ,header=0, ids=None, shape=None, next='------',separators=[';',',',':']) - ::: - - Options ::: - text_file :: ASCII File to read from. - header :: (0) Number of header lines, these lines will be skipped. - ids :: (None) use the values in this list as variable ids (1 per variable returned) - shape :: (None) use the tuple/list in this list as the final shape of the variable read. - next :: ('------') character string marking separation between variables - separators :: ([';',',', ':']) List of character recognized as column separator - Output ::: - vars :: List containing transient(s) variable(s) possibly named after ids and reshaped from the 'shape' option. - + """ + Reads data from an ascii file to generate a list of transient(s)/varable(s) + + :Example: + + .. doctest:: genutil_ASCII_readascii + + >>> vars=genutil.ASCII.readAscii("vars.txt") # use default params + + :param text_file: A string, containing the path to an ASCII File to read from. + :type text_file: str + :param header: Number of header lines, these lines will be skipped. + :type header: int + :param ids: List of values to use as variable ids (1 per variable returned) + :type ids: list + :param shape: use the tuple/list in this list as the final shape of the variable read. + :type shape: tuple or list + :param next: character string marking separation between variables (i.e. '------') + :type next: str + :param separators: List of characters recognized as column separators (i.e. [';',',',':']) + :type separators: list + + :returns: List containing transient(s) variable(s) possibly named after ids and reshaped from the 'shape' option. + :rtype: list """ sep=[] if isinstance(separators,str): @@ -83,23 +92,37 @@ def readAscii( text_file ,header=0, ids=None, shape=None, next='------',separato def read_col( text_file ,header=0, cskip=0, cskip_type='columns', axis=False, ids=None, idrow=0, separators=[';',',', ':']): - """ Reads column-stored data from ASCII files - Usage::: - vars = genutil.ASCII.read_col( text_file ,header=0, cskip=0, cskip_type='columns', axis=False, ids=None, idrow=False, separators=[';',',', ':']) - - Options ::: - text_file :: ASCII File to read from. - header :: (0) Number of header lines, these lines will be skipped. - cskip :: (0) Number of 'column'/'character' to skip (dummy column) - cskip_type :: ('column') is 'cskip' a number of 'column' or 'character' to skip? - axis :: (False) Use as the values for the first column as variable axis (x values in y(x)) - idrow :: (False) Is the first row representing the ids of var generated ? - ids :: (None) use the values in this list as variable ids (1 per column returned) - separators :: ([';',',', ':']) List of character recognized as column separator - Output ::: - vars :: List containing 1 transient varialbe per column in the files. - Variable ids are optionaly determined by first row. - Variable axis may be the first column + """ + Reads column-stored data from ASCII files + + :Example: + + .. doctest:: genutil_ASCII_read_col + + >>> vars = genutil.ASCII.read_col("vars.txt") # use default params + + + :param text_file: ASCII File to read from. + :type text_file: + :param header: (0) Number of header lines, these lines will be skipped. + :type header: + :param cskip: (0) Number of 'column'/'character' to skip (dummy column) + :type cskip: + :param cskip_type: ('column') is 'cskip' a number of 'column' or 'character' to skip? + :type cskip_type: + :param axis: (False) Use as the values for the first column as variable axis (x values in y(x)) + :type axis: + :param idrow: (False) Is the first row representing the ids of var generated ? + :type idrow: + :param ids: (None) use the values in this list as variable ids (1 per column returned) + :type ids: + :param separators: ([';',',', ':']) List of character recognized as column separator + :type separators: + + :returns: List containing 1 transient varialbe per column in the files. + Variable ids are optionaly determined by first row. + Variable axis may be the first column + :rtype: list """ sep=[] diff --git a/Lib/averager.py b/Lib/averager.py index 26623f5..54d6c0f 100644 --- a/Lib/averager.py +++ b/Lib/averager.py @@ -14,7 +14,14 @@ def __str__(self): def _check_axisoptions(x, axisoptions): - """checks the axis=options to make sure that it is valid""" + """ + Checks the axis=options to make sure that it is valid + + :param x: An axis + :type x: + :param axisoptions: String containing axis options + :type axisoptions: str + """ axlist = cdms2.orderparse(axisoptions) if Ellipsis in axlist: raise AveragerError, 'Error: Ellipsis (...) not allowed in axis options' @@ -26,7 +33,8 @@ def _check_axisoptions(x, axisoptions): def __myGetAxisWeights(x, i, axisoptions=None): - """ Assume x is an MV2 duh! and get the weights associated with axis index i. + """ + Assume x is an MV2 duh! and get the weights associated with axis index i. index i can be any of the dimensions in x whose bounds are available. If bounds are not available then an error is raised. """ @@ -62,6 +70,9 @@ def getAxisWeight(x, i): """ This returns the axis weights as generated by __myGetAxisWeights except it is returned as an MV2! + + :param x: + :param i: """ try: wts = __myGetAxisWeights(x, i) @@ -72,7 +83,8 @@ def getAxisWeight(x, i): return wtTV def __myGetAxisWeightsByName(x, name): - """ Get the weights associated with axis name. + """ + Get the weights associated with axis name. The name can be any of the dimensions in x whose bounds are available. If bounds are not available then an error is raised. @@ -103,6 +115,11 @@ def getAxisWeightByName(x, name): This returns the axis weights as generated by __myGetAxisWeights except it is returned as an MV2! + + :param x: CDMS2 axis + :type x: + :param name: String name of an axis + :type name: """ try: wts = __myGetAxisWeightsByName(x, name) @@ -114,7 +131,7 @@ def getAxisWeightByName(x, name): def area_weights(ds,axisoptions=None): - ''' + """ Calculates masked area weights. Author: Charles Doutriaux: doutriaux@llnl.gov @@ -124,7 +141,7 @@ def area_weights(ds,axisoptions=None): Returns a masked array of the same dimensions as ds containing area weights but masked where ds is masked. - ''' + """ cdat_info.pingPCMDIdb("cdat","genutil.area_weights") # __DEBUG__ = 0 From 491be4781ddf58a9d7967eb2bfb38ffa668decac Mon Sep 17 00:00:00 2001 From: embrown Date: Tue, 4 Oct 2016 18:00:13 -0700 Subject: [PATCH 2/5] Editing genutil docstrings --- Lib/Filler.py | 11 +- Lib/Statusbar_Pmw.py | 3 +- Lib/averager.py | 330 ++++++++++----------- Lib/colors.py | 52 ++-- Lib/filters.py | 63 ++-- Lib/grower.py | 26 +- Lib/minmax.py | 64 ++-- Lib/salstat.py | 438 ++++++++++++++++++++-------- Lib/selval.py | 10 +- Lib/statistics.py | 679 ++++++++++++++++++++++++------------------- Lib/statusbar.py | 4 +- 11 files changed, 978 insertions(+), 702 deletions(-) diff --git a/Lib/Filler.py b/Lib/Filler.py index 6ac60da..87fc644 100644 --- a/Lib/Filler.py +++ b/Lib/Filler.py @@ -1,19 +1,20 @@ import cdat_info class StringConstructor: - """ This Class aims at spotting keyword in string and replacing them + """ + This class aims at spotting keywords in a string and replacing them + Usage Filler=StringConstructor(template) or Filler=StringConstructor() Filler.template=template - template is a string of form - template = 'my string here with %(keywords) in it' + template is a string of form: 'my string here with %(keywords) in it' You can have has many 'keyword' as you want, and use them as many times as you want keywords are delimited on the left by %( and ) on the right - In order to construct the string (i.e. replace keywrods with some values: + In order to construct the string (i.e. replace keywords with some values: str=Filler(keyword='kwstr') or @@ -59,7 +60,7 @@ def keys(self,template=None): def construct(self,template=None,**kw): """ - construct, accepts a string with a unlimited number of keyword to replace + Accepts a string with a unlimited number of keyword to replace keyword to replace must be in the format %(keyword) within the string keyword value are either passed as keyword to the construct function or preset Example: diff --git a/Lib/Statusbar_Pmw.py b/Lib/Statusbar_Pmw.py index ef4f223..62f54ad 100644 --- a/Lib/Statusbar_Pmw.py +++ b/Lib/Statusbar_Pmw.py @@ -1,6 +1,7 @@ import Pmw, Tkinter class Statusbar(Pmw.MegaWidget): - """ Megawidget containing a scale and an indicator. + """ + Megawidget containing a scale and an indicator. """ def show(self,value): diff --git a/Lib/averager.py b/Lib/averager.py index 54d6c0f..2659ee1 100644 --- a/Lib/averager.py +++ b/Lib/averager.py @@ -17,8 +17,8 @@ def _check_axisoptions(x, axisoptions): """ Checks the axis=options to make sure that it is valid - :param x: An axis - :type x: + :param x: A CDMS TransientVariable + :type x: cdms.tvariable.TransientVariable :param axisoptions: String containing axis options :type axisoptions: str """ @@ -51,7 +51,7 @@ def __myGetAxisWeights(x, i, axisoptions=None): else: axis_bounds = x.getAxis(i).getBounds() if axis_bounds is None: - ax=x.getAxis(i) + ax=x.getAxis(i) if axisoptions is not None: axo=cdms2.orderparse(axisoptions) if (i in axo ) or (ax.isTime() and 't' in axo) or (ax.isLevel() and 'z' in axo) or ('('+ax.id+')' in axo): @@ -71,8 +71,13 @@ def getAxisWeight(x, i): This returns the axis weights as generated by __myGetAxisWeights except it is returned as an MV2! - :param x: - :param i: + :param x: A CDMS TransientVariable + :type x: cdms.tvariable.TransientVariable + :param i: The index of an axis on x + :type i: int + + :returns: A CDMS TransientVariable containing the axis weights + :rtype: cdms.tvariable.TransientVariable """ try: wts = __myGetAxisWeights(x, i) @@ -116,10 +121,10 @@ def getAxisWeightByName(x, name): This returns the axis weights as generated by __myGetAxisWeights except it is returned as an MV2! - :param x: CDMS2 axis - :type x: + :param x: A CDMS TransientVariable + :type x: cdms.tvariable.TransientVariable :param name: String name of an axis - :type name: + :type name: str """ try: wts = __myGetAxisWeightsByName(x, name) @@ -139,14 +144,20 @@ def area_weights(ds,axisoptions=None): Modified version using CDAT 3.0 by Paul Dubois Further modified by Krishna AchutaRao to return weights in all axes. - Returns a masked array of the same dimensions as ds containing area weights - but masked where ds is masked. + :param ds: A CDMS TransientVariable + :type ds: cdms.tvariable.TransientVariable + + :param axisoptions: String containing axis options + :type axisoptions: str + + :returns: A masked array of the same dimensions as ds containing area weights, but masked where ds is masked. + :rtype: cdms.tvariable.TransientVariable """ cdat_info.pingPCMDIdb("cdat","genutil.area_weights") # __DEBUG__ = 0 # - if __DEBUG__: print 'Incoming axisoptinos = ', axisoptions + if __DEBUG__: print 'Incoming axisoptions = ', axisoptions if __DEBUG__: print 'Shape of Incoming data = ', ds.shape seenlon = 0 seenlat = 0 @@ -315,14 +326,14 @@ def __check_weightoptions(x, axisoptions, weightoptions): Default: 'weighted' - weight options are one of 'weighted', 'unweighted', an array of weights for each - dimension or a MaskedVariable of the same shape as the data x. - - 'weighted' means use the grid information to generate weights for that - dimension or if multiple axes are passed, generate goes ahead and - generates the full masked area weights. - - 'unweighted' means use equal weights for all the grid points in that axis. - - Also an array of weights (of the same shape as the dimension being - averaged over or same shape as V) can be passed. + :param weightoptions: One of 'weighted', 'unweighted', an array of weights for each dimension or a MaskedVariable + of the same shape as the data x. + - 'weighted' means use the grid information to generate weights for that + dimension or if multiple axes are passed, generate goes ahead and + generates the full masked area weights. + - 'unweighted' means use equal weights for all the grid points in that axis. + - Also an array of weights (of the same shape as the dimension being + averaged over or same shape as V) can be passed. """ # # Since the _check_axisoptions was passed, the variable x has already been reordered @@ -609,18 +620,19 @@ def _check_MA_axisoptions(axisoption, N_dim): def sum_engine(x, wts): """ The work horse that does the summing ! This is specific to summing. - We will always be dealing with the first dimension.....and x is already in + We will always be dealing with the first dimension, and x is already in the order we will sum. 1-d wts are always numpy arrays or 'equal' Multi-dimensional arrays are always MV2's - - Inputs: - x : the input array (can be MV2 or MA) - wts : the input weight array (numpy array or MV2 or 'equal') - - Returned: - y : The weighted sum (summed over the first dimension) - return_wts : The sum of weights (summed over the first dimension) + + :param x: the input array (can be MV2 or MA) + :type: MV2 or MA + + :param wts: the input weight array + :type wts: numpy array or MV2 or 'equal' + + :returns y: The weighted sum (summed over the first dimension) + :returns return_wts: The sum of weights (summed over the first dimension) """ # __DEBUG__ = 0 @@ -659,11 +671,21 @@ def sum_engine(x, wts): def average_engine(x, wts): """ - The work horse that does the averaging! This is specific to averageing. - We will always be dealing with the first dimension.....and x is already in + The work horse that does the averaging! This is specific to averaging. + We will always be dealing with the first dimension, and x is already in the order we will average. 1-d wts are always numpy arrays or 'equal' Multi-dimensional arrays are always MV2's + + + :param x: the input array (can be MV2 or MA) + :type: MV2 or MA + + :param wts: the input weight array + :type wts: numpy array or MV2 or 'equal' + + :returns y: The weighted average (averaged over the first dimension) + :returns return_wts: The average of weights (averaged over the first dimension) """ # __DEBUG__ = 0 @@ -690,157 +712,139 @@ def average_engine(x, wts): def averager(V, axis=None, weights=None, action='average', returned=0, weight=None, combinewts=None): """ - Documentation for averager(): - ----------------------------- -The averager() function provides a convenient way of averaging your data giving -you control over the order of operations (i.e which dimensions are averaged -over first) and also the weighting for the different axes. You can pass your -own array of weights for each dimension or use the default (grid) weights or -specify equal weighting. - - -Author: Krishna AchutaRao : achutarao1@llnl.gov - -Returns: -------- - The average over the specified dimensions. -Usage: ------- -from cdutil import averager -averager( V, axis='axisoptions', weights=weightoptions, action='average', - returned='0') - -Where V is an array. It can be an array of numpy, numpy.ma or MV2 type. In each case -the function returns an array (except when it results in a scalar) of the same -type as V. See examples for more details. - -Optional Arguments: -------------------- -axis=axisoptions - Restrictions: axisoptions has to be a string - Default : first dimension in the data you pass to the function. + The averager() function provides a convenient way of averaging your data giving + you control over the order of operations (i.e which dimensions are averaged + over first) and also the weighting for the different axes. You can pass your + own array of weights for each dimension or use the default (grid) weights or + specify equal weighting. + + + Author: Krishna AchutaRao : achutarao1@llnl.gov + + :returns: The average over the specified dimensions. + + Usage: + ------ + + .. code-block:: python + + from cdutil import averager + averager( V, axis='axisoptions', weights=weightoptions, action='average', + returned='0') + Where V is an array. It can be an array of numpy, numpy.ma or MV2 type. In each case + the function returns an array (except when it results in a scalar) of the same + type as V. See examples for more details. + + :param axis: String specifying axisoptions. + Default: first dimension in the data you pass to the function. You can pass axis='tyx', or '123', or 'x (plev)' etc. the same way as in order= options for variable operations EXCEPT that '...'(i.e Ellipses) are not allowed. In the case that V is a numpy or numpy.ma array, axis names have no meaning and only axis indexes are valid. + :type axis: string + + :param weights: String specifying weight options, or a + Default: -weights=weightoptions - Default : - 'weighted' for Transient Variables (MV2s) - 'unweighted' for numpy.ma or numpy arrays. + 'weighted' for Transient Variables (MV2s) + 'unweighted' for numpy.ma or numpy arrays. Note that depending on the array being operated on by averager, the default weights change! - + Weight options are one of 'weighted', 'unweighted', an array of weights for each dimension or a MaskedVariable of the same shape as the data x. - - 'weighted' means use the grid information to generate weights for - that dimension. + - 'weighted' means use the grid information to generate weights for + that dimension. - - 'unweighted' means use equal weights for all the grid points in that axis. + - 'unweighted' means use equal weights for all the grid points in that axis. - - Also an array of weights (of the same shape as the dimension being - averaged over or same shape as V) can be passed. + - Also an array of weights (of the same shape as the dimension being + averaged over or same shape as V) can be passed. - Additional Notes on 'weighted' option: The weights are generated - using the bounds for the specified axis. For latitude and Longitude, - the weights are calculated using the area (see the cdms2 manual - grid.getWeights() for more details) whereas for the other axes - weights are the difference between the bounds (when the bounds are - available). If the bounds are stored in the file being read in, then - those values are used. Otherwise, bounds are generated as long as - cdms2.setAutoBounds('on') is set. If cdms2.setAutoBounds() is set to - 'off', then an Error is raised. + .. note:: -action='average' or 'sum' - Default : 'average' + The weights are generated using the bounds for the specified axis. + For latitude and Longitude, the weights are calculated using the area (see the cdms2 manual + grid.getWeights() for more details) whereas for the other axes weights are the difference + between the bounds (when the bounds are available). + If the bounds are stored in the file being read in, then + those values are used. Otherwise, bounds are generated as long as + cdms2.setAutoBounds('on') is set. + If cdms2.setAutoBounds() is set to 'off', then an Error is raised. - You can either return the weighted average or the weighted sum of the - data by specifying the keyword argument action= - -returned = 0 or 1 - Default: 0 - - - 0 implies sum of weights are not returned after averaging operation. - - 1 implies the sum of weights after the average operation is returned. - -combinewts = None, 0 or 1 - Default: None - same as 0 - - 0 implies weights passed for individual axes are not combined into one - weight array for the full variable V before performing operation. - - 1 implies weights passed for individual axes are combined into one - weight array for the full variable before performing average or sum - operations. One-dimensional weight arrays or key words of 'weighted' or - 'unweighted' must be passed for the axes over which the operation is - to be performed. Additionally, weights for axes that are not being - averaged or summed may also bepassed in the order in which they appear. - If the weights for the other axes are not passed, they are assumed to - be equally weighted. - -Examples: ---------- - >>> f = cdms2.open('data_file_name') - >>> averager(f('variable_name'), axis='1') - # extracts the variable 'variable_name' from f and averages over the - # dimension whose position is 1. Since no other options are specified, - # defaults kick in i.e weight='weighted' and returned=0 - - >>> averager(V, axis='xy', weights=['weighted','unweighted']) - or - >>> averager(V, axis='t', weights='unweighted') - or - >>> averager(V, axis='x') - # Default weights option of 'weighted' is implemented - or - >>> averager(V, axis='x', weights=mywts) - # where mywts is an array of shape (len(xaxis)) or shape(V) - or - >>> averager(V, axis='(lon)y', weights=[myxwts, myywts]) - # where myxwts is of shape len(xaxis) and myywts is of shape len(yaxis) - or - >>> averager(V, axis='xy', weights=V_wts) - # where V_wts is a Masked Variable of shape V - or - >>> averager(V, axis='x', weights='unweighted', action='sum') - # will return the equally weighted sum over the x dimension - or - >>> ywt = area_weights(y) - >>> fractional_area = averager(ywt, axis='xy', - weights=['unweighted', 'unweighted'], action='sum') - # is a good way to compute the area fraction that the - # data y that is non-missing - -Note: ------ - When averaging data with missing values, extra care needs to be taken. - It is recommended that you use the default weights='weighted' option. - This uses cdutil.area_weights(V) to get the correct weights to - pass to the averager. - >>> averager(V, axis='xy', weights='weighted') - - The above is equivalent to: - >>> V_wts = cdutil.area_weights(V) - >>> result = averager(V, axis='xy', weights=V_wts) - or - >>> result = averager(V, axis='xy', weights=cdutil.area_weights(V)) - - However, the area_weights function requires that the axis bounds are - stored or can be calculated (see documentation of area_weights for more - details). In the case that such weights are not stored with the axis - specifications (or the user desires to specify weights from another - source), the use of combinewts option can produce the same results. - In short, the following two are equivalent: - >>> xavg_1 = averager(X, axis = 'xy', weights = area_weights(X)) - >>> xavg_2 = averager(X, axis = 'xy', weights = ['weighted', 'weighted', 'weighted'], combinewts=1) - - Where X is a function of x, y and a third dimension such as time or level. - - In general, the above can be substituted with arrays of weights where - the 'weighted' keyword appears. - """ + :type weights: str + + :param action: One of 'average' or 'sum'. Specifies whether to return the weighted average or weighted sum of data. + Default: 'average' + :type action: str + + :param returned: Integer flag indicating whether or not the weighted average should be returned. + * 0 implies sum of weights are not returned after averaging operation. + * 1 implies the sum of weights after the average operation is returned. + :type returned: int + + :param combinewts: Integer flag indicating whether or not weights passed in for axes should be combined. + * 0 implies weights passed for individual axes are not combined into one + weight array for the full variable V before performing operation. + * 1 implies weights passed for individual axes are combined into one + weight array for the full variable before performing average or sum + operations. One-dimensional weight arrays or key words of 'weighted' or + 'unweighted' must be passed for the axes over which the operation is + to be performed. Additionally, weights for axes that are not being + averaged or summed may also bepassed in the order in which they appear. + If the weights for the other axes are not passed, they are assumed to + be equally weighted. + + :Examples: + + .. code-block:: python + + >>> f = cdms2.open('data_file_name') + >>> averager(f('variable_name'), axis='1') + # extracts the variable 'variable_name' from f and averages over the + # dimension whose position is 1. Since no other options are specified, + # defaults kick in i.e weight='weighted' and returned=0 + >>> averager(V, axis='xy', weights=['weighted','unweighted']) + >>> averager(V, axis='t', weights='unweighted') + >>> averager(V, axis='x') # Default weights option of 'weighted' is implemented + >>> averager(V, axis='x', weights=mywts) # where mywts is an array of shape (len(xaxis)) or shape(V) + >>> averager(V, axis='(lon)y', weights=[xwts, ywts]) # xwts of shape len(xaxis), ywts of shape len(yaxis) + >>> averager(V, axis='xy', weights=V_wts) # where V_wts is a Masked Variable of shape V + >>> averager(V, axis='x', weights='unweighted', action='sum') # equally weighted sum over the x dimension + + >>> ywt = area_weights(y) # These 2 lines compute the area fraction that the data y that is non-missing + >>> fractional_area = averager(ywt, axis='xy', weights=['unweighted', 'unweighted'], action='sum') + + .. note:: + + When averaging data with missing values, extra care needs to be taken. + It is recommended that you use the default weights='weighted' option. + This uses cdutil.area_weights(V) to get the correct weights to + pass to the averager. + + >>> averager(V, axis='xy', weights='weighted')` + The above is equivalent to: + + >>> V_wts = cdutil.area_weights(V) + >>> result = averager(V, axis='xy', weights=V_wts) + >>> result = averager(V, axis='xy', weights=cdutil.area_weights(V)) + + However, the area_weights function requires that the axis bounds are + stored or can be calculated (see documentation of area_weights for more + details). In the case that such weights are not stored with the axis + specifications (or the user desires to specify weights from another + source), the use of combinewts option can produce the same results. + In short, the following two are equivalent: + >>> xavg_1 = averager(X, axis = 'xy', weights = area_weights(X)) + >>> xavg_2 = averager(X, axis = 'xy', weights = ['weighted', 'weighted', 'weighted'], combinewts=1) + Where X is a function of x, y and a third dimension such as time or level. + In general, the above can be substituted with arrays of weights where + the 'weighted' keyword appears. + """ __DEBUG__ = 0 cdat_info.pingPCMDIdb("cdat","genutil.averager") # diff --git a/Lib/colors.py b/Lib/colors.py index c99a899..4c504b7 100644 --- a/Lib/colors.py +++ b/Lib/colors.py @@ -653,20 +653,23 @@ } def str2rgb(col): """ - Function: str2rgb + Given a string representing a color name, this function returns the + corresponding r,g,b values (between 0 and 255). If the color + name is unknown, the function returns None,None,None. - Description of function: - Given a string representing a color name, this function the - corresponding r,g,b values (between 0 and 255). If the color - name is unknown, the function returns None,None,None + This is accomplished by looking in the /usr/X11R6/lib/X11/rgb.txt + file. If the file does not exist, then looks into the builtin + dictionary. - This is accomplished by looking in the /usr/X11R6/lib/X11/rgb.txt - file. If the file does not exist, then looks into the builtin - dictionary - - Examples: - >>> r, g, b = str2rgb('pink2') # returns: (238 , 169 , 184 ) - >>> r, g, b = str2rgb('crapy') # returns: (None, None, None) + :Example: + + .. doctest:: genutil_colors_str2rgb + + >>> r, g, b = str2rgb('pink2') # returns: (238 , 169 , 184 ) + >>> r, g, b = str2rgb('cray') # returns: (None, None, None) + + :param col: String name of a color. + :type col: str """ import string ret=[] @@ -694,14 +697,14 @@ def str2rgb(col): def rgb2str(r,g=None,b=None): """ - Function: rgb2str - - Description of function: - Given r,g,b values, this function returns the closest 'name' + Given r,g,b values, this function returns the closest 'name'. - Example: - >>> print rgb2str([0,0,0]) - 'black' + :Example: + + .. doctest:: genutil_colors_rgb2str + + >>> print rgb2str([0,0,0]) + 'black' """ import string if g is None and len(r)==3: @@ -735,14 +738,3 @@ def rgb2str(r,g=None,b=None): if rms==0.: return ret return ret - - -if __name__=='__main__': - print str2rgb('pink2') - print str2rgb('black') - print str2rgb('crap') - print rgb2str(255,255,255) - print rgb2str([0,0,0]) - print rgb2str(str2rgb('pink2')) - print rgb2str([241,255,255]) - print rgb2str(69,184,67) diff --git a/Lib/filters.py b/Lib/filters.py index 25df30e..5af26cb 100644 --- a/Lib/filters.py +++ b/Lib/filters.py @@ -3,19 +3,22 @@ import numpy,cdms2,MV2,genutil import cdat_info + def custom1D(x,filter,axis=0): """ - Function: custom(x,filter,axis=0) - - Description of function: - Apply a custom 1 dimensional filter to an array over a specified axis - filter can be a list of numbers or a 1D array - Usage: - filtered = custom1D(x,filter) - Options: - axisoptions: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + Apply a custom 1 dimensional filter to an array over a specified axis + filter can be a list of numbers or a 1D array + + :param x: A CDMS TransientVariable + :type x: + + :param filter: + :type filter: + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. + :type axis: str or int """ cdat_info.pingPCMDIdb("cdat","genutil.filters.custom1D") isMV2=cdms2.isVariable(x) @@ -71,31 +74,39 @@ def custom1D(x,filter,axis=0): def smooth121(x,axis=0): """ - Function smooth121(x,axis=0) - - Description of function: - Apply a 121 filter to an array over a specified axis - Usage: - filtered = smooth121(unfiltered) - Options: - axisoptions: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + Apply a 121 filter to an array over a specified axis + + :Example: + + .. doctest:: genutil_filters_smooth121 + + >>> filtered = smooth121(unfiltered) + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. """ cdat_info.pingPCMDIdb("cdat","genutil.filters.smooth121") return custom1D(x,[1.,2.,1.],axis=axis) + def runningaverage(x,N,axis=0): """ - Function runningaverage(x,N,axis=0) - - Description of function: - Apply a running average of length N to an array over a specified axis - Usage: - smooth = runningaverage(x,12) - Options: - N: length of the running average - axisoptions: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + Apply a running average of length N to an array over a specified axis + + :Example: + + .. doctest:: genutil_filters_runningaverage + + >>> smooth = runningaverage(x,12) + + :param x: + :type x: + + :param N: length of the running average + :type N: int + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. """ diff --git a/Lib/grower.py b/Lib/grower.py index 2a63326..51cf055 100644 --- a/Lib/grower.py +++ b/Lib/grower.py @@ -5,19 +5,23 @@ def grower(x, y, singleton=0): """ - Function: grower - - Description of function: - This function takes 2 transient variables and grows them to - match their axes. + This function takes 2 transient variables and grows them to + match their axes. - Usage: - x, y = grower(x, y, singleton=singletonoption) + :Example: + + .. doctest:: genutil_grower + >>> x, y = grower(x, y, singleton=1) + + :param x: + :type x: + + :param y: + :type y: - Options: - singletonoption 0 | 1 - Default = 0 If singletonoption is set to 1 then an error is - raised if one of the dims is not a singleton dimension. + :param singletonoption: Integer flag to indicate whether to raise an error if either dimension is not a singleton. + Default = 0 + If singletonoption is set to 1 then an error is raised if one of the dims is not a singleton dimension. """ # Parse the x axes xorder=x.getOrder(ids=1) diff --git a/Lib/minmax.py b/Lib/minmax.py index e82cc67..f265995 100644 --- a/Lib/minmax.py +++ b/Lib/minmax.py @@ -2,38 +2,38 @@ import cdat_info # Adapted for numpy/ma/cdms2 by convertcdms.py def minmax(*data) : - """ - Function : minmax - - Description of Function: + """ Returns the minimum and maximum of a series of arrays/lists/tuples (or a combination of these) You can combine list/tuples/... pretty much any combination is allowed. - Examples of Use - >>> import genutil - >>> s = range(7) - >>> genutil.minmax(s) - (0.0, 6.0) - >>> genutil.minmax([s,s]) - (0.0, 6.0) - >>> genutil.minmax([[s,s*2],4.,[6.,7.,s]],[5.,-7.,8,(6.,1.)]) - (-7.0, 8.0) - """ - cdat_info.pingPCMDIdb("cdat","genutil.minmax") - mx=numpy.finfo(numpy.float).min - mn=numpy.finfo(numpy.float).max - if len(data)==1 : data=data[0] - global myfunction - def myfunction(d,mx,mn): - from numpy.ma import maximum,minimum,absolute,greater,count - try: - if count(d)==0 : return mx,mn - mx=float(maximum(mx,float(maximum(d)))) - mn=float(minimum(mn,float(minimum(d)))) - except: - for i in d: - mx,mn=myfunction(i,mx,mn) - return mx,mn - mx,mn=myfunction(data,mx,mn) - if mn==1.E500 and mx==-1.E500 :mn=mx=1.E500 - return mn,mx + :Example: + + .. doctest:: genutil_minmax + + >>> import genutil + >>> s = range(7) + >>> genutil.minmax(s) + (0.0, 6.0) + >>> genutil.minmax([s,s]) + (0.0, 6.0) + >>> genutil.minmax([[s,s*2],4.,[6.,7.,s]],[5.,-7.,8,(6.,1.)]) + (-7.0, 8.0) + """ + cdat_info.pingPCMDIdb("cdat","genutil.minmax") + mx=numpy.finfo(numpy.float).min + mn=numpy.finfo(numpy.float).max + if len(data)==1 : data=data[0] + global myfunction + def myfunction(d,mx,mn): + from numpy.ma import maximum,minimum,absolute,greater,count + try: + if count(d)==0 : return mx,mn + mx=float(maximum(mx,float(maximum(d)))) + mn=float(minimum(mn,float(minimum(d)))) + except: + for i in d: + mx,mn=myfunction(i,mx,mn) + return mx,mn + mx,mn=myfunction(data,mx,mn) + if mn==1.E500 and mx==-1.E500 :mn=mx=1.E500 + return mn,mx diff --git a/Lib/salstat.py b/Lib/salstat.py index 74a6dc7..99cb602 100644 --- a/Lib/salstat.py +++ b/Lib/salstat.py @@ -1,7 +1,8 @@ -# Adapted for numpy/ma/cdms2 by convertcdms.py -# stats.py - reworked module for statistical analysis """ -This module has been written specifically for the SalStat statistics package. +Adapted for numpy/ma/cdms2 by convertcdms.py +stats.py - reworked module for statistical analysis + +This module has been written specifically for the SalStat statistics package. It is an object oriented (and more limited) version of Gary Strangmans stats.y module, and much code has been taken from there. The classes and methods are usable from the command line, and some may prefer the OO style @@ -13,7 +14,8 @@ Other parts of this code were taken from stats.py by Gary Strangman of Harvard University (c) Not sure what year, Gary Strangman, released under the -GNU General Public License.""" +GNU General Public License. +""" import numpy.ma,cdms2,array_indexing_emulate as array_indexing from statistics import __checker @@ -25,6 +27,7 @@ sum=numpy.ma.sum mean=numpy.ma.average # Shortcut + def _fixScalar(a): if isinstance(a,(float,int)) or a.shape==(): a=numpy.ma.array([a,],copy=0) @@ -32,8 +35,11 @@ def _fixScalar(a): else: return a -## Diference Squared + +# Diference Squared def _diffsquared(a,b): return numpy.ma.power(a-b,2) + + def differencesquared(x,y,axis=0): """Computes the Squared differecne between 2 datasets Usage: @@ -62,7 +68,8 @@ def differencesquared(x,y,axis=0): diff=diff.filled(1.e20) return diff -## No need to make it user available + +# No need to make it user available def _shellsort(inlist): """ _shellsort algorithm. Sorts a 1D-list. @@ -71,10 +78,11 @@ def _shellsort(inlist): """ return numpy.ma.sort(inlist,axis=0),numpy.ma.argsort(inlist,axis=0) -## Rankdata + +# Rankdata def _rankdata(inlist): """ - Ranks the data in inlist, dealing with ties appropritely. + Ranks the data in inlist, dealing with ties appropriately. Adapted from Gary Perlman's |Stat ranksort. Usage: _rankdata(inlist) @@ -103,21 +111,33 @@ def _rankdata(inlist): sumranks = numpy.ma.where(c1,0.,sumranks) dupcount = numpy.ma.where(c1,0,dupcount) for i in range(n): - newlist2=array_indexing.set(newlist2,ivec[i],newlist[i]) + newlist2=array_indexing.set(newlist2,ivec[i],newlist[i]) return newlist2 + + def rankdata(x,axis=0): """ - Ranks the data, dealing with ties appropritely. + Ranks the data, dealing with ties appropriately. Adapted from Gary Perlman's |Stat ranksort. Further adapted to numpy.ma/numpy by PCMDI's team - Usage: rankdata(array, axis=axisoptions) - Returns: a list of length equal to inlist, containing rank scores - Option: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :Example: + + .. doctest:: genutil_salstat_rankdata + + >>> rankdata(array, axis=axisoptions) + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. even: 'xy': to do over 2 dimensions at once + :type axis: str or int + + :param x: + :type x: + + :returns: A list of length containing rank scores + :rtype: list """ x = _fixScalar(x) if cdms2.isVariable(x) : xatt=x.attributes @@ -139,7 +159,7 @@ def _tiecorrect(rankvals): Corrects for ties in Mann Whitney U and Kruskal Wallis H tests. See Siegel, S. (1956) Nonparametric Statistics for the Behavioral Sciences. New York: McGraw-Hill. Code adapted from |Stat rankind.c code. - + Usage: _tiecorrect(rankvals) Returns: T correction factor for U or H """ @@ -171,13 +191,21 @@ def tiecorrect(x,axis=0): Corrects for ties in Mann Whitney U and Kruskal Wallis H tests. See Siegel, S. (1956) Nonparametric Statistics for the Behavioral Sciences. New York: McGraw-Hill. Code adapted from |Stat rankind.c code. - - Usage: T = tiecorrect(rankvals,axis=axisoptions) - Option: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :Example: + + .. doctest:: genutil_salstat_tiecorrect + + >>> T = tiecorrect(rankvals,axis=axisoptions) + + :param x: + :type x: + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. even: 'xy': to do over 2 dimensions at once + :type axis: """ x = _fixScalar(x) if cdms2.isVariable(x) : xatt=x.attributes @@ -199,12 +227,12 @@ def tiecorrect(x,axis=0): ########################### ## Probability functions ## ########################### - + def _chisqprob(chisq,df,Z_MAX=6.0): """ Returns the (1-tailed) probability value associated with the provided chi-square value and df. Adapted from chisq.c in Gary Perlman's |Stat. - + Usage: _chisqprob(chisq,df,Z_MAX=6.0) """ BIG = 20.0 @@ -256,10 +284,21 @@ def chisqprob(chisq,df,Z_MAX=6.0): """ Returns the (1-tailed) probability value associated with the provided chi-square value and df. Adapted from chisq.c in Gary Perlman's |Stat. - - Usage: prob = chisqprob(chisq,df) - Options: - Z_MAX: Maximum meaningfull value for z probability (default=6.0) + + :Example: + + .. doctest:: genutil_salstat_chisqprob + + >>> csprob = chisqprob(chisq,df) + + :param chisq: + :type chisq: + + :param df: + :type df: + + :param Z_MAX: Maximum meaningful value for z probability (default=6.0) + :type Z_MAX: float """ chisq = _fixScalar(chisq) df = _fixScalar(df) @@ -277,9 +316,9 @@ def chisqprob(chisq,df,Z_MAX=6.0): def _inversechi(prob, df): """This function calculates the inverse of the chi square function. Given - a p-value and a df, it should approximate the critical value needed to + a p-value and a df, it should approximate the critical value needed to achieve these functions. Adapted from Gary Perlmans critchi function in - C. Apologies if this breaks copyright, but no copyright notice was + C. Apologies if this breaks copyright, but no copyright notice was attached to the relevant file. """ minchisq = numpy.ma.zeros(df.shape) @@ -303,12 +342,23 @@ def _inversechi(prob, df): return chisqval def inversechi(prob, df): - """This function calculates the inverse of the chi square function. Given - a p-value and a df, it should approximate the critical value needed to + """ + This function calculates the inverse of the chi square function. Given + a p-value and a df, it should approximate the critical value needed to achieve these functions. Adapted from Gary Perlmans critchi function in - C. Apologies if this breaks copyright, but no copyright notice was + C. Apologies if this breaks copyright, but no copyright notice was attached to the relevant file. - Usage invchi = inversechi(prob,df,axis=axisoptions) + + :Example: + + .. doctest:: genutil_salstat_inversechi + + >>> invchi = inversechi(prob,df,axis=axisoptions) + :param prob: + :type prob: + + :param df: + :type df: """ prob = _fixScalar(prob) df = _fixScalar(df) @@ -328,7 +378,7 @@ def _erfcc(x): """ Returns the complementary error function erfc(x) with fractional error everywhere less than 1.2e-7. Adapted from MAal Recipies. - + Usage: _erfcc(x) """ z = numpy.ma.absolute(x) @@ -345,13 +395,17 @@ def erfcc(x): """ Returns the complementary error function erfc(x) with fractional error everywhere less than 1.2e-7. Adapted from MAal Recipies. - - Usage: err = erfcc(x) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n - default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + + :Example: + + .. doctest:: genutil_salstat_erfcc + + >>> err = erfcc(x) + :param x: + :type x: + + :returns: + :rtype: cdms.tvariable.TransientVariable """ x = _fixScalar(x) isvar=0 @@ -366,16 +420,16 @@ def erfcc(x): err=err.filled(1.e20) return err - + def _zprob(z,Z_MAX = 6.0): """ Returns the area under the normal curve 'to the left of' the given z value. - Thus, + Thus, for z<0, _zprob(z) = 1-tail probability for z>0, 1.0-_zprob(z) = 1-tail probability for any z, 2.0*(1.0-_zprob(abs(z))) = 2-tail probability Adapted from z.c in Gary Perlman's |Stat. - + Usage: z = _zprob(z,Z_MAX = 6.0) """ @@ -407,15 +461,26 @@ def _zprob(z,Z_MAX = 6.0): def zprob(z,Z_MAX = 6.0): """ Returns the area under the normal curve 'to the left of' the given z value. - Thus, + Thus, for z<0, zprob(z) = 1-tail probability for z>0, 1.0-zprob(z) = 1-tail probability for any z, 2.0*(1.0-zprob(abs(z))) = 2-tail probability Adapted from z.c in Gary Perlman's |Stat. - Z_MAX: Maximum meaningfull value for z probability (default = 6) - - Usage: z = zprob(z,Z_MAX=6.0 ) + :Example: + + .. doctest:: genutil_salstat_zprob + + >>> z = zprob(z,Z_MAX=4.0) + + :param z: The Z-value + :type z: float + + :param Z_MAX: Maximum meaningful value for z probability (default = 6) + :type Z_MAX: float + + :returns: The area under the normal curve to the left of the given z value. + :rtype: float """ z = _fixScalar(z) isvar=0 @@ -470,7 +535,17 @@ def ksprob(x): Computes a Kolmolgorov-Smirnov t-test significance level. Adapted from MAal Recipies. - Usage: ks = ksprob(x) + :Example: + + .. doctest:: genutil_salstat_ksprob + + >>> ks = ksprob(x) + + :param x: + :type x: + + :returns: + :rtype: """ x = _fixScalar(x) isvar=0 @@ -490,18 +565,34 @@ def _fprob (dfnum, dfden, F): Returns the (1-tailed) significance level (p-value) of an F statistic given the degrees of freedom for the numerator (dfR-dfF) and the degrees of freedom for the denominator (dfF). - + Usage: _fprob(dfnum, dfden, F) where usually dfnum=dfbn, dfden=dfwn """ return _betai(0.5*dfden, 0.5*dfnum, dfden/(dfden+dfnum*F)) - + def fprob (dfnum, dfden, F): """ - Returns the (1-tailed) significance level (p-value) of an F + Calculates the (1-tailed) significance level (p-value) of an F statistic given the degrees of freedom for the numerator (dfR-dfF) and the degrees of freedom for the denominator (dfF). - - Usage: prob = fprob(dfnum, dfden, F) where usually dfnum=dfbn, dfden=dfwn + + :Example: + + .. doctest:: genutil_salstat_fprob + + >>> prob = fprob(dfnum, dfden, F) # where usually dfnum=dfbn, dfden=dfwn + + :param dfnum: + :type dfnum: + + :param dfden: + :type dfden: + + :param F: + :type F: + + :returns: The p-value of an F statistic. + :rtype: float """ dfnum = _fixScalar(dfnum) dfden = _fixScalar(dfden) @@ -522,8 +613,23 @@ def _tprob(df, t): return _betai(0.5*df,numpy.ma.ones(df.shape)*0.5,df/(1.*df+t*t)) def tprob(df, t): - """Returns t probabilty given degree of freedom and T statistic - Usage: prob = tprob(df,t) + """ + Calculates t probabilty given degree of freedom and T statistic + + :Example: + + .. doctest:: genutil_salstat_tprob + + >>> prob = tprob(df,t) + + :param df: + :type df: + + :param t: + :type t: + + :returns: The t probability of a T statistic + :rtype: float """ df = _fixScalar(df) t = _fixScalar(t) @@ -538,11 +644,11 @@ def tprob(df, t): if not numpy.ma.isMA(t): prob=prob.filled(1.e20) return prob - + def _inversef(prob, df1, df2): """This function returns the f value for a given probability and 2 given degrees of freedom. It is an approximation using the fprob function. - Adapted from Gary Perlmans critf function - apologies if copyright is + Adapted from Gary Perlmans critf function - apologies if copyright is broken, but no copyright notice was attached """ f_epsilon = 0.000001 maxf = numpy.ma.ones(prob.shape)*9999.0 @@ -562,16 +668,29 @@ def _inversef(prob, df1, df2): return fval def inversef(prob, df1, df2): - """This function returns the f value for a given probability and 2 given + """ + This function returns the f value for a given probability and 2 given degrees of freedom. It is an approximation using the fprob function. - Adapted from Gary Perlmans critf function - apologies if copyright is + Adapted from Gary Perlmans critf function - apologies if copyright is broken, but no copyright notice was attached - Usage: fval = inversef(prob, df1, df2) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n - default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + + :Example: + + .. doctest:: genutil_salstat_inversef + + >>> fval = inversef(prob, df1, df2) + + :param prob: The probability + :type prob: + + :param df1: Degree of freedom + :type df1: + + :param df2: Degree of freedom + :type df2: + + :returns: The f value for a given probability with 2 degrees of freedom + :rtype: """ prob = _fixScalar(prob) df1 = _fixScalar(df1) @@ -592,7 +711,7 @@ def _betacf(a,b,x,ITMAX=200,EPS=3.0E-7): """ This function evaluates the continued fraction form of the incomplete Beta function, betai. (Adapted from: MAal Recipies in C.) - + Usage: _betacf(a,b,x,ITMAX=200,EPS=3.0E-7) ITMAX: Maximum number of iteration EPS: Epsilon number @@ -633,8 +752,12 @@ def betacf(a,b,x,ITMAX=200,EPS=3.0E-7): """ This function evaluates the continued fraction form of the incomplete Beta function, betai. (Adapted from: MAal Recipies in C.) - - Usage: beta = betacf(a,b,x,ITMAX=200,EPS=3.0E-7) + + :Example: + + .. doctest:: + + beta = betacf(a,b,x,ITMAX=200,EPS=3.0E-7) ITMAX: Maximum number of iteration EPS: Epsilon number """ @@ -682,7 +805,11 @@ def gamma(x): Gamma(z) = Integral(0,infinity) of t^(z-1)exp(-t) dt. (Adapted from: MAal Recipies in C.) - Usage: _gammaln(xx) + :Example: + + .. doctest:: + + _gammaln(xx) """ x = _fixScalar(x) isvar=0 @@ -1355,7 +1482,11 @@ def OneSampleTTest(x,y,axis=0,df=1): """ This performs a single factor t test for a set of data and a user hypothesised mean value. - Usage: t, prob [,df] = OneSampleTTest(data, usermean, axis=axisoptions, df=1) + :Example: + + .. doctest:: + + t, prob [,df] = OneSampleTTest(data, usermean, axis=axisoptions, df=1) Options: axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index @@ -1503,7 +1634,11 @@ def _TTestUnpaired(data1, data2): def TTestUnpaired(x,y,axis=0,df=1): """ This performs an unpaired t-test. - Usage: t, prob, [df] = TTestUnpaired(data1, data2,axis=axisoptions, df=1) + :Example: + + .. doctest:: + + t, prob, [df] = TTestUnpaired(data1, data2,axis=axisoptions, df=1) Returns: t, df, prob Options: axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n @@ -1554,7 +1689,11 @@ def _TTestPaired(data1, data2): def TTestPaired(x,y,axis=0,df=1): """ This performs an paired t-test. - Usage: t, prob, [df] = TTestUnpaired(data1, data2,axis=axisoptions, df=1) + :Example: + + .. doctest:: + + t, prob, [df] = TTestUnpaired(data1, data2,axis=axisoptions, df=1) Options: axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index @@ -1608,14 +1747,26 @@ def _PearsonsCorrelation(data1, data2): def PearsonsCorrelation(x,y,axis=0,df=1): """ This method performs a Pearsons correlation upon two sets of data - Usage: r, t, prob, [df] = PearsonsCorrelation(data1, data2,axis=0,df=1) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :Example: + + .. doctest:: + + >>> r, t, prob, [df] = PearsonsCorrelation(data1, data2,axis=0,df=1) + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once + :type axis: str or int - df =0: if set to 1 returns degrees of freedom + :param x: + :type x: + + :param y: + :type y: + + :param df: If set to 1, returns degrees of freedom. Defaults to 0. + :type: int """ x = _fixScalar(x) y = _fixScalar(y) @@ -1657,9 +1808,12 @@ def FTest(data1, data2, uservar, axis=0, df=1): """ This method performs a F test for variance ratio and needs a user hypothesised variance to be supplied. - Usage: f, prob [,df1, df2] = FTest(data1, data2, uservar, axis=axisoptions, df=1) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :Example: + + .. doctest:: + + f, prob [,df1, df2] = FTest(data1, data2, uservar, axis=axisoptions, df=1) + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once @@ -1714,9 +1868,12 @@ def TwoSampleSignTest(x,y,axis=0): """ This method performs a 2 sample sign test for matched samples on 2 supplied data sets - Usage: nplus, nminus, ntotal, z, prob = TwoSampleSignTest(data1, data2) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :Example: + + .. doctest:: + + nplus, nminus, ntotal, z, prob = TwoSampleSignTest(data1, data2) + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once @@ -1781,9 +1938,12 @@ def _KendallsTau(data1, data2): def KendallsTau(x,y,axis=0): """ This method performs a Kendalls tau correlation upon 2 data sets. - Usage: tau, z, prob = KendallsTau(data1, data2) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :Example: + + .. doctest:: + + tau, z, prob = KendallsTau(data1, data2) + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once @@ -1853,9 +2013,12 @@ def KolmogorovSmirnov(x,y,axis=0): """ This method performs a Kolmogorov-Smirnov test for unmatched samples upon 2 data vectors. - Usage: ks, prob = KolmogorovSmirnov(data1, data2) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :Example: + + .. doctest:: + + ks, prob = KolmogorovSmirnov(data1, data2) + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once @@ -1896,9 +2059,12 @@ def _SpearmansCorrelation(data1, data2): def SpearmansCorrelation(x,y,axis=0,df=1): """ This method performs a Spearmans correlation upon 2 data sets - Usage: rho, t, df, prob = SpearmansCorrelation(data1, data2, axis=0, df=1) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :Example: + + .. doctest:: + + rho, t, df, prob = SpearmansCorrelation(data1, data2, axis=0, df=1) + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once @@ -1951,9 +2117,12 @@ def WilcoxonRankSums(x,y, Z_MAX = 6.0, axis=0): """ This method performs a Wilcoxon rank sums test for unpaired designs upon 2 data vectors. - Usage: z, prob = WilcoxonRankSums(data1, data2, Z_MAX = 6.0, axis=axisoption) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :Example: + + .. doctest:: + + z, prob = WilcoxonRankSums(data1, data2, Z_MAX = 6.0, axis=axisoption) + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once @@ -2009,9 +2178,12 @@ def WilcoxonSignedRanks(x,y, Z_MAX=6., axis=0): """ This method performs a Wilcoxon Signed Ranks test for matched samples upon 2 data set. - Usage: wt, z, prob = WilcoxonSignedRanks(data1, data2, Z_MAX = 6.0, axis=0) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :Example: + + .. doctest:: + + wt, z, prob = WilcoxonSignedRanks(data1, data2, Z_MAX = 6.0, axis=0) + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once @@ -2063,9 +2235,12 @@ def MannWhitneyU(x, y, Z_MAX=6.0, axis=0): """ This method performs a Mann Whitney U test for unmatched samples on 2 data vectors. - Usage: bigu, smallu, z, prob = MannWhitneyU(data1, data2, Z_MAX=6.0, axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :Example: + + .. doctest:: + + bigu, smallu, z, prob = MannWhitneyU(data1, data2, Z_MAX=6.0, axis=axisoptions) + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once @@ -2123,8 +2298,7 @@ def LinearRegression(x, y, df=1, axis=0): """ This method performs a linear regression upon 2 data vectors. Usage: r, t, prob, slope, intercept, sterrest [,df] = LinearRegression(x,y,df=1,axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once @@ -2188,9 +2362,12 @@ def PairedPermutation(x, y, nperm=None, axis=0): """ This method performs a permutation test for matched samples upon 2 set This code was modified from Segal and further modifed by C. Doutriaux - Usage: utail, crit, prob = PairedPermutation(x,y,nperm=None) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :Example: + + .. doctest:: + + utail, crit, prob = PairedPermutation(x,y,nperm=None) + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once @@ -2250,9 +2427,12 @@ def _ChiSquare(x, y): def ChiSquare(x, y, axis=0, df=1): """ This method performs a chi square on 2 data set. - Usage: chisq, df, prob = ChiSquare(x,y) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :Example: + + .. doctest:: + + chisq, df, prob = ChiSquare(x,y) + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once @@ -2343,8 +2523,7 @@ def anovaWithin( *inlist,**kw): Usage: SSint, SSres, SSbet, SStot, MSbet, MSwit, MSres, F, prob [, dfbet, dfwit, dfres, dftot] = anovaWithin(*inlist,axis=axisoptions). inlist, being as many arrays as you wish - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once @@ -2428,10 +2607,13 @@ def anovaBetween(*inlist,**kw): This method performs a univariate single factor between-subjects analysis of variance on a list of lists (or a numpy matrix). It is specialised for SalStat and best left alone. - Usage: SSbet, SSwit, SStot, MSbet, MSerr, F, prob [, dfbet, dferr, dftot] = anovaBetween(*arrays,axis=axisoptions). + :Example: + + .. doctest:: + + SSbet, SSwit, SStot, MSbet, MSerr, F, prob [, dfbet, dferr, dftot] = anovaBetween(*arrays,axis=axisoptions). inlist, being as many arrays as you wish - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once @@ -2514,10 +2696,13 @@ def KruskalWallisH(*inlist,**kw): """ This method performs a Kruskal Wallis test (like a nonparametric between subjects anova) on a serie of arrays. - Usage: h, df, prob = KruskalWallisH(*args,axis=axispoptions, df=1). + :Example: + + .. doctest:: + + h, df, prob = KruskalWallisH(*args,axis=axispoptions, df=1). inlist, being as many arrays as you wish - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once @@ -2586,10 +2771,13 @@ def FriedmanChiSquare( *inlist, **kw): """ This method performs a Friedman chi square (like a nonparametric within subjects anova) on a list of lists. - Usage: sumranks, chisq, df, prob = FriedmanChiSqure(*args, axis=axisoptions, df=1). + :Example: + + .. doctest:: + + sumranks, chisq, df, prob = FriedmanChiSqure(*args, axis=axisoptions, df=1). inlist, being as many arrays as you wish - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once @@ -2650,16 +2838,22 @@ def _CochranesQ( *inlist): def CochranesQ( *inlist,**kw): """ This method performs a Cochrances Q test upon a list of lists. - Usage: q, df, prob = CochranesQ(*inlist) + + :Example: + + .. doctest:: + + q, df, prob = CochranesQ(*inlist) inlist, being as many arrays as you wish - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once df=1 : if 1 then degrees of freedom are retuned - WARNING: axis and df MUST be passed as keyword, as all arguments are considered as arrays + .. warning:: + + axis and df MUST be passed as keyword, as all arguments are considered as arrays """ if len(inlist)<2: raise 'Error must have at least 2 arrays!' diff --git a/Lib/selval.py b/Lib/selval.py index 01b5b8a..d08649b 100644 --- a/Lib/selval.py +++ b/Lib/selval.py @@ -3,16 +3,16 @@ import MV2,numpy,cdtime import cdat_info class PickComponent(SelectorComponent): - ''' + """ Let the user pick non contiguous values along an axis keyword "match" is reserved for handling of inexisting values match=1 : (default): raise an exception if one of the select-values does not exist match=0 : replace inexistince selcet-values with missing match=-1: skip inexisting select-values - ''' + """ def __init__(self,*args,**kargs): - ''' initialise some value such as tolerances for equality''' + """ initialise some value such as tolerances for equality""" self.args=args self.kargs=kargs self.match=kargs.get('match',1) @@ -34,7 +34,7 @@ def __str__(self): return s def specify(self,slab,axes,specification,confined_by,aux): - ''' First part: confine the slab within a Domain wide enough to do the exact in post''' + """ First part: confine the slab within a Domain wide enough to do the exact in post""" import string,copy from numpy.ma import minimum,maximum # myconfined is for later, we can't confine a dimension twice with an argument plus a keyword or 2 keywords @@ -111,7 +111,7 @@ def specify(self,slab,axes,specification,confined_by,aux): return 0 def post(self,fetched,slab,axes,specifications,confined_by,aux,axismap): - ''' Post processing retouches the bounds and later will deal with the mask''' + """ Post processing retouches the bounds and later will deal with the mask""" import cdms2 as cdms fetched=cdms.createVariable(fetched,copy=1) faxes=fetched.getAxisList() diff --git a/Lib/statistics.py b/Lib/statistics.py index 4315451..fb31912 100644 --- a/Lib/statistics.py +++ b/Lib/statistics.py @@ -675,33 +675,39 @@ def __checker(x,y,w,axes,smally=0): def covariance(x,y,weights=None,axis=0,centered=1,biased=1,max_pct_missing=100.): """ - Function: covariance - - Description of function: - Returns the covariance between 2 slabs. By default on the first dimension, - centered and biased by default. - Usage: - cov = covariance(x, y, weights=weightoptions, axis=axisoptions, + Returns the covariance between 2 slabs. By default on the first dimension, + centered and biased by default. + + :Example: + + .. doctest:: + + >>> cov = covariance(x, y, weights=weightoptions, axis=axisoptions, centered=centeredoptions, biased=biasedoptions, max_pct_missing=max_pct_missingoptions) - Options: - weightoptions + :param weightoptions: default = None. If you want to compute the weighted covariance, provide the weights here. - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n - default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. - centeredoptions None | 0 | 1 - default value = 1 removes the mean first. Set to 0 or None for - uncentered. - biasedoptions None | 0 | 1 - default value = 1 If want to compute an unbiased variance pass - anything but 1. - max_pct_missingoptions - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked + :type weightoptions: + + :type axis: + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + default value = 0. You can pass the name of the dimension or index + (integer value 0...n) over which you want to compute the statistic. + :type centered: + :param centered: None | 0 | 1 + default value = 1 removes the mean first. Set to 0 or None for + uncentered. + :type biased: + :param biased: None | 0 | 1 + default value = 1 If want to compute an unbiased variance pass + anything but 1. + :type max_pct_missing: + :param max_pct_missing: + default value = 100. Maximum fraction of cell which is allowed to be masked (missing). + Set to a percentage between 0 and 100%. + Set to 0. to mask results if any data is masked. + Set to 100. to calculate result if any data is not masked """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.covariance") if cdms2.isVariable(x) : xatt=x.attributes @@ -718,32 +724,37 @@ def covariance(x,y,weights=None,axis=0,centered=1,biased=1,max_pct_missing=100.) def variance(x,weights=None,axis=0,centered=1,biased=1,max_pct_missing=100.): """ - Function: variance - - Description of function: - Returns the variance from a slab. By default on first dimension, - centered, and biased. - Usage: - result = variance(x, weights=weightoptions, axis = axisoptions, + Returns the variance from a slab. By default on first dimension, + centered, and biased. + + :Example: + + .. doctest:: + + >>> result = variance(x, weights=weightoptions, axis = axisoptions, centered=centeredoptions, biased = biasedoptions, max_pct_missing=max_pct_missingoptions) - Options: - weightoptions + :type weightoptions: + :param weightoptions: If you want to compute the weighted variance, provide weights here. - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n - default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. - centeredoptions None | 0 | 1 - default value = 1 removes the mean first. Set to 0 or None for - uncentered. - biasedoptions None | 0 | 1 - default value = 1 If want to compute an unbiased variance pass - anything but 1. - max_pct_missingoptions - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked + :type axis: + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + default value = 0. You can pass the name of the dimension or index + (integer value 0...n) over which you want to compute the statistic. + :type centered: + :param centered: None | 0 | 1 + default value = 1 removes the mean first. Set to 0 or None for + uncentered. + :type biased: + :param biased: None | 0 | 1 + default value = 1 If want to compute an unbiased variance pass + anything but 1. + :type max_pct_missing: + :param max_pct_missing: + default value = 100. Maximum fraction of cell which is allowed to be masked (missing). + Set to a percentage between 0 and 100%. + Set to 0. to mask results if any data is masked. + Set to 100. to calculate result if any data is not masked """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.variance") if cdms2.isVariable(x) : xatt=x.attributes @@ -764,32 +775,37 @@ def checker(x,weights=None,axis=0,centered=1): def std(x,weights=None,axis=0,centered=1,biased=1,max_pct_missing=100.): """ - Function: std - - Description of function: - Returns the standard deviation from a slab. By default on first - dimension, centered, and biased. - Usage: - result = std(x, weights=weightoptions, axis = axisoptions, + Returns the standard deviation from a slab. By default on first + dimension, centered, and biased. + + :Example: + + .. doctest:: + + >>> result = std(x, weights=weightoptions, axis = axisoptions, centered=centeredoptions, biased = biasedoptions, max_pct_missing=max_pct_missingoptions) - Options: - weightoptions + :type weightoptions: + :param weightoptions: If you want to compute the weighted statistic, provide weights here. - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n - default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. - centeredoptions None | 0 | 1 + :type axis: + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + default value = 0. You can pass the name of the dimension or index + (integer value 0...n) over which you want to compute the statistic. + :type centered: + :param centered: None | 0 | 1 default value = 1 removes the mean first. Set to 0 or None for uncentered. - biasedoptions None | 0 | 1 - default value = 1 If want to compute an unbiased variance pass - anything but 1. - max_pct_missingoptions - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked + :type biased: + :param biased: None | 0 | 1 + default value = 1 If want to compute an unbiased variance pass + anything but 1. + :type max_pct_missing: + :param max_pct_missing: + default value = 100. Maximum fraction of cell which is allowed to be masked (missing). + Set to a percentage between 0 and 100%. + Set to 0. to mask results if any data is masked. + Set to 100. to calculate result if any data is not masked """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.std") if cdms2.isVariable(x) : xatt=x.attributes @@ -804,33 +820,38 @@ def std(x,weights=None,axis=0,centered=1,biased=1,max_pct_missing=100.): def correlation(x,y,weights=None,axis=0,centered=1,biased=1,max_pct_missing=100.): """ - Function: correlation - - Description of function: - Returns the correlation between 2 slabs. By default on the first - dimension, centered and biased by default. - Usage: - result = correlation(x, y, weights=weightoptions, axis=axisoptions, + Returns the correlation between 2 slabs. By default on the first + dimension, centered and biased by default. + + :Example: + + .. doctest:: + + >>> result = correlation(x, y, weights=weightoptions, axis=axisoptions, centered=centeredoptions, biased=biasedoptions, max_pct_missing=max_pct_missingoptions) - Options: - weightoptions + :type weights: + :param weights: default = None. If you want to compute the weighted correlation, provide the weights here. - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n - default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. - centeredoptions None | 0 | 1 - default value = 1 removes the mean first. Set to 0 or None for - uncentered. - biasedoptions None | 0 | 1 - default value = 1 returns biased statistic. If want to compute an - unbiased statistic pass anything but 1. - max_pct_missingoptions - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked + :type axis: + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + default value = 0. You can pass the name of the dimension or index + (integer value 0...n) over which you want to compute the statistic. + :type centered: + :param centered: None | 0 | 1 + default value = 1 removes the mean first. Set to 0 or None for + uncentered. + :type biased: + :param biased: None | 0 | 1 + default value = 1 returns biased statistic. If want to compute an + unbiased statistic pass anything but 1. + :type max_pct_missing: + :param max_pct_missing: + default value = 100. Maximum fraction of cell which is allowed to be masked (missing). + Set to a percentage between 0 and 100%. + Set to 0. to mask results if any data is masked. + Set to 100. to calculate result if any data is not masked """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.corelation") x,y,weights,axis,ax=__checker(x,y,weights,axis) @@ -844,34 +865,39 @@ def correlation(x,y,weights=None,axis=0,centered=1,biased=1,max_pct_missing=100. def rms(x,y,weights=None,axis=0,centered=0,biased=1,max_pct_missing=100.): """ - Function: rms - - Description of function: - Returns the root mean square difference between 2 slabs. By default from - a slab (on first dimension) "uncentered" and "biased" by default. - Usage: - result = rms(x, y, weights=weightoptions, axis = axisoptions, + Returns the root mean square difference between 2 slabs. By default from + a slab (on first dimension) "uncentered" and "biased" by default. + + :Example: + + .. doctest:: + + >>> result = rms(x, y, weights=weightoptions, axis = axisoptions, centered=centeredoptions, biased = biasedoptions, max_pct_missing=max_pct_missingoptions) - Options: - weightoptions + :type weights: + :param weights: default = None returns equally weighted statistic. If you want to compute the weighted statistic, provide weights here. - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n - default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. - centeredoptions None | 0 | 1 - default value = 0 returns uncentered statistic (same as None). To - remove the mean first (i.e centered statistic) set to 1. NOTE: Most - other statistic functions return a centered statistic by default. - biasedoptions None | 0 | 1 - default value = 1 If want to compute an unbiased variance pass - anything but 1. - max_pct_missingoptions - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked + :type axis: + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + default value = 0. You can pass the name of the dimension or index + (integer value 0...n) over which you want to compute the statistic. + :type centered: + :param centered: None | 0 | 1 + default value = 0 returns uncentered statistic (same as None). To + remove the mean first (i.e centered statistic) set to 1. NOTE: Most + other statistic functions return a centered statistic by default. + :type biased: + :param biased: None | 0 | 1 + default value = 1 If want to compute an unbiased variance pass + anything but 1. + :type max_pct_missing: + :param max_pct_missing: + default value = 100. Maximum fraction of cell which is allowed to be masked (missing). + Set to a percentage between 0 and 100%. + Set to 0. to mask results if any data is masked. + Set to 100. to calculate result if any data is not masked """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.rms") if cdms2.isVariable(x) : xatt=x.attributes @@ -886,39 +912,45 @@ def rms(x,y,weights=None,axis=0,centered=0,biased=1,max_pct_missing=100.): def laggedcovariance(x,y,lag=None,axis=0,centered=1,partial=1,noloop=0,max_pct_missing=100.): """ - Function: laggedcovariance - - Description of function: - Returns the covariance between 2 slabs at lag k centered and partial by - default. - Usage: - result = laggedcovariance(x, y, lag=lagoptions, axis=axisoptions, - centered=centeredoptions, - partial=partialoptions, noloop=noloopoptions) + Returns the covariance between 2 slabs at lag k centered and partial by + default. + + :Example: + + .. doctest:: + + >>> result = laggedcovariance(x, y, lag=lagoptions, axis=axisoptions, + centered=centeredoptions, + partial=partialoptions, noloop=noloopoptions) Returns value for x lags y by lag (integer) - Options: - lagoptions None | n | (n1, n2, n3...) | [n1, n2, n3 ....] + :type lag: + :param lag: None | n | (n1, n2, n3...) | [n1, n2, n3 ....] default value = None the maximum possible lags for specified axis is used.You can pass an integer, list of integers, or tuple of integers. - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n - default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. - centeredoptions - default value = 1 removes the mean first. Set to 0 or None for - uncentered - partialoptions None | 0 | 1 - default value = 1 uses only common time for means. - noloopoptions None | 0 | 1 - default value = 0 computes statistic at all lags upto 'lag'. If you - set noloop=1 statistic is computed at lag only (not up to lag). - max_pct_missingoptions - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked + :type axis: + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + default value = 0. You can pass the name of the dimension or index + (integer value 0...n) over which you want to compute the statistic. + :type centered: + :param centered: + default value = 1 removes the mean first. Set to 0 or None for + uncentered + :type partial: + :param partial: None | 0 | 1 + default value = 1 uses only common time for means. + :type noloop: + :param noloop: None | 0 | 1 + default value = 0 computes statistic at all lags upto 'lag'. If you + set noloop=1 statistic is computed at lag only (not up to lag). + :type max_pct_missing: + :param max_pct_missing: + default value = 100. Maximum fraction of cell which is allowed to be masked (missing). + Set to a percentage between 0 and 100%. + Set to 0. to mask results if any data is masked. + Set to 100. to calculate result if any data is not masked """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.laggedcovariance") if cdms2.isVariable(x) : xatt=x.attributes @@ -958,42 +990,50 @@ def laggedcovariance(x,y,lag=None,axis=0,centered=1,partial=1,noloop=0,max_pct_m def laggedcorrelation(x,y,lag=None,axis=0,centered=1,partial=1,biased=1,noloop=0,max_pct_missing=100.): """ - Function: laggedcorrelation - - Description of function: - Returns the correlation between 2 slabs at lag k centered, partial and - "biased" by default. - Usage: - result = laggedcorrelation(x, y, lag=lagoptions, axis=axisoptions, + + Returns the correlation between 2 slabs at lag k centered, partial and + "biased" by default. + + :Example: + + .. doctest:: + + >>> result = laggedcorrelation(x, y, lag=lagoptions, axis=axisoptions, centered=centeredoptions, partial=partialoptions, biased=biasedoptions, noloop=noloopoptions) Returns value for x lags y by lag - Options: - lagoptions None | n | (n1, n2, n3...) | [n1, n2, n3 ....] + :type lag: + :param lag: None | n | (n1, n2, n3...) | [n1, n2, n3 ....] default value = None the maximum possible lags for specified axis is used.You can pass an integer, list of integers, or tuple of integers. - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n - default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. - centeredoptions - default value = 1 removes the mean first. Set to 0 or None for - uncentered - partialoptions None | 0 | 1 - default value = 1 uses only common time for means. - biasedoptions None | 0 | 1 - default value = 1 If want to compute an unbiased variance pass - anything but 1. - noloopoptions None | 0 | 1 - default value = 0 computes statistic at all lags upto 'lag'. If you - set noloop=1 statistic is computed at lag only (not up to lag). - max_pct_missingoptions - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked + :type axis: + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + default value = 0. You can pass the name of the dimension or index + (integer value 0...n) over which you want to compute the statistic. + :type centered: + :param centered: + default value = 1 removes the mean first. Set to 0 or None for + uncentered + :type partial: + :param partial: None | 0 | 1 + default value = 1 uses only common time for means. + :type biased: + :param biased: None | 0 | 1 + default value = 1 If want to compute an unbiased variance pass + anything but 1. + :type noloop: + :param noloop: None | 0 | 1 + default value = 0 computes statistic at all lags upto 'lag'. If you + set noloop=1 statistic is computed at lag only (not up to lag). + :type max_pct_missing: + :param max_pct_missing: + default value = 100. Maximum fraction of cell which is allowed to be masked (missing). + Set to a percentage between 0 and 100%. + Set to 0. to mask results if any data is masked. + Set to 100. to calculate result if any data is not masked """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.laggedcorrelation") x,y,w,axis,ax=__checker(x,y,None,axis) @@ -1032,34 +1072,40 @@ def laggedcorrelation(x,y,lag=None,axis=0,centered=1,partial=1,biased=1,noloop=0 def autocovariance(x,lag=None,axis=0,centered=1,partial=1,noloop=0,max_pct_missing=100.): """ - Function: autocovariance - - Description of function: - Returns the autocovariance of a slab. By default over the first dimension, centered, and partial. - Usage: - result = autocovariance(x, lag=lagoptions, axis=axisoptions, + Returns the autocovariance of a slab. By default over the first dimension, centered, and partial. + + :Example: + + .. doctest:: + + >>> result = autocovariance(x, lag=lagoptions, axis=axisoptions, centered=centeredoptions, partial=partialoptions, noloop=noloopoptions) - Options: - lagoptions None | n | (n1, n2, n3...) | [n1, n2, n3 ....] + :type lag: + :param lag: None | n | (n1, n2, n3...) | [n1, n2, n3 ....] default value = None the maximum possible lags for specified axis is used.You can pass an integer, list of integers, or tuple of integers. - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n - default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. - centeredoptions None | 0 | 1 - default value = 1 removes the mean first. Set to 0 or None for - uncentered statistic. - partialoptions None | 0 | 1 - default value = 1 uses only common time for means. - noloopoptions None | 0 | 1 - default value = 0 computes statistic at all lags upto 'lag'. If you - set noloop=1 statistic is computed at lag only (not up to lag). - max_pct_missingoptions - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked + :type axis: + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + default value = 0. You can pass the name of the dimension or index + (integer value 0...n) over which you want to compute the statistic. + :type centered: + :param centered: None | 0 | 1 + default value = 1 removes the mean first. Set to 0 or None for + uncentered statistic. + :type partial: + :param partial: None | 0 | 1 + default value = 1 uses only common time for means. + :type noloop: + :param noloop: None | 0 | 1 + default value = 0 computes statistic at all lags upto 'lag'. If you + set noloop=1 statistic is computed at lag only (not up to lag). + :type max_pct_missing: + :param max_pct_missing: + default value = 100. Maximum fraction of cell which is allowed to be masked (missing). + Set to a percentage between 0 and 100%. + Set to 0. to mask results if any data is masked. + Set to 100. to calculate result if any data is not masked """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.autocovariance") if cdms2.isVariable(x) : xatt=x.attributes @@ -1096,39 +1142,45 @@ def autocovariance(x,lag=None,axis=0,centered=1,partial=1,noloop=0,max_pct_missi def autocorrelation(x,lag=None,axis=0,centered=1,partial=1,biased=1,noloop=0,max_pct_missing=100.): """ - Function: autocorrelation - - Description of function: - Returns the autocorrelation of a slab at lag k centered,partial and - "biased" by default + Returns the autocorrelation of a slab at lag k centered,partial and + "biased" by default - Usage: - result = autocorrelation(x, lag=lagoptions, axis=axisoptions, + :Example: + + .. doctest:: + + >>> result = autocorrelation(x, lag=lagoptions, axis=axisoptions, centered=centeredoptions, partial=partialoptions, biased=biasedoptions, noloop=noloopoptions) - Options: - lagoptions None | n | (n1, n2, n3...) | [n1, n2, n3 ....] + :type lag: + :param lag: None | n | (n1, n2, n3...) | [n1, n2, n3 ....] default value = None the maximum possible lags for specified axis is used.You can pass an integer, list of integers, or tuple of integers. - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n - default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. - centeredoptions None | 0 | 1 - default value = 1 removes the mean first. Set to 0 or None for - uncentered statistic. - partialoptions None | 0 | 1 - default value = 1 uses only common time for means. - biasedoptions None | 0 | 1 - default value = 1 computes the biased statistic. If want to compute - an unbiased statistic pass anything but 1. - noloopoptions None | 0 | 1 - default value = 0 computes statistic at all lags upto 'lag'. If you - set noloop=1 statistic is computed at lag only (not up to lag). - max_pct_missingoptions - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked + :type axis: + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + default value = 0. You can pass the name of the dimension or index + (integer value 0...n) over which you want to compute the statistic. + :type centered: + :param centered: None | 0 | 1 + default value = 1 removes the mean first. Set to 0 or None for + uncentered statistic. + :type partial: + :param partial: None | 0 | 1 + default value = 1 uses only common time for means. + :type biased: + :param biased: None | 0 | 1 + default value = 1 computes the biased statistic. If want to compute + an unbiased statistic pass anything but 1. + :type noloop: + :param noloop: None | 0 | 1 + default value = 0 computes statistic at all lags upto 'lag'. If you + set noloop=1 statistic is computed at lag only (not up to lag). + :type max_pct_missing: + :param max_pct_missing: + default value = 100. Maximum fraction of cell which is allowed to be masked (missing). + Set to a percentage between 0 and 100%. + Set to 0. to mask results if any data is masked. + Set to 100. to calculate result if any data is not masked """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.autocorrelation") x,dum,dum,axis,ax=__checker(x,None,None,axis) @@ -1165,28 +1217,32 @@ def autocorrelation(x,lag=None,axis=0,centered=1,partial=1,biased=1,noloop=0,max def meanabsdiff(x,y,weights=None,axis=0,centered=1,max_pct_missing=100.): """ - Function: meanabsdiff - - Description of function: - Returns the mean absolute difference between 2 slabs x and y. By default - on the first dimension and centered - Usage: - result = meanabsdiff(x, y, weights=weightoptions, axis = axisoptions, + Returns the mean absolute difference between 2 slabs x and y. By default + on the first dimension and centered + + :Example: + + .. doctest:: + + >>> result = meanabsdiff(x, y, weights=weightoptions, axis = axisoptions, centered=centeredoptions) - Options: - weightoptions + :type weights: + :param weights: default = None returns equally weighted statistic. If you want to compute the weighted statistic, provide weights here. - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n - default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. - centeredoptions None | 0 | 1 - default value = 1 removes the mean first. Set to 0 or None for uncentered. - max_pct_missingoptions - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked + :type axis: + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + default value = 0. You can pass the name of the dimension or index + (integer value 0...n) over which you want to compute the statistic. + :type centered: + :param centered: None | 0 | 1 + default value = 1 removes the mean first. Set to 0 or None for uncentered. + :type max_pct_missing: + :param max_pct_missing: + default value = 100. Maximum fraction of cell which is allowed to be masked (missing). + Set to a percentage between 0 and 100%. + Set to 0. to mask results if any data is masked. + Set to 100. to calculate result if any data is not masked """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.meanabsdiff") if cdms2.isVariable(x) : xatt=x.attributes @@ -1210,40 +1266,47 @@ def linearregression(y,axis=None,x=None,error=None,probability=None,nointercept= details, refer to 'Statistical Methods in Atmospheric Sciences' by Daniel S. Wilks, Academic Press, 1995. - Usage: - result = linearregression(y, axis=axisoptions, x=xoptions, \ + :Example: + + .. doctest:: + + >>> result = linearregression(y, axis=axisoptions, x=xoptions, \ error=erroroptions, probability=probabilityoptions, \ nointercept=nointerceptoptions, noslope=noslopeoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :type axis: + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to treat the array as the dependent variable. - xvalues - default = None. You can pass an array of values that are to be used - as the independent axis x - nointerceptoptions None | 0 | 1 - default = None. Setting to 0 or None means intercept calculations - are returned. To turn OFF the intercept computations set - nointercept = 1. - noslopeoptions None | 0 | 1 - default = None. Setting to None or 0 means slope calculations are - returned. To turn OFF the slope computations set noslope to 1. - erroroptions None | 0 | 1 | 2 | 3 - default = None. If set to 0 or None, no associated errors are - returned. - If set to 1, the unadjusted standard error is returned. - If set to 2, standard error returned. This standard error is - adjusted using the centered autocorrelation of the residual. - If set to 3, standard error returned. The standard error here is - adjusted using the centered autocorrelation of the raw data (y). - probabilityoptions None | 0 | 1 - default = None. If set to 0 or None, no associated probabilities are - returned. Set this to 1to compute probabilities. - Note: Probabilities are returned only if erroroptions are set to one - of 1, 2, or 3. If it is set to None or 0, then setting - probabilityoptions has no meaning. + :type nointercept: + :param nointercept: None | 0 | 1 + default = None. Setting to 0 or None means intercept calculations + are returned. To turn OFF the intercept computations set + nointercept = 1. + :type noslope: + :param noslope: None | 0 | 1 + default = None. Setting to None or 0 means slope calculations are + returned. To turn OFF the slope computations set noslope to 1. + :type error: + :param error: None | 0 | 1 | 2 | 3 + default = None. If set to 0 or None, no associated errors are + returned. + If set to 1, the unadjusted standard error is returned. + If set to 2, standard error returned. This standard error is + adjusted using the centered autocorrelation of the residual. + If set to 3, standard error returned. The standard error here is + adjusted using the centered autocorrelation of the raw data (y). + :type probability: + :param probability: None | 0 | 1 + default = None. If set to 0 or None, no associated probabilities are + returned. Set this to 1to compute probabilities. + + .. note:: + + Probabilities are returned only if erroroptions are set to one + of 1, 2, or 3. If it is set to None or 0, then setting + probabilityoptions has no meaning. What is returned? The returned values depend on the combination of options you select. If @@ -1459,18 +1522,21 @@ def linearregression(y,axis=None,x=None,error=None,probability=None,nointercept= def geometricmean(x,axis=0,max_pct_missing=100.): """ - Function: geometricmean - - Description of function: - Returns the geometric mean over a specified axis. + Returns the geometric mean over a specified axis. - Usage: - result = geometricmean(x, axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :Example: + + .. doctest:: + + >>> result = geometricmean(x, axis=axisoptions) + + :type axis: + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - max_pct_missingoptions + + :type max_pct_missing: + :param max_pct_missing: default value = 100. Maximum fraction of cell which is allowed to be masked (missing). Set to a percentage between 0 and 100%. Set to 0. to mask results if any data is masked. @@ -1537,20 +1603,21 @@ def _percentiles(out,percent): def percentiles(x,percentiles=[50.],axis=0): """ - Function: percentiles - - Description of function: - Returns values at the defined percentiles for an array. + Returns values at the defined percentiles for an array. - Usage: - result = percentiles(x, percentiles=percentilesoptions, axis=axisoptions) + :Example: - Options: - percentilesoptions A python list of values - Default = [50.] (the 50th percentile i.e the median value) - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + .. doctest:: + + >>> result = percentiles(x, percentiles=percentilesoptions, axis=axisoptions) + + :type percentilesoptions: + :param percentilesoptions: A python list of values + Default = [50.] (the 50th percentile i.e the median value) + :type axis: + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. + (integer value 0...n) over which you want to compute the statistic. """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.percentiles") if cdms2.isVariable(x) : xatt=x.attributes @@ -1568,16 +1635,17 @@ def percentiles(x,percentiles=[50.],axis=0): def median(x,axis=0): """ - Function: median - - Description of function: - Returns the median value of an array. + Returns the median value of an array. - Usage: - result = median(x, axis=axisoptions) + :Example: + + .. doctest:: + + >>> result = median(x, axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :type axisoptions: + :type axisoptions: + :param axisoptions: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. """ @@ -1589,17 +1657,18 @@ def median(x,axis=0): def rank(x,axis=0): """ - Function: rank - - Description of function: - Returns the rank of each element along the specified axis - where 0 is lowest value, 100 is maximum value. Handles missing values correctly + Returns the rank of each element along the specified axis + where 0 is lowest value, 100 is maximum value. Handles missing values correctly - Usage: - result = median(x, axis=axisoptions) + :Example: + + .. doctest:: + + >>> result = median(x, axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :type axis: + :type axis: + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. """ diff --git a/Lib/statusbar.py b/Lib/statusbar.py index 529faa2..fcea9b0 100644 --- a/Lib/statusbar.py +++ b/Lib/statusbar.py @@ -1,5 +1,5 @@ def statusbar(status,total=1.,prev=-1,title='Done',tk=None): - ''' + """ # Create the illusion of a progressing bar # Date: August 1st, 2000 # Author: Charles Doutriaux @@ -37,7 +37,7 @@ def statusbar(status,total=1.,prev=-1,title='Done',tk=None): prevtxt=statusbar(float(j)/nj,prev=prevtxt,tk=None,title='Test') - ''' + """ import sys,string chardic={ 0:'|', From 7367407d0500a66ad4dccd6f17acd964f115fdb2 Mon Sep 17 00:00:00 2001 From: embrown Date: Wed, 16 Nov 2016 10:15:27 -0800 Subject: [PATCH 3/5] Working on docstring formatting --- Lib/ASCII.py | 16 ++++- Lib/Filler.py | 111 +++++++++++++++++++---------- Lib/arrayindexing.py | 35 ++++++++-- Lib/averager.py | 25 +++---- Lib/colors.py | 9 ++- Lib/filters.py | 18 +++-- Lib/grower.py | 22 ++++-- Lib/statistics.py | 163 ++++++++++++++++++++++--------------------- 8 files changed, 249 insertions(+), 150 deletions(-) diff --git a/Lib/ASCII.py b/Lib/ASCII.py index 42b53a3..2aa8ddd 100644 --- a/Lib/ASCII.py +++ b/Lib/ASCII.py @@ -33,14 +33,19 @@ def readAscii( text_file ,header=0, ids=None, shape=None, next='------',separato :param text_file: A string, containing the path to an ASCII File to read from. :type text_file: str + :param header: Number of header lines, these lines will be skipped. :type header: int + :param ids: List of values to use as variable ids (1 per variable returned) :type ids: list + :param shape: use the tuple/list in this list as the final shape of the variable read. :type shape: tuple or list + :param next: character string marking separation between variables (i.e. '------') :type next: str + :param separators: List of characters recognized as column separators (i.e. [';',',',':']) :type separators: list @@ -104,24 +109,31 @@ def read_col( text_file ,header=0, cskip=0, cskip_type='columns', axis=False, id :param text_file: ASCII File to read from. :type text_file: + :param header: (0) Number of header lines, these lines will be skipped. :type header: + :param cskip: (0) Number of 'column'/'character' to skip (dummy column) :type cskip: + :param cskip_type: ('column') is 'cskip' a number of 'column' or 'character' to skip? :type cskip_type: + :param axis: (False) Use as the values for the first column as variable axis (x values in y(x)) :type axis: + :param idrow: (False) Is the first row representing the ids of var generated ? :type idrow: + :param ids: (None) use the values in this list as variable ids (1 per column returned) :type ids: + :param separators: ([';',',', ':']) List of character recognized as column separator :type separators: - :returns: List containing 1 transient varialbe per column in the files. + :returns: List containing 1 transient variable per column in the files. Variable ids are optionaly determined by first row. - Variable axis may be the first column + Variable axis may be the first column. :rtype: list """ diff --git a/Lib/Filler.py b/Lib/Filler.py index 87fc644..b21c930 100644 --- a/Lib/Filler.py +++ b/Lib/Filler.py @@ -3,34 +3,36 @@ class StringConstructor: """ This class aims at spotting keywords in a string and replacing them - Usage - Filler=StringConstructor(template) - or - Filler=StringConstructor() - Filler.template=template + :Usage: - template is a string of form: 'my string here with %(keywords) in it' + .. code-block:: python - You can have has many 'keyword' as you want, and use them as many times as you want - keywords are delimited on the left by %( and ) on the right - - In order to construct the string (i.e. replace keywords with some values: + >>> template = "templates are strings containing any number of %(keywords) using %(this_format)" + >>> Filler=StringConstructor(template) + # or + >>> Filler=StringConstructor() + >>> Filler.template=template + # In order to construct the string (i.e. replace keywords with some values): + >>> str=Filler(keywords='keywdstr',this_format='') + # or + >>> Filler.keyword='kwstr' + >>> Filler.this_format='' + >>> str=Filler() - str=Filler(keyword='kwstr') - or - Filler.keyword='kwstr' - str=Filler() - Example: - structure='/pcmdi/amip/mo/%(variable)/%(model)/%(variable)_%(model).xml' - Filler=StringConstructor(structure) - Filler.variable='tas' - myfilename=Filler.construct(structure,model='ugamp-98a') - print myfilename # '/pcmdi/amip/mo/tas/ugamp-98a/tas_ugamp-98a.xml' - + template is a string of form: 'my string here with %(keywords) in it' + + You can have has many keywords as you want, and use them as many times as you want. + Keywords are delimited on the left by %( and on the right by ). """ def __init__(self,template=None): + """ + Instantiates a StringConstructor object. + :param template: A string used by StringConstructor for keyword replacement. + template is a string of form: 'my string here with %(keywords) in it'. + There can be an unlimited number of keywords, delimited by %( on the left and ) on the right. + """ cdat_info.pingPCMDIdb("cdat","genutil.StringConstructor") self.template=template ## ok we need to generate the keys and set them to empty it seems like a better idea @@ -60,16 +62,29 @@ def keys(self,template=None): def construct(self,template=None,**kw): """ - Accepts a string with a unlimited number of keyword to replace - keyword to replace must be in the format %(keyword) within the string - keyword value are either passed as keyword to the construct function or preset - Example: - structure='/pcmdi/amip/mo/%(variable)/%(model)/%(variable)_%(model).xml' - Filler=StringConstructor() - Filler.variable='tas' - myfilename=Filler.construct(structure,model='ugamp-98a') - - print myfilename + Accepts a string with an unlimited number of keywords to replace. + Keywords to replace must be in the format %(keyword) within the string. + Keyword values are either passed as keyword to the construct function or preset. + + :Example: + + .. doctest:: Filler_construct + + >>> structure='/pcmdi/amip/mo/%(variable)/%(model)/%(variable)_%(model).xml' + >>> Filler=StringConstructor() + >>> Filler.variable='tas' + >>> myfilename=Filler.construct(structure,model='ugamp-98a') + >>> print myfilename + '/pcmdi/amip/mo/tas/ugamp-98a/tas_ugamp-98a.xml' + + :param template: A string used by StringConstructor for keyword replacement. + template is a string of form: 'my string here with %(keywords) in it'. + There can be an unlimited number of keywords, delimited by %( on the left and ) on the right. + :type template: str + + :param kw: Comma-delimited list of keyword to string value mappings, i.e.: + keyword1='kwd1 string',keyword2='kwd2 string', ... + :type kw: list """ if template is None: template=self.template @@ -83,6 +98,31 @@ def construct(self,template=None,**kw): return template def reverse(self,name,debug=False): + """ + The reverse function attempts to take a template and derive its keyword values based on name parameter. + + :Example: + + .. doctest:: Filler_reverse + + >>> Filler=StringConstructor(template="%(a).%(b)") + >>> Filler.reverse("A.B") + {a:"A", b:"B"} + + :param name: String to test the template's keyword values. + :type name: str + + :param debug: Boolean flag to indicate whether or not to print debug output. + :type debug: bool + + :returns: A dictionary mapping the StringConstructor's template's keywords to the corresponding values, + according to the format of the name parameter. + :rtype: dict + + .. warning:: + + reverse makes its best effort at deriving keyword values from a string, but it is not guaranteed to work. + """ out={} template = self.template for k in self.keys(): @@ -122,11 +162,6 @@ def reverse(self,name,debug=False): def __call__(self,*args,**kw): """default call is construct function""" return self.construct(*args,**kw) - -Filler=StringConstructor() -if __name__=='__main__': - Filler.variable='tas' - structure='/pcmdi/amip/mo/%(variable)/%(model)/%(variable)_%(model).xml' - myfilename=Filler.construct(structure,model='*') - print myfilename + +Filler=StringConstructor() diff --git a/Lib/arrayindexing.py b/Lib/arrayindexing.py index 03c83e8..fe7fb57 100644 --- a/Lib/arrayindexing.py +++ b/Lib/arrayindexing.py @@ -6,10 +6,24 @@ def get(Array,Indices,axis=0): """ Arrayrrayindexing returns Array[Indices], indices are taken along dimension given with axis - - Usage: - C=get(Array,Indices,axis=0) # i.e. C=Array[Indices] - Indices accepts negative value ,e.g: -1 is last element + + :Example: + + .. doctest:: arrayindexing_get + + >>> import numpy as np + >>> Array=np.array([2,3,1,0,1,2,3]) + >>> Indices=[0,-1, len(Array)-2] # get the first, last, and second-to-last indices of the array + >>> C=get(Array,Indices,axis=0) # i.e. C=Array[Indices] + + :param Array: A cdms2 variable, or numpy array, to access the indices of + :type Array: cdms.tvariable.TransientVariable or numpy.array + + :param Indices: List of integers specifying the indices of Array to access and return + :type Indices: list + + :param axis: Axis of a cdms variable + :type axis: int or str """ ## First some checks @@ -28,11 +42,11 @@ def get(Array,Indices,axis=0): if isinstance(Indices,int): return Array[Indices] if Indices.shape!=Array.shape[1:]: - raise "Error uncompatible shapes: "+str(Array.shape)+" and "+str(Indices.shape) + raise "Error incompatible shapes: "+str(Array.shape)+" and "+str(Indices.shape) else: Array,Indices,weights,axis,ax=statistics.__checker(Array,Indices,None,axis) if Indices.shape!=Array.shape: - raise "Error uncompatible shapes: "+str(Array.shape)+" and "+str(Indices.shape) + raise "Error incompatible shapes: "+str(Array.shape)+" and "+str(Indices.shape) m=Array.mask if not isinstance(Indices,int): Indices=Indices.data.astype('i') # Sometihng happened with masking of y by x mask @@ -57,6 +71,15 @@ def set(Array,Indices,Values,axis=0): Array=set(Array,Indices,Values,axis=0) # i.e. Array[Indices]=Values Indices accepts negative value ,e.g: -1 is last element + + :param Array: A cdms2 variable, or numpy array, to set the indices of + :type Array: cdms.tvariable.TransientVariable or numpy.array + + :param Indices: List of integers specifying the indices of Array to access and set + :type Indices: list + + :param axis: Axis of a cdms variable + :type axis: int or str """ ## if numpy.rank(Indices)==0: ## Array[Indices]=Values diff --git a/Lib/averager.py b/Lib/averager.py index 2659ee1..cbc60d8 100644 --- a/Lib/averager.py +++ b/Lib/averager.py @@ -5,10 +5,10 @@ class AveragerError (Exception): def __init__ (self, args=None): - "Create an exception" + """Create an exception""" self.args = args def __str__(self): - "Calculate the string representation" + """Calculate the string representation""" return str(self.args) __repr__ = __str__ @@ -723,18 +723,18 @@ def averager(V, axis=None, weights=None, action='average', returned=0, weight=No :returns: The average over the specified dimensions. - Usage: - ------ + :Usage: .. code-block:: python from cdutil import averager - averager( V, axis='axisoptions', weights=weightoptions, action='average', + averager(V, axis='axisoptions', weights=weightoptions, action='average', returned='0') - Where V is an array. It can be an array of numpy, numpy.ma or MV2 type. In each case - the function returns an array (except when it results in a scalar) of the same - type as V. See examples for more details. + + + :param V: an array of numpy, numpy.ma or MV2 type + :type V: numpy.array or numpy.ma or MV2 :param axis: String specifying axisoptions. Default: first dimension in the data you pass to the function. @@ -744,15 +744,17 @@ def averager(V, axis=None, weights=None, action='average', returned=0, weight=No numpy.ma array, axis names have no meaning and only axis indexes are valid. :type axis: string - :param weights: String specifying weight options, or a + :param weights: String specifying weight options Default: 'weighted' for Transient Variables (MV2s) 'unweighted' for numpy.ma or numpy arrays. - Note that depending on the array being operated on by averager, the - default weights change! + .. note:: + + Depending on the array being operated on by averager, the + default weights change! Weight options are one of 'weighted', 'unweighted', an array of weights for each dimension or a MaskedVariable of the same shape as the data x. @@ -775,7 +777,6 @@ def averager(V, axis=None, weights=None, action='average', returned=0, weight=No those values are used. Otherwise, bounds are generated as long as cdms2.setAutoBounds('on') is set. If cdms2.setAutoBounds() is set to 'off', then an Error is raised. - :type weights: str :param action: One of 'average' or 'sum'. Specifies whether to return the weighted average or weighted sum of data. diff --git a/Lib/colors.py b/Lib/colors.py index 4c504b7..0234fb5 100644 --- a/Lib/colors.py +++ b/Lib/colors.py @@ -665,11 +665,16 @@ def str2rgb(col): .. doctest:: genutil_colors_str2rgb - >>> r, g, b = str2rgb('pink2') # returns: (238 , 169 , 184 ) - >>> r, g, b = str2rgb('cray') # returns: (None, None, None) + >>> str2rgb('pink2') + 238, 169, 184 + >>> str2rgb('cray') + None, None, None :param col: String name of a color. :type col: str + + :returns: A three-tuple with red, green, and blue values of the specified color, or None, None, None if the color + does not exist. """ import string ret=[] diff --git a/Lib/filters.py b/Lib/filters.py index 5af26cb..5c8175d 100644 --- a/Lib/filters.py +++ b/Lib/filters.py @@ -10,10 +10,10 @@ def custom1D(x,filter,axis=0): filter can be a list of numbers or a 1D array :param x: A CDMS TransientVariable - :type x: + :type x: cdms.tvariable.TransientVariable - :param filter: - :type filter: + :param filter: numpy or MV array + :type filter: array :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index @@ -80,11 +80,16 @@ def smooth121(x,axis=0): .. doctest:: genutil_filters_smooth121 - >>> filtered = smooth121(unfiltered) + >>> import cdms2, vcs + >>> vcs.download_sample_data() + >>> f=cdms2.open(vcs.sample_data + 'clt.nc') + >>> unfiltered=f('clt') + >>> filtered = smooth121(unfiltered) # filter over axis at index 0 :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. + :type axis: str or int """ cdat_info.pingPCMDIdb("cdat","genutil.filters.smooth121") return custom1D(x,[1.,2.,1.],axis=axis) @@ -98,6 +103,10 @@ def runningaverage(x,N,axis=0): .. doctest:: genutil_filters_runningaverage + >>> import cdms2, vcs + >>> vcs.download_sample_data() + >>> f=cdms2.open(vcs.sample_data + 'clt.nc') + >>> x=f('clt') >>> smooth = runningaverage(x,12) :param x: @@ -109,6 +118,7 @@ def runningaverage(x,N,axis=0): :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. + :type axis: str or int """ filter=numpy.ma.ones((N,),dtype='f') cdat_info.pingPCMDIdb("cdat","genutil.filters.runningaverage(%i)" % N) diff --git a/Lib/grower.py b/Lib/grower.py index 51cf055..93c0495 100644 --- a/Lib/grower.py +++ b/Lib/grower.py @@ -7,21 +7,33 @@ def grower(x, y, singleton=0): """ This function takes 2 transient variables and grows them to match their axes. + The final order will be the order of the first variables + followed by all/any dimension(s) from the second variable not present in the first variable. :Example: .. doctest:: genutil_grower + + >>> import cdms2, vcs + >>> vcs.download_sample_data_files() + >>> f=cdms2.open(vcs.sampledata + '/clt.nc') + >>> x=f('clt') + >>> y=f('v') >>> x, y = grower(x, y, singleton=1) - :param x: - :type x: + :param x: First transient variable to grow + :type x: cdms.tvariable.TransientVariable - :param y: - :type y: + :param y: Second transient variable to grow + :type y: cdms.tvariable.Transientvariable - :param singletonoption: Integer flag to indicate whether to raise an error if either dimension is not a singleton. + :param singleton: Integer flag to indicate whether to raise an error if either dimension is not a singleton. Default = 0 If singletonoption is set to 1 then an error is raised if one of the dims is not a singleton dimension. + :type singleton: int + + :returns: x and y, adjusted such that their axes match. + :rtype: cdms.tvariable.TransientVariable """ # Parse the x axes xorder=x.getOrder(ids=1) diff --git a/Lib/statistics.py b/Lib/statistics.py index fb31912..916ef7f 100644 --- a/Lib/statistics.py +++ b/Lib/statistics.py @@ -685,29 +685,28 @@ def covariance(x,y,weights=None,axis=0,centered=1,biased=1,max_pct_missing=100.) >>> cov = covariance(x, y, weights=weightoptions, axis=axisoptions, centered=centeredoptions, biased=biasedoptions, max_pct_missing=max_pct_missingoptions) - :param weightoptions: + :param weights: default = None. If you want to compute the weighted covariance, provide the weights here. - :type weightoptions: - - :type axis: + :type weights: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type centered: + :type axis: :param centered: None | 0 | 1 default value = 1 removes the mean first. Set to 0 or None for uncentered. - :type biased: + :type centered: :param biased: None | 0 | 1 default value = 1 If want to compute an unbiased variance pass anything but 1. - :type max_pct_missing: + :type biased: :param max_pct_missing: default value = 100. Maximum fraction of cell which is allowed to be masked (missing). Set to a percentage between 0 and 100%. Set to 0. to mask results if any data is masked. Set to 100. to calculate result if any data is not masked + :type max_pct_missing: """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.covariance") if cdms2.isVariable(x) : xatt=x.attributes @@ -734,27 +733,27 @@ def variance(x,weights=None,axis=0,centered=1,biased=1,max_pct_missing=100.): >>> result = variance(x, weights=weightoptions, axis = axisoptions, centered=centeredoptions, biased = biasedoptions, max_pct_missing=max_pct_missingoptions) - :type weightoptions: :param weightoptions: If you want to compute the weighted variance, provide weights here. - :type axis: + :type weightoptions: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type centered: + :type axis: :param centered: None | 0 | 1 default value = 1 removes the mean first. Set to 0 or None for uncentered. - :type biased: + :type centered: :param biased: None | 0 | 1 default value = 1 If want to compute an unbiased variance pass anything but 1. - :type max_pct_missing: + :type biased: :param max_pct_missing: default value = 100. Maximum fraction of cell which is allowed to be masked (missing). Set to a percentage between 0 and 100%. Set to 0. to mask results if any data is masked. Set to 100. to calculate result if any data is not masked + :type max_pct_missing: """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.variance") if cdms2.isVariable(x) : xatt=x.attributes @@ -785,27 +784,27 @@ def std(x,weights=None,axis=0,centered=1,biased=1,max_pct_missing=100.): >>> result = std(x, weights=weightoptions, axis = axisoptions, centered=centeredoptions, biased = biasedoptions, max_pct_missing=max_pct_missingoptions) - :type weightoptions: :param weightoptions: If you want to compute the weighted statistic, provide weights here. - :type axis: + :type weightoptions: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type centered: + :type axis: :param centered: None | 0 | 1 default value = 1 removes the mean first. Set to 0 or None for uncentered. - :type biased: + :type centered: :param biased: None | 0 | 1 + :type biased: default value = 1 If want to compute an unbiased variance pass anything but 1. - :type max_pct_missing: :param max_pct_missing: default value = 100. Maximum fraction of cell which is allowed to be masked (missing). Set to a percentage between 0 and 100%. Set to 0. to mask results if any data is masked. Set to 100. to calculate result if any data is not masked + :type max_pct_missing: """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.std") if cdms2.isVariable(x) : xatt=x.attributes @@ -830,28 +829,28 @@ def correlation(x,y,weights=None,axis=0,centered=1,biased=1,max_pct_missing=100. >>> result = correlation(x, y, weights=weightoptions, axis=axisoptions, centered=centeredoptions, biased=biasedoptions, max_pct_missing=max_pct_missingoptions) - :type weights: :param weights: default = None. If you want to compute the weighted correlation, provide the weights here. - :type axis: + :type weights: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type centered: + :type axis: :param centered: None | 0 | 1 default value = 1 removes the mean first. Set to 0 or None for uncentered. - :type biased: + :type centered: :param biased: None | 0 | 1 default value = 1 returns biased statistic. If want to compute an unbiased statistic pass anything but 1. - :type max_pct_missing: + :type biased: :param max_pct_missing: default value = 100. Maximum fraction of cell which is allowed to be masked (missing). Set to a percentage between 0 and 100%. Set to 0. to mask results if any data is masked. Set to 100. to calculate result if any data is not masked + :type max_pct_missing: """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.corelation") x,y,weights,axis,ax=__checker(x,y,weights,axis) @@ -875,29 +874,29 @@ def rms(x,y,weights=None,axis=0,centered=0,biased=1,max_pct_missing=100.): >>> result = rms(x, y, weights=weightoptions, axis = axisoptions, centered=centeredoptions, biased = biasedoptions, max_pct_missing=max_pct_missingoptions) - :type weights: :param weights: default = None returns equally weighted statistic. If you want to compute the weighted statistic, provide weights here. - :type axis: + :type weights: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type centered: + :type axis: :param centered: None | 0 | 1 default value = 0 returns uncentered statistic (same as None). To remove the mean first (i.e centered statistic) set to 1. NOTE: Most other statistic functions return a centered statistic by default. - :type biased: + :type centered: :param biased: None | 0 | 1 default value = 1 If want to compute an unbiased variance pass anything but 1. - :type max_pct_missing: + :type biased: :param max_pct_missing: default value = 100. Maximum fraction of cell which is allowed to be masked (missing). Set to a percentage between 0 and 100%. Set to 0. to mask results if any data is masked. Set to 100. to calculate result if any data is not masked + :type max_pct_missing: """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.rms") if cdms2.isVariable(x) : xatt=x.attributes @@ -925,32 +924,32 @@ def laggedcovariance(x,y,lag=None,axis=0,centered=1,partial=1,noloop=0,max_pct_m Returns value for x lags y by lag (integer) - :type lag: :param lag: None | n | (n1, n2, n3...) | [n1, n2, n3 ....] default value = None the maximum possible lags for specified axis is used.You can pass an integer, list of integers, or tuple of - integers. - :type axis: + integers. + :type lag: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type centered: + :type axis: :param centered: default value = 1 removes the mean first. Set to 0 or None for uncentered - :type partial: + :type centered: :param partial: None | 0 | 1 default value = 1 uses only common time for means. - :type noloop: + :type partial: :param noloop: None | 0 | 1 default value = 0 computes statistic at all lags upto 'lag'. If you set noloop=1 statistic is computed at lag only (not up to lag). - :type max_pct_missing: + :type noloop: :param max_pct_missing: default value = 100. Maximum fraction of cell which is allowed to be masked (missing). Set to a percentage between 0 and 100%. Set to 0. to mask results if any data is masked. Set to 100. to calculate result if any data is not masked + :type max_pct_missing: """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.laggedcovariance") if cdms2.isVariable(x) : xatt=x.attributes @@ -1005,35 +1004,35 @@ def laggedcorrelation(x,y,lag=None,axis=0,centered=1,partial=1,biased=1,noloop=0 Returns value for x lags y by lag - :type lag: :param lag: None | n | (n1, n2, n3...) | [n1, n2, n3 ....] default value = None the maximum possible lags for specified axis - is used.You can pass an integer, list of integers, or tuple of integers. - :type axis: + is used.You can pass an integer, list of integers, or tuple of integers. + :type lag: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type centered: + :type axis: :param centered: default value = 1 removes the mean first. Set to 0 or None for uncentered - :type partial: + :type centered: :param partial: None | 0 | 1 default value = 1 uses only common time for means. - :type biased: + :type partial: :param biased: None | 0 | 1 default value = 1 If want to compute an unbiased variance pass anything but 1. - :type noloop: + :type biased: :param noloop: None | 0 | 1 default value = 0 computes statistic at all lags upto 'lag'. If you set noloop=1 statistic is computed at lag only (not up to lag). - :type max_pct_missing: + :type noloop: :param max_pct_missing: default value = 100. Maximum fraction of cell which is allowed to be masked (missing). Set to a percentage between 0 and 100%. Set to 0. to mask results if any data is masked. Set to 100. to calculate result if any data is not masked + :type max_pct_missing: """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.laggedcorrelation") x,y,w,axis,ax=__checker(x,y,None,axis) @@ -1081,31 +1080,31 @@ def autocovariance(x,lag=None,axis=0,centered=1,partial=1,noloop=0,max_pct_missi >>> result = autocovariance(x, lag=lagoptions, axis=axisoptions, centered=centeredoptions, partial=partialoptions, noloop=noloopoptions) - :type lag: :param lag: None | n | (n1, n2, n3...) | [n1, n2, n3 ....] default value = None the maximum possible lags for specified axis - is used.You can pass an integer, list of integers, or tuple of integers. - :type axis: + is used.You can pass an integer, list of integers, or tuple of integers. + :type lag: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type centered: + :type axis: :param centered: None | 0 | 1 default value = 1 removes the mean first. Set to 0 or None for uncentered statistic. - :type partial: + :type centered: :param partial: None | 0 | 1 default value = 1 uses only common time for means. - :type noloop: + :type partial: :param noloop: None | 0 | 1 default value = 0 computes statistic at all lags upto 'lag'. If you set noloop=1 statistic is computed at lag only (not up to lag). - :type max_pct_missing: + :type noloop: :param max_pct_missing: default value = 100. Maximum fraction of cell which is allowed to be masked (missing). Set to a percentage between 0 and 100%. Set to 0. to mask results if any data is masked. Set to 100. to calculate result if any data is not masked + :type max_pct_missing: """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.autocovariance") if cdms2.isVariable(x) : xatt=x.attributes @@ -1152,35 +1151,35 @@ def autocorrelation(x,lag=None,axis=0,centered=1,partial=1,biased=1,noloop=0,max >>> result = autocorrelation(x, lag=lagoptions, axis=axisoptions, centered=centeredoptions, partial=partialoptions, biased=biasedoptions, noloop=noloopoptions) - :type lag: :param lag: None | n | (n1, n2, n3...) | [n1, n2, n3 ....] default value = None the maximum possible lags for specified axis is - used.You can pass an integer, list of integers, or tuple of integers. - :type axis: + used.You can pass an integer, list of integers, or tuple of integers. + :type lag: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type centered: + :type axis: :param centered: None | 0 | 1 default value = 1 removes the mean first. Set to 0 or None for uncentered statistic. - :type partial: + :type centered: :param partial: None | 0 | 1 default value = 1 uses only common time for means. - :type biased: + :type partial: :param biased: None | 0 | 1 default value = 1 computes the biased statistic. If want to compute an unbiased statistic pass anything but 1. - :type noloop: + :type biased: :param noloop: None | 0 | 1 default value = 0 computes statistic at all lags upto 'lag'. If you set noloop=1 statistic is computed at lag only (not up to lag). - :type max_pct_missing: + :type noloop: :param max_pct_missing: default value = 100. Maximum fraction of cell which is allowed to be masked (missing). Set to a percentage between 0 and 100%. Set to 0. to mask results if any data is masked. Set to 100. to calculate result if any data is not masked + :type max_pct_missing: """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.autocorrelation") x,dum,dum,axis,ax=__checker(x,None,None,axis) @@ -1226,23 +1225,23 @@ def meanabsdiff(x,y,weights=None,axis=0,centered=1,max_pct_missing=100.): >>> result = meanabsdiff(x, y, weights=weightoptions, axis = axisoptions, centered=centeredoptions) - :type weights: :param weights: default = None returns equally weighted statistic. If you want to compute the weighted statistic, provide weights here. - :type axis: + :type weights: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type centered: + :type axis: :param centered: None | 0 | 1 default value = 1 removes the mean first. Set to 0 or None for uncentered. - :type max_pct_missing: + :type centered: :param max_pct_missing: default value = 100. Maximum fraction of cell which is allowed to be masked (missing). Set to a percentage between 0 and 100%. Set to 0. to mask results if any data is masked. Set to 100. to calculate result if any data is not masked + :type max_pct_missing: """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.meanabsdiff") if cdms2.isVariable(x) : xatt=x.attributes @@ -1274,21 +1273,20 @@ def linearregression(y,axis=None,x=None,error=None,probability=None,nointercept= error=erroroptions, probability=probabilityoptions, \ nointercept=nointerceptoptions, noslope=noslopeoptions) - :type axis: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to treat the array as the dependent variable. - :type nointercept: + :type axis: :param nointercept: None | 0 | 1 default = None. Setting to 0 or None means intercept calculations are returned. To turn OFF the intercept computations set nointercept = 1. - :type noslope: + :type nointercept: :param noslope: None | 0 | 1 default = None. Setting to None or 0 means slope calculations are returned. To turn OFF the slope computations set noslope to 1. - :type error: + :type noslope: :param error: None | 0 | 1 | 2 | 3 default = None. If set to 0 or None, no associated errors are returned. @@ -1297,7 +1295,7 @@ def linearregression(y,axis=None,x=None,error=None,probability=None,nointercept= adjusted using the centered autocorrelation of the residual. If set to 3, standard error returned. The standard error here is adjusted using the centered autocorrelation of the raw data (y). - :type probability: + :type error: :param probability: None | 0 | 1 default = None. If set to 0 or None, no associated probabilities are returned. Set this to 1to compute probabilities. @@ -1307,6 +1305,7 @@ def linearregression(y,axis=None,x=None,error=None,probability=None,nointercept= Probabilities are returned only if erroroptions are set to one of 1, 2, or 3. If it is set to None or 0, then setting probabilityoptions has no meaning. + :type probability: What is returned? The returned values depend on the combination of options you select. If @@ -1379,7 +1378,7 @@ def linearregression(y,axis=None,x=None,error=None,probability=None,nointercept= >>> intercept,intercept_error,pt1,pt2,pf1,pf2 = \ linearregression(y, error=2,probability=1,noslope=1) -""" + """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.linearregression") yisV=cdms2.isVariable(y) if yisV : yatt=y.attributes @@ -1530,17 +1529,17 @@ def geometricmean(x,axis=0,max_pct_missing=100.): >>> result = geometricmean(x, axis=axisoptions) - :type axis: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. + (integer value 0...n) over which you want to compute the statistic. + :type axis: - :type max_pct_missing: :param max_pct_missing: default value = 100. Maximum fraction of cell which is allowed to be masked (missing). Set to a percentage between 0 and 100%. Set to 0. to mask results if any data is masked. Set to 100. to calculate result if any data is not masked + :type max_pct_missing: """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.geometricmean") if cdms2.isVariable(x) : xatt=x.attributes @@ -1611,13 +1610,14 @@ def percentiles(x,percentiles=[50.],axis=0): >>> result = percentiles(x, percentiles=percentilesoptions, axis=axisoptions) - :type percentilesoptions: - :param percentilesoptions: A python list of values + :param percentiles: A python list of values Default = [50.] (the 50th percentile i.e the median value) - :type axis: + :type percentiles: + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. + :type axis: """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.percentiles") if cdms2.isVariable(x) : xatt=x.attributes @@ -1643,11 +1643,13 @@ def median(x,axis=0): >>> result = median(x, axis=axisoptions) - :type axisoptions: - :type axisoptions: - :param axisoptions: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :param x: + :type x: + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. + (integer value 0...n) over which you want to compute the statistic. + :type axis: str or int """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.median") tmp=percentiles(x,percentiles=[50.],axis=axis) @@ -1665,12 +1667,11 @@ def rank(x,axis=0): .. doctest:: >>> result = median(x, axis=axisoptions) - - :type axis: - :type axis: + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. + (integer value 0...n) over which you want to compute the statistic. + :type axis: """ # preprocessing From 9813db31cb3aca2192ac928bdaaaad789530d0b4 Mon Sep 17 00:00:00 2001 From: embrown Date: Thu, 17 Nov 2016 10:05:14 -0800 Subject: [PATCH 4/5] Mostly done converting docstrings. Need to set up sphinx and testing stuff. --- Lib/ASCII.py | 19 +- Lib/arrayindexing.py | 26 +- Lib/averager.py | 9 +- Lib/colors.py | 9 + Lib/filters.py | 7 +- Lib/selval.py | 40 +- Lib/statistics.py | 878 +++++++++++++++++++++++++------------------ Lib/statusbar.py | 2 - 8 files changed, 585 insertions(+), 405 deletions(-) diff --git a/Lib/ASCII.py b/Lib/ASCII.py index 2aa8ddd..af13bfb 100644 --- a/Lib/ASCII.py +++ b/Lib/ASCII.py @@ -110,19 +110,20 @@ def read_col( text_file ,header=0, cskip=0, cskip_type='columns', axis=False, id :param text_file: ASCII File to read from. :type text_file: - :param header: (0) Number of header lines, these lines will be skipped. - :type header: + :param header: Number of header lines, these lines will be skipped. + :type header: int - :param cskip: (0) Number of 'column'/'character' to skip (dummy column) - :type cskip: + :param cskip: Number of 'column'/'character' to skip (dummy column) + :type cskip: int - :param cskip_type: ('column') is 'cskip' a number of 'column' or 'character' to skip? - :type cskip_type: + :param cskip_type: One of 'columns' or 'characters'. Specifies which should be skipped. + :type cskip_type: str - :param axis: (False) Use as the values for the first column as variable axis (x values in y(x)) - :type axis: + :param axis: Boolean flag indicating whether to use as the values for the first column as + variable axis (x values in y(x)). + :type axis: bool - :param idrow: (False) Is the first row representing the ids of var generated ? + :param idrow: Is the first row representing the ids of var generated. :type idrow: :param ids: (None) use the values in this list as variable ids (1 per column returned) diff --git a/Lib/arrayindexing.py b/Lib/arrayindexing.py index fe7fb57..4cef1b4 100644 --- a/Lib/arrayindexing.py +++ b/Lib/arrayindexing.py @@ -20,6 +20,11 @@ def get(Array,Indices,axis=0): :type Array: cdms.tvariable.TransientVariable or numpy.array :param Indices: List of integers specifying the indices of Array to access and return + + .. note:: + + Negative index value will access indices starting from the end of the array. + i.e. -1 will be the last item. :type Indices: list :param axis: Axis of a cdms variable @@ -66,16 +71,27 @@ def get(Array,Indices,axis=0): def set(Array,Indices,Values,axis=0): """ Arrayrrayindexing set Array[Indices] with Values, indices are taken along dimension given with axis - - Usage: - Array=set(Array,Indices,Values,axis=0) # i.e. Array[Indices]=Values - Indices accepts negative value ,e.g: -1 is last element + :Example: + + .. doctest:: arrayindexing_set + + >>> import numpy as np + >>> Array=np.array([2,3,1,0,1,2,3]) + >>> Indices=[0,-1, len(Array)-2] # get the first, last, and second-to-last indices of the array + >>> Values = [5, 7, 9] + >>> Array=set(Array,Indices,Values,axis=0) # i.e. Array[Indices]=Values + :param Array: A cdms2 variable, or numpy array, to set the indices of :type Array: cdms.tvariable.TransientVariable or numpy.array - :param Indices: List of integers specifying the indices of Array to access and set + :param Indices: List of integers specifying the indices of Array to access and set. + + .. note:: + + Negative index value will access indices starting from the end of the array. + i.e. -1 will be the last item. :type Indices: list :param axis: Axis of a cdms variable diff --git a/Lib/averager.py b/Lib/averager.py index cbc60d8..8afede7 100644 --- a/Lib/averager.py +++ b/Lib/averager.py @@ -727,11 +727,10 @@ def averager(V, axis=None, weights=None, action='average', returned=0, weight=No .. code-block:: python - from cdutil import averager - averager(V, axis='axisoptions', weights=weightoptions, action='average', - returned='0') - - + >>> import numpy as np + >>> V=np.array([1,2,3,4,5]) + >>> averager(V, returned=1) + 3 :param V: an array of numpy, numpy.ma or MV2 type :type V: numpy.array or numpy.ma or MV2 diff --git a/Lib/colors.py b/Lib/colors.py index 0234fb5..49b1755 100644 --- a/Lib/colors.py +++ b/Lib/colors.py @@ -710,6 +710,15 @@ def rgb2str(r,g=None,b=None): >>> print rgb2str([0,0,0]) 'black' + + :param r: Either a list of size 3 with r, g, and b values, or an integer representing r value. + :type r: list or int + + :param g: Integer representing g value. + :type g: int + + :param b: Integer representing b value. + :type b: int """ import string if g is None and len(r)==3: diff --git a/Lib/filters.py b/Lib/filters.py index 5c8175d..b09d485 100644 --- a/Lib/filters.py +++ b/Lib/filters.py @@ -86,6 +86,9 @@ def smooth121(x,axis=0): >>> unfiltered=f('clt') >>> filtered = smooth121(unfiltered) # filter over axis at index 0 + :param x: A CDMS TransientVariable + :type x: cdms.tvariable.TransientVariable + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. @@ -109,8 +112,8 @@ def runningaverage(x,N,axis=0): >>> x=f('clt') >>> smooth = runningaverage(x,12) - :param x: - :type x: + :param x: A CDMS TransientVariable + :type x: cdms.tvariable.TransientVariable :param N: length of the running average :type N: int diff --git a/Lib/selval.py b/Lib/selval.py index d08649b..74c8b2e 100644 --- a/Lib/selval.py +++ b/Lib/selval.py @@ -5,14 +5,20 @@ class PickComponent(SelectorComponent): """ Let the user pick non contiguous values along an axis - keyword "match" is reserved for handling of inexisting values + keyword "match" is reserved for handling of non-existing values match=1 : (default): raise an exception if one of the select-values does not exist match=0 : replace inexistince selcet-values with missing match=-1: skip inexisting select-values """ def __init__(self,*args,**kargs): - """ initialise some value such as tolerances for equality""" + """Initialise some values such as tolerances for equality + + :param kargs: match is the most relevant keyword argument. There is a + match=1 : (default): raise an exception if one of the select-values does not exist + match=0 : replace inexistence select-values with missing + match=-1: skip inexistent select-values + """ self.args=args self.kargs=kargs self.match=kargs.get('match',1) @@ -177,25 +183,23 @@ def picker(*args, **kargs): Let the user pick non contiguous values along an axis Usage: picker(dim2=list1,dim2=list2) - keyword 'match' is reserved for handling of inexisting values + keyword 'match' is reserved for handling of inexistent values match=1 : (default): raise an exception if one of the select-values does not exist - match=0 : replace inexistince selcet-values with missing + match=0 : replace inexistince select-values with missing match=-1: skip inexisting select-values - Example: - f=cdms.open('/pcmdi/obs/mo/ta/rnl_ncep/ta.rnl_ncep.ctl') - #f first levels are 1000.00, 925.00, 850.00, 700.00 - s=f('ta,picker(level=[1000,850,700])) - #or - s=f('ta,picker(level=[1000,700,850]) # different order from first example - #or - s=f('ta,picker(level=[1000,700,800]) # raise an exception since 800 doesn't exist - #or - s=f('ta,picker(level=[1000,700,800],match=0) # replace 800 level with missing values - #or - s=f('ta,picker(level=[1000,700,800],match=-1) # skip 800 level - # or - s=f('ta',genutil.picker(time=['1987-7','1988-3',cdtime.comptime(1989,3)],level=[1000,700,850])) + :Example: + + .. doctest:: selval_picker + + # The following examples show numerous ways of specifying a picker + >>> f=cdms.open('/pcmdi/obs/mo/ta/rnl_ncep/ta.rnl_ncep.ctl') + >>> s=f('ta',picker(level=[1000,850,700])) # f first levels are 1000.00, 925.00, 850.00, 700.00 + >>> s=f('ta',picker(level=[1000,700,850]) # different order from first example + >>> s=f('ta',picker(level=[1000,700,800]) # raise an exception since 800 doesn't exist + >>> s=f('ta',picker(level=[1000,700,800],match=0) # replace 800 level with missing values + >>> s=f('ta',picker(level=[1000,700,800],match=-1) # skip 800 level + >>> s=f('ta',genutil.picker(time=['1987-7','1988-3',cdtime.comptime(1989,3)],level=[1000,700,850])) """ cdat_info.pingPCMDIdb("cdat","genutil.picker") diff --git a/Lib/statistics.py b/Lib/statistics.py index 916ef7f..84728b6 100644 --- a/Lib/statistics.py +++ b/Lib/statistics.py @@ -79,16 +79,16 @@ def __betai1(a, b, x): def __probnd1(x): """ - c FUNCTION PROBND1. - c - c Calculates the area under a normal curve (mean=0.0, variance=1.0) - c to the right of x. The accuracy is better than 7.5 * 10.**-8. - c - c REFERENCE: - c - c M. Abramowitz and I.A. Stegun. - c Handbook of Mathematical Functions. - c Dover, 1970, pages 931-932 (26.2.1 and 26.2.17). + FUNCTION PROBND1. + + Calculates the area under a normal curve (mean=0.0, variance=1.0) + to the right of x. The accuracy is better than 7.5 * 10.**-8. + + REFERENCE: + + M. Abramowitz and I.A. Stegun. + Handbook of Mathematical Functions. + Dover, 1970, pages 931-932 (26.2.1 and 26.2.17). """ b1 = 0.319381530 b2 = -0.356563782 @@ -106,36 +106,36 @@ def __probnd1(x): def __probf1(y, n1, n2, id): """ -c FUNCTION PROBF1. -c -c The output is either the one- or two-tailed test area: i.e., the -c area under an F-curve (with N1 and N2 degrees of freedom) to the -c right of X if X exceeds 1.0 (one-tailed test) or twice this area -c (two-tailed test). -c -c Note: if X is less than 1.0, this function gives the area to the -c right of 1/X with reversed order for the degrees of freedom. This -c ensures the accuracy of the numerical algorithm. -c -c REFERENCE: -c -c M. Abramowitz and I.A. Stegun. -c Handbook of Mathematical Functions. -c Dover, 1970, page 947 (26.6.15). - -c ** INPUT ** -c real y Calculated F-value -c real x Inverse of Y if Y is less than 1.0 -c integer n1, n2 Degrees of freedom -c integer id Identifier for one- or two-tailed test -c -c ** OUTPUT ** -c real probf1 Significance level (p-value) for F-value -c -c EXTERNALS: -c -c function PROBND1 - Calculates the area under a normal curve. -""" + FUNCTION PROBF1. + + The output is either the one- or two-tailed test area: i.e., the + area under an F-curve (with N1 and N2 degrees of freedom) to the + right of X if X exceeds 1.0 (one-tailed test) or twice this area + (two-tailed test). + + Note: if X is less than 1.0, this function gives the area to the + right of 1/X with reversed order for the degrees of freedom. This + ensures the accuracy of the numerical algorithm. + + REFERENCE: + + M. Abramowitz and I.A. Stegun. + Handbook of Mathematical Functions. + Dover, 1970, page 947 (26.6.15). + + ** INPUT ** + real y Calculated F-value + real x Inverse of Y if Y is less than 1.0 + integer n1, n2 Degrees of freedom + integer id Identifier for one- or two-tailed test + + ** OUTPUT ** + real probf1 Significance level (p-value) for F-value + + EXTERNALS: + + function PROBND1 - Calculates the area under a normal curve. + """ ly=numpy.ma.less(y,1.) x=numpy.ma.where(ly,1./numpy.ma.array(y),y) n=numpy.ma.where(ly,n1,n2) @@ -253,6 +253,7 @@ def __correlation(x,y,weights=None,centered=1,biased=1): sy=__std(y,weights=weights,centered=centered,biased=biased) return cov/(sx*sy) + def __rms(x,y,weights=None,centered=0,biased=1): """ Function: __rms @@ -264,6 +265,7 @@ def __rms(x,y,weights=None,centered=0,biased=1): return __std(x-y,centered=centered,biased=biased,weights=weights) + def __laggedcovariance(x,y,lag=1,centered=1,partial=1): """ Function: __laggedcovariance @@ -303,6 +305,7 @@ def __laggedcovariance(x,y,lag=1,centered=1,partial=1): tmp=x[:-lag]*y[lag:] return numpy.ma.sum(tmp, axis=0)/numpy.ma.count(x*y,axis=0) + def __laggedcorrelation(x,y,lag,centered=1,partial=1,biased=1): """ Function: __laggedcorrelation @@ -680,33 +683,44 @@ def covariance(x,y,weights=None,axis=0,centered=1,biased=1,max_pct_missing=100.) :Example: - .. doctest:: + .. doctest:: statistics_covariance + + >>> import vcs, cdms2, os + >>> try: + ... os.listdir(vcs.sample_data) + >>> except: + ... vcs.download_sample_data_files() + >>> f=cdms2.open(vcs.sample_data + 'clt.nc') + >>> x=f('u') + >>> y=f('v') + >>> cov = covariance(x, y) # default covariance of x and y - >>> cov = covariance(x, y, weights=weightoptions, axis=axisoptions, - centered=centeredoptions, biased=biasedoptions, - max_pct_missing=max_pct_missingoptions) - :param weights: - default = None. If you want to compute the weighted covariance, - provide the weights here. - :type weights: + :param x: The first slab. + :type x: cdms2.tvariable.TransientVariable or numpy.array + + :param y: The second slab + :type y: cdms2.tvariable.TransientVariable or numpy.array + + :param weights: list of weights for assessing the weighted covariance + + .. note:: + + Weighted covariance is inherently biased. Passing a value for weights but + specifying an unbiased variance will cause an error + + :type weights: list :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type axis: - :param centered: None | 0 | 1 - default value = 1 removes the mean first. Set to 0 or None for - uncentered. - :type centered: - :param biased: None | 0 | 1 - default value = 1 If want to compute an unbiased variance pass - anything but 1. - :type biased: - :param max_pct_missing: - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked - :type max_pct_missing: + :type axis: int or str + :param centered: Integer flag for whether the covariance should be centered. + 0 or None means don't center, 1 means center. + :type centered: int + :param biased: Flag indicating whether covariance should be calculated with bias. A value of 1 indicates covariance + should be biased, while any other value indicates that it should not. + :type biased: int + :param max_pct_missing: Maximum percentage of cell which is allowed to be masked (missing). + :type max_pct_missing: float """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.covariance") if cdms2.isVariable(x) : xatt=x.attributes @@ -728,32 +742,43 @@ def variance(x,weights=None,axis=0,centered=1,biased=1,max_pct_missing=100.): :Example: - .. doctest:: + .. doctest:: statistics_variance + + >>> import vcs, cdms2, os + >>> try: + ... os.listdir(vcs.sample_data) + >>> except: + ... vcs.download_sample_data_files() + >>> f=cdms2.open(vcs.sample_data + 'clt.nc') + >>> x=f('u') + >>> result = variance(x) # default variance of x + + :param x: Slab to compute variance of. + :type x: cdms2.tvariable.TransientVariable or numpy.array + + :param weights: list of weights(floats) for assessing the weighted variance + + .. note:: + + Weighted covariance is inherently biased. Passing a value for weights but + specifying an unbiased variance will cause an error + :type weights: list - >>> result = variance(x, weights=weightoptions, axis = axisoptions, - centered=centeredoptions, biased = biasedoptions, - max_pct_missing=max_pct_missingoptions) - :param weightoptions: - If you want to compute the weighted variance, provide weights here. - :type weightoptions: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type axis: - :param centered: None | 0 | 1 - default value = 1 removes the mean first. Set to 0 or None for - uncentered. - :type centered: - :param biased: None | 0 | 1 - default value = 1 If want to compute an unbiased variance pass - anything but 1. - :type biased: - :param max_pct_missing: - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked - :type max_pct_missing: + :type axis: int or str + + :param centered: Integer flag for whether the variance should be centered. + 0 or None means don't center, 1 means center. + :type centered: int + + :param biased: Flag indicating whether variance should be calculated with bias. A value of 1 indicates variance + should be biased, while any other value indicates that it should not. + :type biased: int + + :param max_pct_missing: Maximum percentage of cell which is allowed to be masked (missing). + :type max_pct_missing: float """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.variance") if cdms2.isVariable(x) : xatt=x.attributes @@ -779,32 +804,43 @@ def std(x,weights=None,axis=0,centered=1,biased=1,max_pct_missing=100.): :Example: - .. doctest:: + .. doctest:: statistics_std + + >>> import vcs, cdms2, os + >>> try: + ... os.listdir(vcs.sample_data) + >>> except: + ... vcs.download_sample_data_files() + >>> f=cdms2.open(vcs.sample_data + 'clt.nc') + >>> x=f('u') + >>> result = std(x) # default standard deviation of x + + :param x: Slab to compute std of. + :type x: cdms2.tvariable.TransientVariable or numpy.array + + :param weights: list of weights(floats) for assessing the weighted calculation + + .. note:: + + Use of weights is inherently biased. Passing a value for weights but + specifying a non-biased calculation will cause an error. + :type weights: list - >>> result = std(x, weights=weightoptions, axis = axisoptions, - centered=centeredoptions, biased = biasedoptions, - max_pct_missing=max_pct_missingoptions) - :param weightoptions: - If you want to compute the weighted statistic, provide weights here. - :type weightoptions: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type axis: - :param centered: None | 0 | 1 - default value = 1 removes the mean first. Set to 0 or None for - uncentered. - :type centered: - :param biased: None | 0 | 1 - :type biased: - default value = 1 If want to compute an unbiased variance pass - anything but 1. - :param max_pct_missing: - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked - :type max_pct_missing: + :type axis: int or str + + :param centered: Integer flag for whether the calculation should be centered. + 0 or None means don't center, 1 means center. + :type centered: int + + :param biased: Flag indicating whether std should be calculated with bias. A value of 1 indicates calculation + should be biased, while any other value indicates that it should not. + :type biased: int + + :param max_pct_missing: Maximum percentage of cell which is allowed to be masked (missing). + :type max_pct_missing: float """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.std") if cdms2.isVariable(x) : xatt=x.attributes @@ -824,33 +860,46 @@ def correlation(x,y,weights=None,axis=0,centered=1,biased=1,max_pct_missing=100. :Example: - .. doctest:: + .. doctest:: statistics_correlation + + >>> import vcs, cdms2, os + >>> try: + ... os.listdir(vcs.sample_data) + >>> except: + ... vcs.download_sample_data_files() + >>> f=cdms2.open(vcs.sample_data + 'clt.nc') + >>> x=f('u') + >>> y=f('v') + >>> result = correlation(x, y) # calculate the default correlation + :param x: First slab. + :type x: cdms2.tvariable.TransientVariable or numpy.array + + :param y: Second slab. + :type y: cdms2.tvariable.TransientVariable or numpy.array + + :param weights: list of weights(floats) for assessing the weighted calculation + + .. note:: + + Use of weights is inherently biased. Passing a value for weights but + specifying a non-biased calculation will cause an error. + :type weights: list - >>> result = correlation(x, y, weights=weightoptions, axis=axisoptions, - centered=centeredoptions, biased=biasedoptions, - max_pct_missing=max_pct_missingoptions) - :param weights: - default = None. If you want to compute the weighted correlation, - provide the weights here. - :type weights: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type axis: - :param centered: None | 0 | 1 - default value = 1 removes the mean first. Set to 0 or None for - uncentered. - :type centered: - :param biased: None | 0 | 1 - default value = 1 returns biased statistic. If want to compute an - unbiased statistic pass anything but 1. - :type biased: - :param max_pct_missing: - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked - :type max_pct_missing: + :type axis: int or str + + :param centered: Integer flag for whether the calculation should be centered. + 0 or None means don't center, 1 means center. + :type centered: int + + :param biased: Flag indicating whether calculation should be biased. A value of 1 indicates calculation + should be biased, while any other value indicates that it should not. + :type biased: int + + :param max_pct_missing: Maximum percentage of cell which is allowed to be masked (missing). + :type max_pct_missing: float """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.corelation") x,y,weights,axis,ax=__checker(x,y,weights,axis) @@ -869,34 +918,46 @@ def rms(x,y,weights=None,axis=0,centered=0,biased=1,max_pct_missing=100.): :Example: - .. doctest:: + .. doctest:: statistics_rms + + >>> import vcs, cdms2, os + >>> try: + ... os.listdir(vcs.sample_data) + >>> except: + ... vcs.download_sample_data_files() + >>> f=cdms2.open(vcs.sample_data + 'clt.nc') + >>> x=f('u') + >>> y=f('v') + >>> result = rms(x, y) # default rms calculation + :param x: First slab. + :type x: cdms2.tvariable.TransientVariable or numpy.array + + :param y: Second slab. + :type y: cdms2.tvariable.TransientVariable or numpy.array + + :param weights: list of weights(floats) for assessing the weighted calculation + + .. note:: + + Use of weights is inherently biased. Passing a value for weights but + specifying a non-biased calculation will cause an error. + :type weights: list - >>> result = rms(x, y, weights=weightoptions, axis = axisoptions, - centered=centeredoptions, biased = biasedoptions, - max_pct_missing=max_pct_missingoptions) - :param weights: - default = None returns equally weighted statistic. If you want to - compute the weighted statistic, provide weights here. - :type weights: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type axis: - :param centered: None | 0 | 1 - default value = 0 returns uncentered statistic (same as None). To - remove the mean first (i.e centered statistic) set to 1. NOTE: Most - other statistic functions return a centered statistic by default. - :type centered: - :param biased: None | 0 | 1 - default value = 1 If want to compute an unbiased variance pass - anything but 1. - :type biased: - :param max_pct_missing: - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked - :type max_pct_missing: + :type axis: int or str + + :param centered: Integer flag for whether the calculation should be centered. + 0 or None means don't center, 1 means center. + :type centered: int + + :param biased: Flag indicating whether calculation should be biased. A value of 1 indicates calculation + should be biased, while any other value indicates that it should not. + :type biased: int + + :param max_pct_missing: Maximum percentage of cell which is allowed to be masked (missing). + :type max_pct_missing: float """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.rms") if cdms2.isVariable(x) : xatt=x.attributes @@ -916,40 +977,49 @@ def laggedcovariance(x,y,lag=None,axis=0,centered=1,partial=1,noloop=0,max_pct_m :Example: - .. doctest:: + .. doctest:: statistics_laggedcovariance - >>> result = laggedcovariance(x, y, lag=lagoptions, axis=axisoptions, - centered=centeredoptions, - partial=partialoptions, noloop=noloopoptions) + >>> import vcs, cdms2, os, os + >>> try: + ... os.listdir(vcs.sample_data) + >>> except: + ... vcs.download_sample_data_files() + >>> f=cdms2.open(vcs.sample_data + '/clt.nc') + >>> x=f('u') + >>> y=f('v') + >>> result = laggedcovariance(x, y) # default laggedcovariance calculation, with max. number of lags + + :param x: First slab. + :type x: cdms2.tvariable.TransientVariable or numpy.array + + :param y: Second slab. + :type y: cdms2.tvariable.TransientVariable or numpy.array + + :param lag: Integer, list of integers, tuple of integers, or None. If None, maximum possible lags for specified axis + are used. + :type lag: int or list or tuple or None - Returns value for x lags y by lag (integer) - - :param lag: None | n | (n1, n2, n3...) | [n1, n2, n3 ....] - default value = None the maximum possible lags for specified axis - is used.You can pass an integer, list of integers, or tuple of - integers. - :type lag: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type axis: - :param centered: - default value = 1 removes the mean first. Set to 0 or None for - uncentered - :type centered: - :param partial: None | 0 | 1 - default value = 1 uses only common time for means. - :type partial: + :type axis: int or str + + :param centered: Integer flag for whether the calculation should be centered. + 0 or None means don't center, 1 means center. + :type centered: int + + :param centered: Integer flag for whether the calculation should be centered. + 0 or None means don't center, 1 means center. + :type centered: int + :param partial: Integer flag. If 1, uses only common time for means. + :type partial: int or None :param noloop: None | 0 | 1 default value = 0 computes statistic at all lags upto 'lag'. If you set noloop=1 statistic is computed at lag only (not up to lag). - :type noloop: - :param max_pct_missing: - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked - :type max_pct_missing: + :type noloop: int or None + + :param max_pct_missing: Maximum percentage of cell which is allowed to be masked (missing). + :type max_pct_missing: float """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.laggedcovariance") if cdms2.isVariable(x) : xatt=x.attributes @@ -995,44 +1065,50 @@ def laggedcorrelation(x,y,lag=None,axis=0,centered=1,partial=1,biased=1,noloop=0 :Example: - .. doctest:: + .. doctest:: statistics_laggedcorrelation - >>> result = laggedcorrelation(x, y, lag=lagoptions, axis=axisoptions, - centered=centeredoptions, - partial=partialoptions, - biased=biasedoptions, noloop=noloopoptions) + >>> import vcs, cdms2, os + >>> try: + ... os.listdir(vcs.sample_data) + >>> except: + ... vcs.download_sample_data_files() + >>> f=cdms2.open(vcs.sample_data + 'clt.nc') + >>> x=f('u') + >>> y=f('v') + >>> result = laggedcorrelation(x, y) # default laggedcorrelation, with max. number of lags - Returns value for x lags y by lag - :param lag: None | n | (n1, n2, n3...) | [n1, n2, n3 ....] - default value = None the maximum possible lags for specified axis - is used.You can pass an integer, list of integers, or tuple of integers. - :type lag: + :param x: First slab. + :type x: cdms2.tvariable.TransientVariable or numpy.array + + :param y: Second slab. + :type y: cdms2.tvariable.TransientVariable or numpy.array + + :param lag: Integer, list of integers, tuple of integers, or None. + If None, maximum possible lags for specified axis are used. + :type lag: int or list or tuple or None + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type axis: - :param centered: - default value = 1 removes the mean first. Set to 0 or None for - uncentered - :type centered: - :param partial: None | 0 | 1 - default value = 1 uses only common time for means. - :type partial: - :param biased: None | 0 | 1 - default value = 1 If want to compute an unbiased variance pass - anything but 1. - :type biased: + :type axis: int or str + + :param centered: Integer flag for whether the calculation should be centered. + 0 or None means don't center, 1 means center. + :type centered: int + + :param centered: Integer flag for whether the calculation should be centered. + 0 or None means don't center, 1 means center. + :type centered: int + :param partial: Integer flag. If 1, uses only common time for means. + :type partial: int or None :param noloop: None | 0 | 1 default value = 0 computes statistic at all lags upto 'lag'. If you set noloop=1 statistic is computed at lag only (not up to lag). - :type noloop: - :param max_pct_missing: - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked - :type max_pct_missing: + :type noloop: int or None + + :param max_pct_missing: Maximum percentage of cell which is allowed to be masked (missing). + :type max_pct_missing: float """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.laggedcorrelation") x,y,w,axis,ax=__checker(x,y,None,axis) @@ -1075,36 +1151,47 @@ def autocovariance(x,lag=None,axis=0,centered=1,partial=1,noloop=0,max_pct_missi :Example: - .. doctest:: + .. doctest:: statistics_autocovariance + + >>> import vcs, cdms2, os + >>> try: + ... os.listdir(vcs.sample_data) + >>> except: + ... vcs.download_sample_data_files() + >>> f=cdms2.open(vcs.sample_data + 'clt.nc') + >>> x=f('u') + >>> result = autocovariance(x) # default autocovariance + + :param x: First slab. + :type x: cdms2.tvariable.TransientVariable or numpy.array + + :param lag: Integer, list of integers, tuple of integers, or None. + If None, maximum possible lags for specified axis are used. + :type lag: int or list or tuple or None - >>> result = autocovariance(x, lag=lagoptions, axis=axisoptions, - centered=centeredoptions, - partial=partialoptions, noloop=noloopoptions) - :param lag: None | n | (n1, n2, n3...) | [n1, n2, n3 ....] - default value = None the maximum possible lags for specified axis - is used.You can pass an integer, list of integers, or tuple of integers. - :type lag: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type axis: - :param centered: None | 0 | 1 - default value = 1 removes the mean first. Set to 0 or None for - uncentered statistic. - :type centered: - :param partial: None | 0 | 1 - default value = 1 uses only common time for means. - :type partial: + :type axis: int or str + + :param centered: Integer flag for whether the calculation should be centered. + 0 or None means don't center, 1 means center. + :type centered: int + + :param centered: Integer flag for whether the calculation should be centered. + 0 or None means don't center, 1 means center. + :type centered: int + + :param partial: Integer flag. If 1, uses only common time for means. + :type partial: int or None + :param noloop: None | 0 | 1 default value = 0 computes statistic at all lags upto 'lag'. If you set noloop=1 statistic is computed at lag only (not up to lag). - :type noloop: - :param max_pct_missing: - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked - :type max_pct_missing: + :type noloop: int or None + + :param max_pct_missing: Maximum percentage of cell which is allowed to be masked (missing). + :type max_pct_missing: float """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.autocovariance") if cdms2.isVariable(x) : xatt=x.attributes @@ -1146,40 +1233,46 @@ def autocorrelation(x,lag=None,axis=0,centered=1,partial=1,biased=1,noloop=0,max :Example: - .. doctest:: + .. doctest:: statistics_autocorrelation + + >>> import vcs, cdms2, os + >>> try: + ... os.listdir(vcs.sample_data) + >>> except: + ... vcs.download_sample_data_files() + >>> f=cdms2.open(vcs.sample_data + 'clt.nc') + >>> x=f('u') + >>> result = autocorrelation(x) + :param x: First slab. + :type x: cdms2.tvariable.TransientVariable or numpy.array + + :param lag: Integer, list of integers, tuple of integers, or None. + If None, maximum possible lags for specified axis are used. + :type lag: int or list or tuple or None - >>> result = autocorrelation(x, lag=lagoptions, axis=axisoptions, - centered=centeredoptions, partial=partialoptions, - biased=biasedoptions, noloop=noloopoptions) - :param lag: None | n | (n1, n2, n3...) | [n1, n2, n3 ....] - default value = None the maximum possible lags for specified axis is - used.You can pass an integer, list of integers, or tuple of integers. - :type lag: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type axis: - :param centered: None | 0 | 1 - default value = 1 removes the mean first. Set to 0 or None for - uncentered statistic. - :type centered: - :param partial: None | 0 | 1 - default value = 1 uses only common time for means. - :type partial: - :param biased: None | 0 | 1 - default value = 1 computes the biased statistic. If want to compute - an unbiased statistic pass anything but 1. - :type biased: + :type axis: int or str + + :param centered: Integer flag for whether the calculation should be centered. + 0 or None means don't center, 1 means center. + :type centered: int + + :param centered: Integer flag for whether the calculation should be centered. + 0 or None means don't center, 1 means center. + :type centered: int + + :param partial: Integer flag. If 1, uses only common time for means. + :type partial: int or None + :param noloop: None | 0 | 1 default value = 0 computes statistic at all lags upto 'lag'. If you set noloop=1 statistic is computed at lag only (not up to lag). - :type noloop: - :param max_pct_missing: - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked - :type max_pct_missing: + :type noloop: int or None + + :param max_pct_missing: Maximum percentage of cell which is allowed to be masked (missing). + :type max_pct_missing: float """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.autocorrelation") x,dum,dum,axis,ax=__checker(x,None,None,axis) @@ -1221,27 +1314,38 @@ def meanabsdiff(x,y,weights=None,axis=0,centered=1,max_pct_missing=100.): :Example: - .. doctest:: + .. doctest:: statistics_meanabsdiff + + >>> import vcs, cdms2, os + >>> try: + ... os.listdir(vcs.sample_data) + >>> except: + ... vcs.download_sample_data_files() + >>> f=cdms2.open(vcs.sample_data + 'clt.nc') + >>> x=f('u') + >>> y=f('v') + >>> result = meanabsdiff(x, y) # default mean absolute difference calculation + + :param x: First slab. + :type x: cdms2.tvariable.TransientVariable or numpy.array + + :param y: Second slab. + :type y: cdms2.tvariable.TransientVariable or numpy.array + + :param weights: list of weights for assessing the weighted calculation + :type weights: list - >>> result = meanabsdiff(x, y, weights=weightoptions, axis = axisoptions, - centered=centeredoptions) - :param weights: - default = None returns equally weighted statistic. If you want to - compute the weighted statistic, provide weights here. - :type weights: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type axis: - :param centered: None | 0 | 1 - default value = 1 removes the mean first. Set to 0 or None for uncentered. - :type centered: - :param max_pct_missing: - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked - :type max_pct_missing: + :type axis: int or str + + :param centered: Integer flag for whether the calculation should be centered. + 0 or None means don't center, 1 means center. + :type centered: int + + :param max_pct_missing: Maximum percentage of cell which is allowed to be masked (missing). + :type max_pct_missing: float """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.meanabsdiff") if cdms2.isVariable(x) : xatt=x.attributes @@ -1267,54 +1371,65 @@ def linearregression(y,axis=None,x=None,error=None,probability=None,nointercept= :Example: - .. doctest:: + .. doctest:: statistics_linearregression - >>> result = linearregression(y, axis=axisoptions, x=xoptions, \ - error=erroroptions, probability=probabilityoptions, \ - nointercept=nointerceptoptions, noslope=noslopeoptions) + >>> import vcs, cdms2, os + >>> try: + ... os.listdir(vcs.sample_data) + >>> except: + ... vcs.download_sample_data_files() + >>> f=cdms2.open(vcs.sample_data + 'clt.nc') + >>> y=f('v') + >>> result = linearregression(y, axis='x') # default linearregression over x axis + + :param y: Slab to compute linear regression of + :type y: cdms2.tvariable.TransientVariable or numpy.array :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n - default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to treat the array as the - dependent variable. - :type axis: - :param nointercept: None | 0 | 1 - default = None. Setting to 0 or None means intercept calculations + default value = 0. You can pass the name of the dimension or index + (integer value 0...n) over which you want to compute the statistic. + :type axis: int or str + + :param x: Slab over which linear regression of y will be computed + :type x: cdms2.tvariable.TransientVariable or numpy.array + + :param nointercept: Setting to 0 or None means intercept calculations are returned. To turn OFF the intercept computations set nointercept = 1. - :type nointercept: - :param noslope: None | 0 | 1 - default = None. Setting to None or 0 means slope calculations are + :type nointercept: int or None + + :param noslope: Setting to None or 0 means slope calculations are returned. To turn OFF the slope computations set noslope to 1. - :type noslope: - :param error: None | 0 | 1 | 2 | 3 - default = None. If set to 0 or None, no associated errors are + :type noslope: int or None + + :param error: If set to 0 or None, no associated errors are returned. If set to 1, the unadjusted standard error is returned. If set to 2, standard error returned. This standard error is adjusted using the centered autocorrelation of the residual. If set to 3, standard error returned. The standard error here is adjusted using the centered autocorrelation of the raw data (y). - :type error: - :param probability: None | 0 | 1 - default = None. If set to 0 or None, no associated probabilities are - returned. Set this to 1to compute probabilities. + :type error: int or None + + :param probability: If set to 0 or None, no associated probabilities are + returned. Set this to 1 to compute probabilities. .. note:: Probabilities are returned only if erroroptions are set to one of 1, 2, or 3. If it is set to None or 0, then setting probabilityoptions has no meaning. - :type probability: + :type probability: int or None + + :Return Values: - What is returned? The returned values depend on the combination of options you select. If both slope and intercept are required, a tuple is returned for both Value and optionally Error (or optionally associated Probabilities), but single values (not tuples) are returned if only one set (slope OR intercept) is required. See examples below for more details. - - When erroroption = 1 (from description above for erroroptions you know + + * When erroroption = 1 (from description above for erroroptions you know that means unadjusted standard error) and probabilityoption=1, then the following are returned: pt1 : The p-value for regression coefficient t-value. (With no @@ -1323,10 +1438,10 @@ def linearregression(y,axis=None,x=None,error=None,probability=None,nointercept= returned to keep the length of the returned values consistent. pf1 : The p-value for regression coefficient F-value (one-tailed). pf2 : The p-value for regression coefficient F-value (two-tailed). - - When erroroption = 2 or 3 (implying error adjustment using the residual + + * When erroroption = 2 or 3 (implying error adjustment using the residual or the raw data and probabilityoption = 1, then the following are - returned: + returned: pt1 : The p-value for regression coefficient t-value.(With effective sample size adjustment for standard error of slope. pt2 : The p-value for regression coefficient t-value.(With effective @@ -1334,49 +1449,51 @@ def linearregression(y,axis=None,x=None,error=None,probability=None,nointercept= t-value.) pf1 : The p-value for regression coefficient F-value (one-tailed). pf2 : The p-value for regression coefficient F-value (two-tailed). - - The values pt1 and pt2 are used to test the null hypothesis that b = 0 + + * The values pt1 and pt2 are used to test the null hypothesis that b = 0 (i.e., y is independent of x). - The values pf1 and pf2 are used to test the null hypothesis that the + * The values pf1 and pf2 are used to test the null hypothesis that the regression is linear (goodness of linear fit). For non-replicated values of y, the degrees of freedom are 1 and n-2. - Examples: + :Examples: - Let us first examine the default behaviour of the linearregression - function. - >>> Values = statistics.linearregression(y) - - #The returned "Values" is actually a tuple consisting of the slope and - #intercept. They can also be accessed as follows: - >>> slope, intercept = statistics.linearregression(y) + .. code-block:: python - If error estimates are also required, then: - >>> Values, Errors = linearregression(y, error=1) - - #where "Values" and "Errors" are tuples containing answer for - #slope AND intercept. You can break them as follows. - #slope, intercept = Value and slope_error, intercept_error = Errors. i.e. - >>> (slope, intercept), (slo_error, int_error) = \ - linearregression(y, error=1) - - #WARNING: The following will not work. - >>> slope, intercept, slo_error, int_error = linearregression(y, error=1) - - #To get the standard error non adjusted result for slope only - >>> slope, slope_error = linearregression(y, error=1, nointercept=1) - - #In the line below all the returned values are tuples. - >>> Values,Errors,Pt1,Pt2,Pf1,Pf2 = \ - linearregression(y, error=2,probability=1) - #That means in the above statement is returning tuples ordered so: - #(slope, intercept), (slo_error, int_error), (pt1_slo, pt1_int),\ - (pt2_slo, pt2_int), (pf1_slo, pf1_int), (pf2_slo, pf2_int) - - #If we want results returned for the intercept only. - >>> intercept,intercept_error,pt1,pt2,pf1,pf2 = \ - linearregression(y, error=2,probability=1,noslope=1) + # Let us first examine the default behaviour of the linearregression + # function. + >>> Values = statistics.linearregression(y) + + # The returned "Values" is actually a tuple consisting of the slope and + # intercept. They can also be accessed as follows: + >>> slope, intercept = statistics.linearregression(y) + + # If error estimates are also required, then: + >>> Values, Errors = linearregression(y, error=1) + + # where "Values" and "Errors" are tuples containing answer for + # slope AND intercept. You can break them as follows. + # slope, intercept = Value and slope_error, intercept_error = Errors. i.e. + >>> (slope, intercept), (slo_error, int_error) = \ + linearregression(y, error=1) + + # WARNING: The following will not work. + >>> slope, intercept, slo_error, int_error = linearregression(y, error=1) + + # To get the standard error non adjusted result for slope only + >>> slope, slope_error = linearregression(y, error=1, nointercept=1) + + # In the line below all the returned values are tuples. + >>> Values,Errors,Pt1,Pt2,Pf1,Pf2 = \ + linearregression(y, error=2,probability=1) + # That means in the above statement is returning tuples ordered so: + # (slope, intercept), (slo_error, int_error), (pt1_slo, pt1_int),\ + (pt2_slo, pt2_int), (pf1_slo, pf1_int), (pf2_slo, pf2_int) + + # If we want results returned for the intercept only. + >>> intercept,intercept_error,pt1,pt2,pf1,pf2 = \ + linearregression(y, error=2,probability=1,noslope=1) """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.linearregression") @@ -1525,21 +1642,27 @@ def geometricmean(x,axis=0,max_pct_missing=100.): :Example: - .. doctest:: + .. doctest:: statistics_geometricmean + + >>> import vcs, cdms2, os + >>> try: + ... os.listdir(vcs.sample_data) + >>> except: + ... vcs.download_sample_data_files() + >>> f=cdms2.open(vcs.sample_data + 'clt.nc') + >>> x=f('v') + >>> result = geometricmean(x, axis='x') - >>> result = geometricmean(x, axis=axisoptions) + :param x: Slab to compute geometric mean for + :type x: cdms2.tvariable.TransientVariable or numpy.array :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n - default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. - :type axis: - - :param max_pct_missing: - default value = 100. Maximum fraction of cell which is allowed to be masked (missing). - Set to a percentage between 0 and 100%. - Set to 0. to mask results if any data is masked. - Set to 100. to calculate result if any data is not masked - :type max_pct_missing: + default value = 0. You can pass the name of the dimension or index + (integer value 0...n) over which you want to compute the statistic. + :type axis: int or str + + :param max_pct_missing: Maximum percentage of cell which is allowed to be masked (missing). + :type max_pct_missing: float """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.geometricmean") if cdms2.isVariable(x) : xatt=x.attributes @@ -1606,18 +1729,28 @@ def percentiles(x,percentiles=[50.],axis=0): :Example: - .. doctest:: + .. doctest:: statistics_percentiles + + >>> import vcs, cdms2, os + >>> try: + ... os.listdir(vcs.sample_data) + >>> except: + ... vcs.download_sample_data_files() + >>> f=cdms2.open(vcs.sample_data + 'clt.nc') + >>> x=f('v') + >>> result = percentiles(x, percentiles=[25.,50.,75.,100.]) # percentiles across default axis - >>> result = percentiles(x, percentiles=percentilesoptions, axis=axisoptions) + :param x: Slab to compute statistics for + :type x: cdms2.tvariable.TransientVariable or numpy.array :param percentiles: A python list of values Default = [50.] (the 50th percentile i.e the median value) - :type percentiles: + :type percentiles: list :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n - default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. - :type axis: + default value = 0. You can pass the name of the dimension or index + (integer value 0...n) over which you want to compute the statistic. + :type axis: int or str """ cdat_info.pingPCMDIdb("cdat","genutil.statistics.percentiles") if cdms2.isVariable(x) : xatt=x.attributes @@ -1639,12 +1772,19 @@ def median(x,axis=0): :Example: - .. doctest:: + .. doctest:: statistics_median - >>> result = median(x, axis=axisoptions) + >>> import vcs, cdms2, os + >>> try: + ... os.listdir(vcs.sample_data) + >>> except: + ... vcs.download_sample_data_files() + >>> f=cdms2.open(vcs.sample_data + 'clt.nc') + >>> x=f('v') + >>> result = median(x, axis='x') - :param x: - :type x: + :param x: Slab to compute statistics for + :type x: cdms2.tvariable.TransientVariable or numpy.array :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index @@ -1664,14 +1804,24 @@ def rank(x,axis=0): :Example: - .. doctest:: + .. doctest:: statistics_rank - >>> result = median(x, axis=axisoptions) + >>> import vcs, cdms2, os + >>> try: + ... os.listdir(vcs.sample_data) + >>> except: + ... vcs.download_sample_data_files() + >>> f=cdms2.open(vcs.sample_data + 'clt.nc') + >>> x=f('v') + >>> result = median(x, axis='x') + + :param x: Slab to compute statistics for + :type x: cdms2.tvariable.TransientVariable or numpy.array :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - :type axis: + :type axis: str or int """ # preprocessing diff --git a/Lib/statusbar.py b/Lib/statusbar.py index fcea9b0..bb6dcc9 100644 --- a/Lib/statusbar.py +++ b/Lib/statusbar.py @@ -35,8 +35,6 @@ def statusbar(status,total=1.,prev=-1,title='Done',tk=None): prevj=statusbar(float(j)/nj,prev=prevj,tk=1) prevall=statusbar([float(i)/ni,float(j)/nj],prev=prevall,tk=1,title='Test') prevtxt=statusbar(float(j)/nj,prev=prevtxt,tk=None,title='Test') - - """ import sys,string chardic={ From 0c591f9c4c0c3771564a0f48e7a3d973d57254f1 Mon Sep 17 00:00:00 2001 From: embrown Date: Thu, 5 Jan 2017 11:38:13 -0800 Subject: [PATCH 5/5] This contains a lot of documentation edits to make docstrings sphinx-compatible. Most of the docstrings are in RST format, and many have :Example: sections with doctests meant to show usage examples for the code. This is just the beginning phase of updating the documentation. What needs to happen next is that someone familiar with the library and its functions (parameters, return values, etc.) needs to fill in missing param/type and return/rtype. The :Examples: need to be edited such that they would actually run if you copied them into a python console. We also need to add a sphinx configuration to the Doc folder so we can start building a webpage/pdf manual. --- Lib/ASCII.py | 27 +++-- Lib/Filler.py | 14 +-- Lib/averager.py | 28 +++--- Lib/filters.py | 12 +-- Lib/salstat.py | 246 +++++++++++++++++++++++++++++----------------- Lib/statistics.py | 4 + Lib/statusbar.py | 2 +- Lib/xmldocs.py | 19 ++++ 8 files changed, 225 insertions(+), 127 deletions(-) create mode 100644 Lib/xmldocs.py diff --git a/Lib/ASCII.py b/Lib/ASCII.py index af13bfb..36b34b3 100644 --- a/Lib/ASCII.py +++ b/Lib/ASCII.py @@ -21,6 +21,8 @@ def make_var(lap,id=None,shape=None): lap.id=id return lap + +# TODO: need an actual 'vars.txt' file for the doctests def readAscii( text_file ,header=0, ids=None, shape=None, next='------',separators=[';',',',':']): """ Reads data from an ascii file to generate a list of transient(s)/varable(s) @@ -46,8 +48,10 @@ def readAscii( text_file ,header=0, ids=None, shape=None, next='------',separato :param next: character string marking separation between variables (i.e. '------') :type next: str - :param separators: List of characters recognized as column separators (i.e. [';',',',':']) - :type separators: list + :param separators: ([';',',', ':']) List of characters recognized as column + separators. Can be represented as a list or a string. + If it is a string, separator characters must be space-delimited. + :type separators: list or str :returns: List containing transient(s) variable(s) possibly named after ids and reshaped from the 'shape' option. :rtype: list @@ -96,7 +100,8 @@ def readAscii( text_file ,header=0, ids=None, shape=None, next='------',separato return vars[0] -def read_col( text_file ,header=0, cskip=0, cskip_type='columns', axis=False, ids=None, idrow=0, separators=[';',',', ':']): +def read_col( text_file ,header=0, cskip=0, cskip_type='columns', axis=False, ids=None, idrow=0, + separators=[';',',', ':']): """ Reads column-stored data from ASCII files @@ -129,12 +134,14 @@ def read_col( text_file ,header=0, cskip=0, cskip_type='columns', axis=False, id :param ids: (None) use the values in this list as variable ids (1 per column returned) :type ids: - :param separators: ([';',',', ':']) List of character recognized as column separator - :type separators: + :param separators: ([';',',', ':']) List of characters recognized as column + separator. Can be represented as a list or a string. + If it is a string, separator characters must be space-delimited. + :type separators: list or str :returns: List containing 1 transient variable per column in the files. - Variable ids are optionaly determined by first row. - Variable axis may be the first column. + Variable ids are optionally determined by first row. + Variable axis may be the first column. :rtype: list """ @@ -144,9 +151,9 @@ def read_col( text_file ,header=0, cskip=0, cskip_type='columns', axis=False, id for s in separators: sep.append(s) - f=open( text_file ) - lst = f.readlines( ) - f.close( ) + f=open(text_file) + lst = f.readlines() + f.close() lst=lst[header:] if not isinstance(ids,(tuple,list)): ids=[ids] diff --git a/Lib/Filler.py b/Lib/Filler.py index b21c930..ee0a5dc 100644 --- a/Lib/Filler.py +++ b/Lib/Filler.py @@ -29,9 +29,11 @@ class StringConstructor: def __init__(self,template=None): """ Instantiates a StringConstructor object. - :param template: A string used by StringConstructor for keyword replacement. - template is a string of form: 'my string here with %(keywords) in it'. - There can be an unlimited number of keywords, delimited by %( on the left and ) on the right. + :param template: A string used by StringConstructor for keyword + replacement. template is a string of form: + 'my string here with %(keywords) in it'. + There can be an unlimited number of keywords, delimited by %( on + the left and ) on the right. """ cdat_info.pingPCMDIdb("cdat","genutil.StringConstructor") self.template=template @@ -78,12 +80,12 @@ def construct(self,template=None,**kw): '/pcmdi/amip/mo/tas/ugamp-98a/tas_ugamp-98a.xml' :param template: A string used by StringConstructor for keyword replacement. - template is a string of form: 'my string here with %(keywords) in it'. - There can be an unlimited number of keywords, delimited by %( on the left and ) on the right. + template is a string of form: 'my string here with %(keywords) in it'. + There can be an unlimited number of keywords, delimited by %( on the left and ) on the right. :type template: str :param kw: Comma-delimited list of keyword to string value mappings, i.e.: - keyword1='kwd1 string',keyword2='kwd2 string', ... + keyword1='kwd1 string',keyword2='kwd2 string', ... :type kw: list """ if template is None: diff --git a/Lib/averager.py b/Lib/averager.py index 8afede7..363214d 100644 --- a/Lib/averager.py +++ b/Lib/averager.py @@ -779,25 +779,27 @@ def averager(V, axis=None, weights=None, action='average', returned=0, weight=No :type weights: str :param action: One of 'average' or 'sum'. Specifies whether to return the weighted average or weighted sum of data. - Default: 'average' + Default: 'average' :type action: str :param returned: Integer flag indicating whether or not the weighted average should be returned. - * 0 implies sum of weights are not returned after averaging operation. - * 1 implies the sum of weights after the average operation is returned. + *0:* implies sum of weights are not returned after averaging operation. + *1:* implies the sum of weights after the average operation is returned. :type returned: int :param combinewts: Integer flag indicating whether or not weights passed in for axes should be combined. - * 0 implies weights passed for individual axes are not combined into one - weight array for the full variable V before performing operation. - * 1 implies weights passed for individual axes are combined into one - weight array for the full variable before performing average or sum - operations. One-dimensional weight arrays or key words of 'weighted' or - 'unweighted' must be passed for the axes over which the operation is - to be performed. Additionally, weights for axes that are not being - averaged or summed may also bepassed in the order in which they appear. - If the weights for the other axes are not passed, they are assumed to - be equally weighted. + + *0:* implies weights passed for individual axes are not combined into one + weight array for the full variable V before performing operation. + + *1:* implies weights passed for individual axes are combined into one + weight array for the full variable before performing average or sum + operations. One-dimensional weight arrays or key words of 'weighted' or + 'unweighted' must be passed for the axes over which the operation is + to be performed. Additionally, weights for axes that are not being + averaged or summed may also bepassed in the order in which they appear. + If the weights for the other axes are not passed, they are assumed to + be equally weighted. :Examples: diff --git a/Lib/filters.py b/Lib/filters.py index b09d485..f8d7f55 100644 --- a/Lib/filters.py +++ b/Lib/filters.py @@ -16,8 +16,8 @@ def custom1D(x,filter,axis=0): :type filter: array :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n - default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. + default value = 0. You can pass the name of the dimension or index + (integer value 0...n) over which you want to compute the statistic. :type axis: str or int """ cdat_info.pingPCMDIdb("cdat","genutil.filters.custom1D") @@ -90,8 +90,8 @@ def smooth121(x,axis=0): :type x: cdms.tvariable.TransientVariable :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n - default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. + default value = 0. You can pass the name of the dimension or index + (integer value 0...n) over which you want to compute the statistic. :type axis: str or int """ cdat_info.pingPCMDIdb("cdat","genutil.filters.smooth121") @@ -119,8 +119,8 @@ def runningaverage(x,N,axis=0): :type N: int :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n - default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. + default value = 0. You can pass the name of the dimension or index + (integer value 0...n) over which you want to compute the statistic. :type axis: str or int """ filter=numpy.ma.ones((N,),dtype='f') diff --git a/Lib/salstat.py b/Lib/salstat.py index 99cb602..a83949a 100644 --- a/Lib/salstat.py +++ b/Lib/salstat.py @@ -128,9 +128,9 @@ def rankdata(x,axis=0): >>> rankdata(array, axis=axisoptions) :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n - default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. - even: 'xy': to do over 2 dimensions at once + default value = 0. You can pass the name of the dimension or index + (integer value 0...n) over which you want to compute the statistic. + even: 'xy': to do over 2 dimensions at once :type axis: str or int :param x: @@ -202,9 +202,9 @@ def tiecorrect(x,axis=0): :type x: :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n - default value = 0. You can pass the name of the dimension or index - (integer value 0...n) over which you want to compute the statistic. - even: 'xy': to do over 2 dimensions at once + default value = 0. You can pass the name of the dimension or index + (integer value 0...n) over which you want to compute the statistic. + even: 'xy': to do over 2 dimensions at once :type axis: """ x = _fixScalar(x) @@ -354,6 +354,7 @@ def inversechi(prob, df): .. doctest:: genutil_salstat_inversechi >>> invchi = inversechi(prob,df,axis=axisoptions) + :param prob: :type prob: @@ -401,6 +402,7 @@ def erfcc(x): .. doctest:: genutil_salstat_erfcc >>> err = erfcc(x) + :param x: :type x: @@ -755,11 +757,16 @@ def betacf(a,b,x,ITMAX=200,EPS=3.0E-7): :Example: - .. doctest:: + .. doctest:: salstat_betacf + + >>> beta = betacf(a,b,x,ITMAX=200,EPS=3.0E-7) + + :param ITMAX: Maximum number of iterations + :type ITMAX: int + + :param EPS: Epsilon number + :type EPS: float - beta = betacf(a,b,x,ITMAX=200,EPS=3.0E-7) - ITMAX: Maximum number of iteration - EPS: Epsilon number """ a = _fixScalar(a) b = _fixScalar(b) @@ -807,9 +814,14 @@ def gamma(x): :Example: - .. doctest:: + .. doctest:: salstat_gamma _gammaln(xx) + + :param x: + :type x: + + :returns: """ x = _fixScalar(x) isvar=0 @@ -867,8 +879,12 @@ def betai(a,b,x,ITMAX=200,EPS=3.0E-7): using the betacf function. (Adapted from: MAal Recipies in C.) Usage: beta = betai(a,b,x,ITMAX=200,EPS=3.0E-7) - ITMAX: Maximum number of iteration for betacf - EPS: Epsilon number + + :param ITMAX: Maximum number of iterations + :type ITMAX: int + + :param EPS: Epsilon number + :type EPS: float """ a = _fixScalar(a) b = _fixScalar(b) @@ -908,11 +924,11 @@ def sumsquares(x,axis=0): """Return the sum of the squares Usage: sq=sumsquare(data,axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int """ x = _fixScalar(x) if cdms2.isVariable(x) : xatt=x.attributes @@ -938,11 +954,12 @@ def Range(x,axis=0): """Returns the range of the data Usage: rg=Range(data,axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int """ x = _fixScalar(x) if cdms2.isVariable(x) : xatt=x.attributes @@ -961,11 +978,12 @@ def harmonicmean(x,axis=0): """Returns the harmonicmean of the data Usage: h=harmonicmean(data,axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int """ x = _fixScalar(x) if cdms2.isVariable(x) : xatt=x.attributes @@ -1005,11 +1023,12 @@ def median(x,axis=0): Not to use with missing values Usage: med=_median(data,axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int """ x = _fixScalar(x) if cdms2.isVariable(x) : xatt=x.attributes @@ -1035,11 +1054,12 @@ def medianranks(x,axis=0): """ Return the ranks of the median Usage: medrk=medianranks(data,axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int """ x = _fixScalar(x) if cdms2.isVariable(x) : xatt=x.attributes @@ -1065,11 +1085,12 @@ def mad(x,axis=0): """ return the sum of the deviation from the median Usage: md=_mad(data,axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int """ x = _fixScalar(x) if cdms2.isVariable(x) : xatt=x.attributes @@ -1103,11 +1124,12 @@ def numberuniques(x,axis=0): """Return the number of unique values Usage: uniques=numberuniques(data,axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int """ x = _fixScalar(x) if cdms2.isVariable(x) : xatt=x.attributes @@ -1133,11 +1155,12 @@ def center(x,axis=0): """Returns the deviation from the mean Usage: centered=center(data) # returns deviation from mean - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int """ x = _fixScalar(x) if cdms2.isVariable(x) : xatt=x.attributes @@ -1163,11 +1186,12 @@ def ssdevs(x,axis=0): """Return the sum of the square of the deviation from mean Usage: ss=_ssdevs(data,axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int """ x = _fixScalar(x) if cdms2.isVariable(x) : xatt=x.attributes @@ -1222,11 +1246,12 @@ def unbiasedvariance(x,axis=0): """Return the variance (Ssq/(N-1)) Usage: svar=unbiasedvariance(x,axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int """ x = _fixScalar(x) if cdms2.isVariable(x) : xatt=x.attributes @@ -1252,11 +1277,12 @@ def variance(x,axis=0): """Return the variance of data Usage: V=variance(data,axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int """ x = _fixScalar(x) if cdms2.isVariable(x) : xatt=x.attributes @@ -1282,11 +1308,12 @@ def standarddeviation(x,axis=0): """Returns stadard deviation of data Usage: std=standarddeviation(data,axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int """ x = _fixScalar(x) if cdms2.isVariable(x) : xatt=x.attributes @@ -1313,11 +1340,12 @@ def coefficentvariance(x,axis=0): """Returns the coefficents variance of data Usage: coefvar=coefficentvariance(data,axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int """ x = _fixScalar(x) if cdms2.isVariable(x) : xatt=x.attributes @@ -1345,11 +1373,12 @@ def skewness(x,axis=0): """Return the skewness of data Usage: skew=skewness(data, axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int """ x = _fixScalar(x) if cdms2.isVariable(x) : xatt=x.attributes @@ -1377,11 +1406,12 @@ def kurtosis(x,axis=0): """Return kurtosis value from dataset Usage: k=kurtosis(data, axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int """ x = _fixScalar(x) if cdms2.isVariable(x) : xatt=x.attributes @@ -1406,11 +1436,12 @@ def standarderror(x,axis=0): """Returns the standard error from dataset Usage: stderr=standarderror(data,axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int """ x = _fixScalar(x) if cdms2.isVariable(x) : xatt=x.attributes @@ -1447,11 +1478,12 @@ def mode(x,axis=0): """returns the mode of the data Usage: md=mode(data, axis=axisoptions) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int """ x = _fixScalar(x) if cdms2.isVariable(x) : xatt=x.attributes @@ -1487,13 +1519,16 @@ def OneSampleTTest(x,y,axis=0,df=1): .. doctest:: t, prob [,df] = OneSampleTTest(data, usermean, axis=axisoptions, df=1) - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int - df=1 : If set to 1 then the degrees of freedom are returned + :param df: An integer flag indicating whether to return degrees of freedom. + If 1, degrees of freedom are returned. If set to 0, they are not. + :type df: int """ x = _fixScalar(x) @@ -1542,11 +1577,12 @@ def OneSampleSignTest(x,y,axis=0): Usage: nplus, nminus, z, prob = OneSampleSignTest(data, usermean, axis=axisoptions) Returns: nplus, nminus, z, prob. - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int """ x = _fixScalar(x) y = _fixScalar(y) @@ -1584,11 +1620,12 @@ def ChiSquareVariance(x,y,axis=0, df=1): Usage: chisquare, prob, [df] = ChiSquareVariance(data, usermean, axis=axisoptions, df=1) Returns: chisquare, prob, [df] = - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int """ x = _fixScalar(x) y = _fixScalar(y) @@ -1640,13 +1677,16 @@ def TTestUnpaired(x,y,axis=0,df=1): t, prob, [df] = TTestUnpaired(data1, data2,axis=axisoptions, df=1) Returns: t, df, prob - Options: - axisoptions 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. - you can also pass 'xy' to work on both axes at once + You can also pass 'xy': to do over 2 dimensions at once + :type axis: str or int - df =0: if set to 1 returns degrees of freedom + :param df: An integer flag indicating whether to return degrees of freedom. + If 1, degrees of freedom are returned. If set to 0, they are not. + :type df: int """ x = _fixScalar(x) y = _fixScalar(y) @@ -1700,7 +1740,9 @@ def TTestPaired(x,y,axis=0,df=1): (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once - df =0: if set to 1 returns degrees of freedom + :param df: An integer flag indicating whether to return degrees of freedom. + If 1, degrees of freedom are returned. If set to 0, they are not. + :type df: int """ x = _fixScalar(x) y = _fixScalar(y) @@ -1765,8 +1807,9 @@ def PearsonsCorrelation(x,y,axis=0,df=1): :param y: :type y: - :param df: If set to 1, returns degrees of freedom. Defaults to 0. - :type: int + :param df: An integer flag indicating whether to return degrees of freedom. + If 1, degrees of freedom are returned. If set to 0, they are not. + :type df: int """ x = _fixScalar(x) y = _fixScalar(y) @@ -1808,17 +1851,22 @@ def FTest(data1, data2, uservar, axis=0, df=1): """ This method performs a F test for variance ratio and needs a user hypothesised variance to be supplied. + :Example: .. doctest:: f, prob [,df1, df2] = FTest(data1, data2, uservar, axis=axisoptions, df=1) - :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once + :type axis: str or int - df =0: if set to 1 returns degrees of freedom + :param df: An integer flag indicating whether to return degrees of freedom. + If 1, degrees of freedom are returned. If set to 0, they are not. + :type df: int """ data1 = _fixScalar(data2) data2 = _fixScalar(data2) @@ -1873,10 +1921,12 @@ def TwoSampleSignTest(x,y,axis=0): .. doctest:: nplus, nminus, ntotal, z, prob = TwoSampleSignTest(data1, data2) - :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once + :type axis: str or int """ x = _fixScalar(x) @@ -1943,10 +1993,12 @@ def KendallsTau(x,y,axis=0): .. doctest:: tau, z, prob = KendallsTau(data1, data2) - :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once + :type axis: str or int """ x = _fixScalar(x) @@ -2018,10 +2070,12 @@ def KolmogorovSmirnov(x,y,axis=0): .. doctest:: ks, prob = KolmogorovSmirnov(data1, data2) - :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once + :type axis: str or int """ x = _fixScalar(x) @@ -2064,10 +2118,12 @@ def SpearmansCorrelation(x,y,axis=0,df=1): .. doctest:: rho, t, df, prob = SpearmansCorrelation(data1, data2, axis=0, df=1) - :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n default value = 0. You can pass the name of the dimension or index (integer value 0...n) over which you want to compute the statistic. you can also pass 'xy' to work on both axes at once + :type axis: str or int df=1 : If set to 1 returns the degrees of freedom """ @@ -2529,7 +2585,9 @@ def anovaWithin( *inlist,**kw): you can also pass 'xy' to work on both axes at once df=1 : if 1 then degrees of freedom are retuned - WARNING: axis and df MUST be passed as keyword, as all arguments are considered as arrays + .. warning:: + + axis and df MUST be passed as keyword, as all arguments are considered as arrays """ if len(inlist)<2: raise 'Error must have at least 2 arrays!' @@ -2619,7 +2677,9 @@ def anovaBetween(*inlist,**kw): you can also pass 'xy' to work on both axes at once df=1 : if 1 then degrees of freedom are retuned - WARNING: axis and df MUST be passed as keyword, as all arguments are considered as arrays + .. warning:: + + axis and df MUST be passed as keyword, as all arguments are considered as arrays """ if len(inlist)<2: raise 'Error must have at least 2 arrays!' @@ -2708,7 +2768,9 @@ def KruskalWallisH(*inlist,**kw): you can also pass 'xy' to work on both axes at once df=1 : if 1 then degrees of freedom are retuned - WARNING: axis and df MUST be passed as keyword, as all arguments are considered as arrays + .. warning:: + + axis and df MUST be passed as keyword, as all arguments are considered as arrays """ if len(inlist)<2: raise 'Error must have at least 2 arrays!' @@ -2783,7 +2845,9 @@ def FriedmanChiSquare( *inlist, **kw): you can also pass 'xy' to work on both axes at once df=1 : if 1 then degrees of freedom are retuned - WARNING: axis and df MUST be passed as keyword, as all arguments are considered as arrays + .. warning:: + + axis and df MUST be passed as keyword, as all arguments are considered as arrays """ if len(inlist)<2: raise 'Error must have at least 2 arrays!' diff --git a/Lib/statistics.py b/Lib/statistics.py index 84728b6..3130cfc 100644 --- a/Lib/statistics.py +++ b/Lib/statistics.py @@ -762,6 +762,7 @@ def variance(x,weights=None,axis=0,centered=1,biased=1,max_pct_missing=100.): Weighted covariance is inherently biased. Passing a value for weights but specifying an unbiased variance will cause an error + :type weights: list :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n @@ -824,6 +825,7 @@ def std(x,weights=None,axis=0,centered=1,biased=1,max_pct_missing=100.): Use of weights is inherently biased. Passing a value for weights but specifying a non-biased calculation will cause an error. + :type weights: list :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n @@ -883,6 +885,7 @@ def correlation(x,y,weights=None,axis=0,centered=1,biased=1,max_pct_missing=100. Use of weights is inherently biased. Passing a value for weights but specifying a non-biased calculation will cause an error. + :type weights: list :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n @@ -941,6 +944,7 @@ def rms(x,y,weights=None,axis=0,centered=0,biased=1,max_pct_missing=100.): Use of weights is inherently biased. Passing a value for weights but specifying a non-biased calculation will cause an error. + :type weights: list :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n diff --git a/Lib/statusbar.py b/Lib/statusbar.py index bb6dcc9..ad813f2 100644 --- a/Lib/statusbar.py +++ b/Lib/statusbar.py @@ -95,7 +95,7 @@ def statusbar(status,total=1.,prev=-1,title='Done',tk=None): wsave=10. if prev==[0,0] : master=Tkinter.Toplevel() - #Pmw.Blt._checkForBlt(master) + # Pmw.Blt._checkForBlt(master) master.geometry('200x'+sheigth) master.resizable(0,0) master.update() diff --git a/Lib/xmldocs.py b/Lib/xmldocs.py new file mode 100644 index 0000000..aad3aad --- /dev/null +++ b/Lib/xmldocs.py @@ -0,0 +1,19 @@ +"""This file contains docstring snippets that are used repetetively in documenting genutil functions. + Use it as a repository for any pieces of documentation that show up many times, and would be more convenient to + edit in one place and plug in everywhere. +""" + +# Parameters +axis = """ + :param axis: 'x' | 'y' | 'z' | 't' | '(dimension_name)' | 0 | 1 ... | n + default value = 0. You can pass the name of the dimension or index + (integer value 0...n) over which you want to compute the statistic. + you can also pass 'xy' to work on both axes at once + :type axis: str or int + """ + +df = """ + :param df: An integer flag indicating whether to return degrees of freedom. + If 1, degrees of freedom are returned. If set to 0, they are not. + :type df: int + """ \ No newline at end of file