docstrings: use standard spelling and capitalization of MATLAB

efiring · efiring · commit fa0b68abe741 · 2010-06-26T19:04:53.000Z
svn path=/trunk/matplotlib/; revision=8470
diff --git a/doc/users/intro.rst b/doc/users/intro.rst
@@ -3,12 +3,15 @@ Introduction
 
 matplotlib is a library for making 2D plots of arrays in `Python
 <http://www.python.org>`_.  Although it has its origins in emulating
-the MATLAB graphics commands, it is
+the MATLAB |reg| [*]_ graphics commands, it is
 independent of MATLAB, and can be used in a Pythonic, object oriented
 way.  Although matplotlib is written primarily in pure Python, it
 makes heavy use of `NumPy <http://www.numpy.org>`_ and other extension
 code to provide good performance even for large arrays.
 
+.. |reg| unicode:: 0xAE
+   :ltrim:
+
 matplotlib is designed with the philosophy that you should be able to
 create simple plots with just a few commands, or just one!  If you
 want to see a histogram of your data, you shouldn't need to
@@ -87,3 +90,6 @@ from the Python shell in Tkinter on Windows™. My primary use is to
 embed matplotlib in a Gtk+ EEG application that runs on Windows, Linux
 and Macintosh OS X.
 
+.. [*] MATLAB is a registered trademark of The MathWorks, Inc.
+
+
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -1,19 +1,25 @@
 """
 This is an object-orient plotting library.
 
-A procedural interface is provided by the companion pylab module,
+A procedural interface is provided by the companion pyplot module,
 which may be imported directly, e.g::
 
+    from pyplot import *
+
+To include numpy functions, use::
+
     from pylab import *
 
 or using ipython::
 
     ipython -pylab
 
 For the most part, direct use of the object-oriented library is
-encouraged when programming rather than working interactively.  The
-exceptions are the pylab commands :func:`~matplotlib.pyplot.figure`,
+encouraged when programming; pyplot is primarily for working
+interactively.  The
+exceptions are the pyplot commands :func:`~matplotlib.pyplot.figure`,
 :func:`~matplotlib.pyplot.subplot`,
+:func:`~matplotlib.pyplot.subplots`,
 :func:`~matplotlib.backends.backend_qt4agg.show`, and
 :func:`~pyplot.savefig`, which can greatly simplify scripting.
 
@@ -86,6 +92,10 @@
 
 matplotlib is written by John D. Hunter (jdh2358 at gmail.com) and a
 host of others.
+
+Occasionally the internal documentation (python docstrings) will refer
+to MATLAB&reg;, a registered trademark of The MathWorks, Inc.
+
 """
 from __future__ import generators
 
@@ -897,7 +907,7 @@ def tk_window_focus():
 
 # Now allow command line to override
 
-# Allow command line access to the backend with -d (matlab compatible
+# Allow command line access to the backend with -d (MATLAB compatible
 # flag)
 
 for s in sys.argv[1:]:
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -1159,10 +1159,10 @@ def setp(obj, *args, **kwargs):
       >>> lines = plot(x, y1, x, y2)
       >>> setp(lines, linewidth=2, color='r')
 
-    :func:`setp` works with the matlab style string/value pairs or
+    :func:`setp` works with the MATLAB style string/value pairs or
     with python kwargs.  For example, the following are equivalent::
 
-      >>> setp(lines, 'linewidth', 2, 'color', r')  # matlab style
+      >>> setp(lines, 'linewidth', 2, 'color', r')  # MATLAB style
 
       >>> setp(lines, linewidth=2, color='r')       # python style
     """
diff --git a/lib/matplotlib/axes.py b/lib/matplotlib/axes.py
@@ -50,7 +50,7 @@ def _string_to_bool(s):
 
 def _process_plot_format(fmt):
     """
-    Process a matlab(TM) style color/line style format string.  Return a
+    Process a MATLAB style color/line style format string.  Return a
     (*linestyle*, *color*) tuple as a result of the processing.  Default
     values are ('-', 'b').  Example format strings include:
 
@@ -1963,7 +1963,7 @@ def grid(self, b=None, which='major', **kwargs):
 
           grid(self, b=None, which='major', **kwargs)
 
-        Set the axes grids on or off; *b* is a boolean.  (For Matlab
+        Set the axes grids on or off; *b* is a boolean.  (For MATLAB
         compatibility, *b* may also be a string, 'on' or 'off'.)
 
         If *b* is *None* and ``len(kwargs)==0``, toggle the grid state.  If
@@ -5187,7 +5187,7 @@ def boxplot(self, x, notch=0, sym='b+', vert=1, whis=1.5,
 
         - *vert* = 1 (default) makes the boxes vertical.
         - *vert* = 0 makes horizontal boxes.  This seems goofy, but
-          that's how Matlab did it.
+          that's how MATLAB did it.
 
         *whis* (default 1.5) defines the length of the whiskers as
         a function of the inner quartile range.  They extend to the
@@ -6744,7 +6744,7 @@ def pcolor(self, *args, **kwargs):
           *shading*: [ 'flat' | 'faceted' ]
             If 'faceted', a black grid is drawn around each rectangle; if
             'flat', edges are not drawn. Default is 'flat', contrary to
-            Matlab.
+            MATLAB.
 
             This kwarg is deprecated; please use 'edgecolors' instead:
               * shading='flat' -- edgecolors='none'
@@ -6765,7 +6765,7 @@ def pcolor(self, *args, **kwargs):
 
         .. _axes-pcolor-grid-orientation:
 
-        The grid orientation follows the Matlab(TM) convention: an
+        The grid orientation follows the MATLAB convention: an
         array *C* with shape (*nrows*, *ncolumns*) is plotted with
         the column number as *X* and the row number as *Y*, increasing
         up; hence it is plotted the way the array would be printed,
@@ -6800,7 +6800,7 @@ def pcolor(self, *args, **kwargs):
 
           pcolor(C.T)
 
-        Matlab :func:`pcolor` always discards the last row and column
+        MATLAB :func:`pcolor` always discards the last row and column
         of *C*, but matplotlib displays the last row and column if *X* and
         *Y* are not specified, or if *X* and *Y* have one more row and
         column than *C*.
@@ -6942,7 +6942,7 @@ def pcolormesh(self, *args, **kwargs):
           *shading*: [ 'flat' | 'faceted' | 'gouraud' ]
             If 'faceted', a black grid is drawn around each rectangle; if
             'flat', edges are not drawn. Default is 'flat', contrary to
-            Matlab(TM).
+            MATLAB.
 
             This kwarg is deprecated; please use 'edgecolors' instead:
               * shading='flat' -- edgecolors='None'
@@ -8219,14 +8219,14 @@ def __init__(self, fig, *args, **kwargs):
                     raise ValueError('Argument to subplot must be a 3 digits long')
                 rows, cols, num = map(int, s)
                 self._subplotspec = GridSpec(rows, cols)[num-1]
-                # num - 1 for converting from matlab to python indexing
+                # num - 1 for converting from MATLAB to python indexing
         elif len(args)==3:
             rows, cols, num = args
             if isinstance(num, tuple) and len(num) == 2:
                 self._subplotspec = GridSpec(rows, cols)[num[0]-1:num[1]]
             else:
                 self._subplotspec = GridSpec(rows, cols)[num-1]
-                # num - 1 for converting from matlab to python indexing
+                # num - 1 for converting from MATLAB to python indexing
         else:
             raise ValueError(  'Illegal argument to subplot')
 
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -702,7 +702,7 @@ def get_linewidth(self):
     def get_rgb(self):
         """
         returns a tuple of three floats from 0-1.  color can be a
-        matlab format string, a html hex color string, or a rgb tuple
+        MATLAB format string, a html hex color string, or a rgb tuple
         """
         return self._rgb
 
@@ -781,7 +781,7 @@ def set_dashes(self, dash_offset, dash_list):
 
     def set_foreground(self, fg, isRGB=False):
         """
-        Set the foreground color.  fg can be a matlab format string, a
+        Set the foreground color.  fg can be a MATLAB format string, a
         html hex color string, an rgb unit tuple, or a float between 0
         and 1.  In the latter case, grayscale is used.
 
@@ -2072,7 +2072,7 @@ def stop_event_loop_default(self):
 
 class FigureManagerBase:
     """
-    Helper class for matlab mode, wraps everything up into a neat bundle
+    Helper class for pyplot mode, wraps everything up into a neat bundle
 
     Public attibutes:
 
diff --git a/lib/matplotlib/blocking_input.py b/lib/matplotlib/blocking_input.py
@@ -194,7 +194,7 @@ def mouse_event_stop( self, event ):
         BlockingInput.pop(self,-1)
 
         # This will exit even if not in infinite mode.  This is
-        # consistent with matlab and sometimes quite useful, but will
+        # consistent with MATLAB and sometimes quite useful, but will
         # require the user to test how many points were actually
         # returned before using data.
         self.fig.canvas.stop_event_loop()
diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py
@@ -1234,8 +1234,8 @@ def _initialize_x_y(self, z):
         filled contours, respectively.  Except as noted, function
         signatures and return values are the same for both versions.
 
-        :func:`~matplotlib.pyplot.contourf` differs from the Matlab
-        (TM) version in that it does not draw the polygon edges.
+        :func:`~matplotlib.pyplot.contourf` differs from the MATLAB
+        version in that it does not draw the polygon edges.
         To draw edges, add line contours with
         calls to :func:`~matplotlib.pyplot.contour`.
 
diff --git a/lib/matplotlib/mlab.py b/lib/matplotlib/mlab.py
@@ -1,9 +1,9 @@
 """
 
-Numerical python functions written for compatability with matlab(TM)
+Numerical python functions written for compatability with MATLAB
 commands with the same names.
 
-Matlab(TM) compatible functions
+MATLAB compatible functions
 -------------------------------
 
 :func:`cohere`
@@ -41,10 +41,10 @@
 Miscellaneous functions
 -------------------------
 
-Functions that don't exist in matlab(TM), but are useful anyway:
+Functions that don't exist in MATLAB, but are useful anyway:
 
 :meth:`cohere_pairs`
-    Coherence over all pairs.  This is not a matlab function, but we
+    Coherence over all pairs.  This is not a MATLAB function, but we
     compute coherence a lot in my lab, and we compute it for a lot of
     pairs.  This function is optimized to do this efficiently by
     caching the direct FFTs.
@@ -245,7 +245,7 @@ def _spectral_helper(x, y, NFFT=256, Fs=2, detrend=detrend_none,
         raise ValueError("sides must be one of: 'default', 'onesided', or "
             "'twosided'")
 
-    # Matlab divides by the sampling frequency so that density function
+    # MATLAB divides by the sampling frequency so that density function
     # has units of dB/Hz and can be integrated by the plotted frequency
     # values. Perform the same scaling here.
     if scale_by_freq:
@@ -277,18 +277,18 @@ def _spectral_helper(x, y, NFFT=256, Fs=2, detrend=detrend_none,
         Pxy[:,i] = np.conjugate(fx[:numFreqs]) * fy[:numFreqs]
 
     # Scale the spectrum by the norm of the window to compensate for
-    # windowing loss; see Bendat & Piersol Sec 11.5.2. 
+    # windowing loss; see Bendat & Piersol Sec 11.5.2.
     Pxy *= 1 / (np.abs(windowVals)**2).sum()
 
     # Also include scaling factors for one-sided densities and dividing by the
     # sampling frequency, if desired. Scale everything, except the DC component
-    # and the NFFT/2 component:    
+    # and the NFFT/2 component:
     Pxy[1:-1] *= scaling_factor
 
-    #But do scale those components by Fs, if required    
+    #But do scale those components by Fs, if required
     if scale_by_freq:
-        Pxy[[0,-1]] /= Fs 
-    
+        Pxy[[0,-1]] /= Fs
+
     t = 1./Fs * (ind + NFFT / 2.)
     freqs = float(Fs) / pad_to * np.arange(numFreqs)
 
@@ -315,7 +315,7 @@ def _spectral_helper(x, y, NFFT=256, Fs=2, detrend=detrend_none,
       *detrend*: callable
           The function applied to each segment before fft-ing,
           designed to remove the mean or linear trend.  Unlike in
-          matlab, where the *detrend* parameter is a vector, in
+          MATLAB, where the *detrend* parameter is a vector, in
           matplotlib is it a function.  The :mod:`~matplotlib.pylab`
           module defines :func:`~matplotlib.pylab.detrend_none`,
           :func:`~matplotlib.pylab.detrend_mean`, and
@@ -356,7 +356,7 @@ def _spectral_helper(x, y, NFFT=256, Fs=2, detrend=detrend_none,
           Specifies whether the resulting density values should be scaled
           by the scaling frequency, which gives density in units of Hz^-1.
           This allows for integration over the returned frequency values.
-          The default is True for MatLab compatibility.
+          The default is True for MATLAB compatibility.
 """))
 
 @docstring.dedent_interpd
@@ -785,7 +785,7 @@ def prepca(P, frac=0):
       - *fracVar* : the fraction of the variance accounted for by each
          component returned
 
-    A similar function of the same name was in the Matlab (TM)
+    A similar function of the same name was in the MATLAB 
     R13 Neural Network Toolbox but is not found in later versions;
     its successor seems to be called "processpcs".
     """
@@ -1732,7 +1732,7 @@ def ispower2(n):
 
 def isvector(X):
     """
-    Like the Matlab (TM) function with the same name, returns *True*
+    Like the MATLAB function with the same name, returns *True*
     if the supplied numpy array or matrix *X* looks like a vector,
     meaning it has a one non-singleton axis (i.e., it can have
     multiple axes, but all must have length 1, except for one of
@@ -2719,7 +2719,7 @@ def griddata(x,y,z,xi,yi,interp='nn'):
     # remove masked points.
     if hasattr(z,'mask'):
         # make sure mask is not a scalar boolean array.
-        if a.mask.ndim: 
+        if a.mask.ndim:
             x = x.compress(z.mask == False)
             y = y.compress(z.mask == False)
             z = z.compressed()
diff --git a/lib/matplotlib/pylab.py b/lib/matplotlib/pylab.py
@@ -3,7 +3,9 @@
 plotting library.
 
 The following plotting commands are provided; the majority have
-Matlab(TM) analogs and similar argument.
+MATLAB |reg| [*]_ analogs and similar arguments.
+
+.. |reg| unicode:: 0xAE
 
 _Plotting commands
   acorr     - plot the autocorrelation function
@@ -197,6 +199,9 @@
 
 __end
 
+.. [*] MATLAB is a registered trademark of The MathWorks, Inc.
+
+
 """
 import sys, warnings
 
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -1,3 +1,19 @@
+"""
+Provides a MATLAB-like plotting framework.
+
+:mod:`~matplotlib.pylab` combines pyplot with numpy into a single namespace.
+This is convenient for interactive work, but for programming it
+is recommended that the namespaces be kept separate, e.g.::
+
+    import numpy as np
+    import matplotlib.pyplot as plt
+
+    x = np.arange(0, 5, 0.1);
+    y = np.sin(x)
+    plt.plot(x, y)
+
+"""
+
 import sys
 
 import matplotlib
@@ -197,7 +213,7 @@ def figure(num=None, # autoincrement if None, else integer from 1-N
 
     If *num* is an integer, and ``figure(num)`` already exists, make it
     active and return a reference to it.  If ``figure(num)`` does not exist
-    it will be created.  Numbering starts at 1, matlab style::
+    it will be created.  Numbering starts at 1, MATLAB style::
 
       figure(1)
 
@@ -739,7 +755,7 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True,
         subplot_kw['sharey'] = ax0
     axarr[0] = ax0
 
-    # Note off-by-one counting because add_subplot uses the matlab 1-based
+    # Note off-by-one counting because add_subplot uses the MATLAB 1-based
     # convention.
     for i in range(1, nplots):
         axarr[i] = fig.add_subplot(nrows, ncols, i+1, **subplot_kw)
@@ -947,7 +963,7 @@ def axis(*v, **kwargs):
     changes *x* and *y* axis limits such that all data is shown. If
     all data is already shown, it will move it to the center of the
     figure without modifying (*xmax* - *xmin*) or (*ymax* -
-    *ymin*). Note this is slightly different than in matlab.
+    *ymin*). Note this is slightly different than in MATLAB.
 
       >>> axis('image')
 
