DOC: merge wiki edits for io module.

scipy/io/arff/arffread.py

@@ -455,7 +455,14 @@ def types(self):
 
 
 def loadarff(filename):
-    """Read an arff file.
+    """
+    Read an arff file.
+
+    The data is returned as a record array, which can be accessed much like
+    a dictionary of numpy arrays.  For example, if one of the attributes is
+    called 'pressure', then its first 10 data points can be accessed from the
+    ``data`` record array like so: ``data['pressure'][0:10]``
+
 
     Parameters
     ----------
@@ -465,22 +472,32 @@ def loadarff(filename):
     Returns
     -------
     data : record array
-       the data of the arff file. Each record corresponds to one attribute.
-    meta : MetaData
-       this contains information about the arff file, like type and
-       names of attributes, the relation (name of the dataset), etc...
+       The data of the arff file, accessible by attribute names.
+    meta : `MetaData`
+       Contains information about the arff file such as name and
+       type of attributes, the relation (name of the dataset), etc...
+
+    Raises
+    ------
+    `ParseArffError`
+        This is raised if the given file is not ARFF-formatted.
+    NotImplementedError
+        The ARFF file has an attribute which is not supported yet.
 
     Notes
     -----
 
     This function should be able to read most arff files. Not
-    implemented functionalities include:
+    implemented functionality include:
 
     * date type attributes
     * string type attributes
 
-    It can read files with numeric and nominal attributes.  It can read
-    files with sparse data (? in the file).
+    It can read files with numeric and nominal attributes.  It cannot read
+    files with sparse data ({} in the file).  However, this function can
+    read files with missing data (? in the file), representing the data
+    points as NaNs.
+
     """
     ofile = open(filename)
 

scipy/io/matlab/mio.py

@@ -22,7 +22,7 @@ def find_mat_file(file_name, appendmat=True):
 
     Parameters
     ----------
-    file_name : string
+    file_name : str
        file name for mat file
     %(append_arg)s
 
@@ -113,13 +113,14 @@ def mat_reader_factory(file_name, appendmat=True, **kwargs):
 
 @docfiller
 def loadmat(file_name,  mdict=None, appendmat=True, **kwargs):
-    ''' Load Matlab(tm) file
+    """
+    Load MATLAB file
 
     Parameters
     ----------
     %(file_arg)s
     m_dict : dict, optional
-        dictionary in which to insert matfile variables
+        Dictionary in which to insert matfile variables.
     %(append_arg)s
     %(load_args)s
     %(struct_arg)s
@@ -143,7 +144,8 @@ def loadmat(file_name,  mdict=None, appendmat=True, **kwargs):
     You will need an HDF5 python library to read matlab 7.3 format mat
     files.  Because scipy does not supply one, we do not implement the
     HDF5 / 7.3 interface here.
-    '''
+
+    """
     variable_names = kwargs.pop('variable_names', None)
     MR = mat_reader_factory(file_name, appendmat, **kwargs)
     matfile_dict = MR.get_variables(variable_names)
@@ -154,31 +156,53 @@ def loadmat(file_name,  mdict=None, appendmat=True, **kwargs):
     return mdict
 
 @docfiller
-def savemat(file_name, mdict, 
-            appendmat=True, 
-            format='5', 
+def savemat(file_name, mdict,
+            appendmat=True,
+            format='5',
             long_field_names=False,
             do_compression=False,
             oned_as=None):
-    """Save a dictionary of names and arrays into the MATLAB-style .mat file.
+    """
+    Save a dictionary of names and arrays into a MATLAB-style .mat file.
 
-    This saves the arrayobjects in the given dictionary to a matlab
+    This saves the array objects in the given dictionary to a MATLAB-
     style .mat file.
 
     Parameters
     ----------
-    file_name : {string, file-like object}
-        Name of the mat file (do not need .mat extension if
-        appendmat==True) Can also pass open file-like object
+    file_name : str or file-like object
+        Name of the .mat file (.mat extension not needed if ``appendmat ==
+        True``).
+        Can also pass open file_like object.
     m_dict : dict
-        dictionary from which to save matfile variables
+        Dictionary from which to save matfile variables.
     %(append_arg)s
-    format : {'5', '4'} string, optional
-        '5' for matlab 5 (up to matlab 7.2)
-        '4' for matlab 4 mat files
+    format : {'5', '4'}, string, optional
+        '5' (the default) for MATLAB 5 and up (to 7.2),
+        '4' for MATLAB 4 .mat files
     %(long_fields)s
     %(do_compression)s
     %(oned_as)s
+
+    See also
+    --------
+    mio4.MatFile4Writer
+    mio5.MatFile5Writer
+
+    Notes
+    -----
+    If ``format == '4'``, `mio4.MatFile4Writer` is called, which sets
+    `oned_as` to 'row' if it had been None.  If ``format == '5'``,
+    `mio5.MatFile5Writer` is called, which sets `oned_as` to 'column' if
+    it had been None, but first it executes:
+
+    ``warnings.warn("Using oned_as default value ('column')" +``
+                  ``" This will change to 'row' in future versions",``
+                  ``FutureWarning, stacklevel=2)``
+
+    without being more specific as to precisely when the change will take
+    place.
+
     """
     file_is_string = isinstance(file_name, basestring)
     if file_is_string:

scipy/io/matlab/miobase.py

@@ -24,55 +24,55 @@ class MatReadWarning(UserWarning): pass
 
 doc_dict = \
     {'file_arg':
-         '''file_name : string
+         '''file_name : str
    Name of the mat file (do not need .mat extension if
-   appendmat==True) Can also pass open file-like object''',
+   appendmat==True) Can also pass open file-like object.''',
      'append_arg':
-         '''appendmat : {True, False} optional
+         '''appendmat : bool, optional
    True to append the .mat extension to the end of the given
-   filename, if not already present''',
+   filename, if not already present.''',
      'load_args':
-         '''byte_order : {None, string}, optional
+         '''byte_order : str or None, optional
    None by default, implying byte order guessed from mat
    file. Otherwise can be one of ('native', '=', 'little', '<',
-   'BIG', '>')
-mat_dtype : {False, True} optional
+   'BIG', '>').
+mat_dtype : bool, optional
    If True, return arrays in same dtype as would be loaded into
-   matlab (instead of the dtype with which they are saved)
-squeeze_me : {False, True} optional
-   whether to squeeze unit matrix dimensions or not
-chars_as_strings : {True, False} optional
-   whether to convert char arrays to string arrays
-matlab_compatible : {False, True}
-   returns matrices as would be loaded by matlab (implies
+   MATLAB (instead of the dtype with which they are saved).
+squeeze_me : bool, optional
+   Whether to squeeze unit matrix dimensions or not.
+chars_as_strings : bool, optional
+   Whether to convert char arrays to string arrays.
+matlab_compatible : bool, optional
+   Returns matrices as would be loaded by MATLAB (implies
    squeeze_me=False, chars_as_strings=False, mat_dtype=True,
-   struct_as_record=True)''',
+   struct_as_record=True).''',
      'struct_arg':
-         '''struct_as_record : {True, False} optional
-   Whether to load matlab structs as numpy record arrays, or as
+         '''struct_as_record : bool, optional
+   Whether to load MATLAB structs as numpy record arrays, or as
    old-style numpy arrays with dtype=object.  Setting this flag to
    False replicates the behaviour of scipy version 0.7.x (returning
    numpy object arrays).  The default setting is True, because it
-   allows easier round-trip load and save of matlab files.''',
+   allows easier round-trip load and save of MATLAB files.''',
      'matstream_arg':
          '''mat_stream : file-like
-   object with file API, open for reading''',
+   Object with file API, open for reading.''',
      'long_fields':
-         '''long_field_names : boolean, optional, default=False
+         '''long_field_names : bool, optional
    * False - maximum field name length in a structure is 31 characters
-     which is the documented maximum length
+     which is the documented maximum length. This is the default.
    * True - maximum field name length in a structure is 63 characters
      which works for Matlab 7.6''',
      'do_compression':
-         '''do_compression : {False, True} bool, optional
-   Whether to compress matrices on write. Default is False''',
+         '''do_compression : bool, optional
+   Whether to compress matrices on write. Default is False.''',
      'oned_as':
-         '''oned_as : {'column', 'row'} string, optional
-   If 'column', write 1D numpy arrays as column vectors
-   If 'row', write 1D numpy arrays as row vectors''',
+         '''oned_as : {'column', 'row'}, optional
+   If 'column', write 1-D numpy arrays as column vectors.
+   If 'row', write 1D numpy arrays as row vectors.''',
      'unicode_strings':
-         '''unicode_strings : {True, False} boolean, optional
-   If True, write strings as Unicode, else matlab usual encoding'''}
+         '''unicode_strings : bool, optional
+   If True, write strings as Unicode, else matlab usual encoding.'''}
 
 docfiller = doccer.filldoc(doc_dict)