From 828bc589b2dc6faf1b402a10202418f068b7fc59 Mon Sep 17 00:00:00 2001 From: switham Date: Thu, 9 Oct 2014 23:04:32 -0400 Subject: [PATCH 1/3] Document auto-init behavior of colors.Normalize and cm.ScalarMappable. modified: colors.py norm = Normalize() # No parameters, the defaults. aa = norm(a) # a is normalized according to a's min and max. bb = norm(b) # b is normalized according to *a's min and max*. That is, if vmin and vmax aren't set by the time the first __call__ happens, they are initialized as a side-effect, based on the data in the first call. This may well be the intended behavior, but the existing docstring suggested autoscaling to whatever data comes through. Side-effects should be documented so they sound like side-effects. Documented this in the __init__ docstring (which is where the __call__ behavior was documented), and added a docstring to the __call__ method and also mentioned this side-effect behavior there. modified: cm.py in class ScalarMappable def __init__(norm=None, ...) Added to the docstring that the default is really a new Normalize initialized with no parameters, which auto-initializes scaling based on the first input data. --- lib/matplotlib/cm.py | 3 +++ lib/matplotlib/colors.py | 19 +++++++++++++++---- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/lib/matplotlib/cm.py b/lib/matplotlib/cm.py index cc9cc42e3317..0d88631f25dd 100644 --- a/lib/matplotlib/cm.py +++ b/lib/matplotlib/cm.py @@ -178,6 +178,9 @@ def __init__(self, norm=None, cmap=None): norm : :class:`matplotlib.colors.Normalize` instance The normalizing object which scales data, typically into the interval ``[0, 1]``. + If not given or *None*, norm defaults to a *colors.Normalize* + object which initializes its scaling based on the first + data processed. cmap : str or :class:`~matplotlib.colors.Colormap` instance The colormap used to map normalized data values to RGBA colors. diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py index 9ce0fddcb6f6..0289ae5566e1 100644 --- a/lib/matplotlib/colors.py +++ b/lib/matplotlib/colors.py @@ -851,10 +851,12 @@ class Normalize(object): """ def __init__(self, vmin=None, vmax=None, clip=False): """ - If *vmin* or *vmax* is not given, they are taken from the input's - minimum and maximum value respectively. If *clip* is *True* and - the given value falls outside the range, the returned value - will be 0 or 1, whichever is closer. Returns 0 if:: + If *vmin* or *vmax* is not given, they are initialized from the + minimum and maximum value respectively of the first input + processed. That is, *__call__(A)* calls *autoscale_None(A)*. + If *clip* is *True* and the given value falls outside the range, + the returned value will be 0 or 1, whichever is closer. + Returns 0 if:: vmin==vmax @@ -902,6 +904,15 @@ def process_value(value): return result, is_scalar def __call__(self, value, clip=None): + """ + ``norm.__call__(value) <==> norm(value)`` + + Normalize data in the ``[vmin, vmax]`` interval into the + ``[0.0, 1.0]`` interval. *clip* defaults to *self.clip* + (which defaults to *False*). If not already initialized, + *vmin* and *vmax* are initialized using + *autoscale_None(value)*. + """ if clip is None: clip = self.clip From 038507120acbafa5bd96adcf555047f81d90c7ae Mon Sep 17 00:00:00 2001 From: switham Date: Wed, 15 Oct 2014 00:46:52 -0400 Subject: [PATCH 2/3] Tweaks to colors.Normalize and cm.ScalarMappable docstrings. modified: cm.py in ScalarMappable.__init__ "If not given or *None*," ==> "If *None*," modified: colors.py in Normalize.__call__ Removed this: "``norm.__call__(value) <==> norm(value)``" Mentioned that __call__ takes *value* and returns the normalized data. --- lib/matplotlib/cm.py | 6 ++---- lib/matplotlib/colors.py | 10 ++++------ 2 files changed, 6 insertions(+), 10 deletions(-) diff --git a/lib/matplotlib/cm.py b/lib/matplotlib/cm.py index 0d88631f25dd..d6169520cc83 100644 --- a/lib/matplotlib/cm.py +++ b/lib/matplotlib/cm.py @@ -178,12 +178,10 @@ def __init__(self, norm=None, cmap=None): norm : :class:`matplotlib.colors.Normalize` instance The normalizing object which scales data, typically into the interval ``[0, 1]``. - If not given or *None*, norm defaults to a *colors.Normalize* - object which initializes its scaling based on the first - data processed. + If *None*, *norm* defaults to a *colors.Normalize* object which + initializes its scaling based on the first data processed. cmap : str or :class:`~matplotlib.colors.Colormap` instance The colormap used to map normalized data values to RGBA colors. - """ self.callbacksSM = cbook.CallbackRegistry() diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py index 0289ae5566e1..59be1b578aec 100644 --- a/lib/matplotlib/colors.py +++ b/lib/matplotlib/colors.py @@ -905,12 +905,10 @@ def process_value(value): def __call__(self, value, clip=None): """ - ``norm.__call__(value) <==> norm(value)`` - - Normalize data in the ``[vmin, vmax]`` interval into the - ``[0.0, 1.0]`` interval. *clip* defaults to *self.clip* - (which defaults to *False*). If not already initialized, - *vmin* and *vmax* are initialized using + Normalize *value* data in the ``[vmin, vmax]`` interval into + the ``[0.0, 1.0]`` interval and return it. *clip* defaults + to *self.clip* (which defaults to *False*). If not already + initialized, *vmin* and *vmax* are initialized using *autoscale_None(value)*. """ if clip is None: From 1f07ab1b68758f1bdabddf19cc6bc0863be87482 Mon Sep 17 00:00:00 2001 From: switham Date: Wed, 15 Oct 2014 14:32:55 -0400 Subject: [PATCH 3/3] rm trailing whitespace added in 828bc58 or 0385071 --- lib/matplotlib/colors.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py index 59be1b578aec..bbc79043bccd 100644 --- a/lib/matplotlib/colors.py +++ b/lib/matplotlib/colors.py @@ -851,11 +851,11 @@ class Normalize(object): """ def __init__(self, vmin=None, vmax=None, clip=False): """ - If *vmin* or *vmax* is not given, they are initialized from the + If *vmin* or *vmax* is not given, they are initialized from the minimum and maximum value respectively of the first input processed. That is, *__call__(A)* calls *autoscale_None(A)*. If *clip* is *True* and the given value falls outside the range, - the returned value will be 0 or 1, whichever is closer. + the returned value will be 0 or 1, whichever is closer. Returns 0 if:: vmin==vmax @@ -905,10 +905,10 @@ def process_value(value): def __call__(self, value, clip=None): """ - Normalize *value* data in the ``[vmin, vmax]`` interval into + Normalize *value* data in the ``[vmin, vmax]`` interval into the ``[0.0, 1.0]`` interval and return it. *clip* defaults to *self.clip* (which defaults to *False*). If not already - initialized, *vmin* and *vmax* are initialized using + initialized, *vmin* and *vmax* are initialized using *autoscale_None(value)*. """ if clip is None: