Load a separated value text file to a list of column arrays.

    Basically, this function calls loadSVrecs, and transposes the string-valued 
    row data returned by that function into a Python list of numpy arrays 
    corresponding to columns, each a uniform Python type (int, float, str).  
    Also uses and returns metadata including column names, formats, coloring, 
    &c. if these items  are determined during the loading process.

    **Parameters**

        **fname** :  string or file object

            Path (or file object) corresponding to a separated variable (CSV) 
            text file.
                    
        **usecols** :  sequence of non-negative integers or strings, optional

            Only the columns in *usecols* are loaded and processed.  Columns can 
            be described by number, with 0 being the first column; or if name 
            metadata is present, then by name; or, if color group information is 
            present in the file, then by color group name.  Default is None, 
            e.g. all columns are loaded.
 
        **excludecols** :  sequence of non-negative integers or strings, optional

            Converse of **usecols**, e.g. all columns EXCEPT those listed 
            will be loaded. 
            
        **valuefixer**  :  callable, or list or dictionary of callables, optional
    
            These callable(s) are applied to every value in each field.  The 
            application is done after line strings are loaded and split into 
            fields, but before any typing or missing-value imputation is done.  
            The purpose of the **valuefixer** is to prepare column 
            values for typing and imputation.  The valuefixer callable can 
            return a string or a python object.  If `valuefixer` is a single 
            callable, then that same callable is applied to values in all 
            column; if it is a dictionary, then the keys can be either 
            numbers or names and the value for the key will be applied to 
            values in the corresponding column with that name or number; if 
            it is a list, then the list elements must be in 1-to-1 
            correspondence with the loaded columns, and are applied to each 
            respectively.
               
        **colfixer** : callable, or list or dictionary of callables, optional

            Same as **valuefixer**, but instead of being applied to 
            individual values, are applied to whole columns (and must return 
            columns or numpy arrays of identical length).  Like valuefixer, 
            colfixer callable(s) are applied before typing and missing-value 
            imputation.  
                
        **missingvalues** : string, callable returning string, or list or dictionary of strings or string-valued callable
            
            String value(s) to consider as "missing data" and to be replaced 
            before typing is done.   If specified as a callable, the 
            callable will be applied to the column(s) to determine missing 
            value.  If specified as a dictionary, keys are expected to be 
            numbers of names of columns, and values are individual missing 
            values for those columns (like **valuefixer** inferface).                   
                
        **fillingvalues** : string, pair of strings, callable returning string, or list or dictionary of strings or string-valued callable
            
            Values to be used to replace missing data before typing is done.   
            If specified as a  single non-callable, non-tuple value, this 
            value is used to replace all missing data.  If specified as a 
            callable, the callable is applied to the column and returns the 
            fill value (e.g. to allow the value to depend on the column 
            type).  If specified as a pair of values, the first value acts 
            as the missing value and the second as the value to replace 
            with.  If a dictionary or list of values, then values are 
            applied to corresponding columns.  
    
        NOTE:  all the **missingvalues** and **fillingvalues** 
        functionalities can be replicated (and generalized) using the 
        **valuefixer** or **colfixer** parameters, by specifying function(s) 
        which identify and replace missing values.  While more limited, 
        using **missingvalues** and **fillingvalues**  interface is easier 
        and gives better performance.   
    
        **typer** : callable taking python list of strings (or other values) 
        and returning 1-d numpy array; or list dictionary of such callables  
            
           Function used to infer type and convert string lists into typed 
           numpy arrays, if no format information has been provided.  When 
           applied at all, this function is applied after string have been 
           loaded and split into fields.  This function is expected to 
           impute missing values as well, and will override any setting of 
           **missingvalues** or **fillingvalues**.  If a callable is passed,  
           it is used as typer for all columns, while if a dictionary (or 
           list) of callables is passed, they're used on corresponding 
           columns.  If needed (e.g. because formatting information hasn't 
           been supplied) but **typer** isn't specified (at least, for a 
           given column), the constructor defaults to using the 
           `utils.DEFAULT_TYPEINFERER` function.          
                          
        **kwargs**: keyword argument dictionary of variable length
         
            Contains various parameters to be passed on to loadSVrecs, 
            including **skiprows**, **comments**, **delimiter**, 
            **lineterminator**, **uselines**,  **metametadata**, 
            **namesinheader**,**headerlines**, **linefixer**,  
            **delimiter_regex**, **inflines**, **verbosity**, and various 
            CSV module parameters like **escapechar**, **quoting**, 
            **quotechar**, **doublequote**, **skipinitialspace**. 
            
    **Returns**

        **columns** :  list of numpy arrays

            List of arrays corresponding to columns of data.

        **metadata** :  dictionary

            Metadata read and constructed during process of reading file.

    **See Also:**

            :func:`tabular.io.loadSV`, :func:`tabular.io.saveSV`, 
            :func:`tabular.io.DEFAULT_TYPEINFERER`

def loadSVcols(fname, usecols=None, excludecols=None, valuefixer=None, 
               colfixer=None, missingvalues=None, fillingvalues=None,
               typeinferer=None, **kwargs):
    """
    Load a separated value text file to a list of column arrays.

    Basically, this function calls loadSVrecs, and transposes the string-valued 
    row data returned by that function into a Python list of numpy arrays 
    corresponding to columns, each a uniform Python type (int, float, str).  
    Also uses and returns metadata including column names, formats, coloring, 
    &c. if these items  are determined during the loading process.

    **Parameters**

        **fname** :  string or file object

            Path (or file object) corresponding to a separated variable (CSV) 
            text file.
                    
        **usecols** :  sequence of non-negative integers or strings, optional

            Only the columns in *usecols* are loaded and processed.  Columns can 
            be described by number, with 0 being the first column; or if name 
            metadata is present, then by name; or, if color group information is 
            present in the file, then by color group name.  Default is None, 
            e.g. all columns are loaded.
 
        **excludecols** :  sequence of non-negative integers or strings, optional

            Converse of **usecols**, e.g. all columns EXCEPT those listed 
            will be loaded. 
            
        **valuefixer**  :  callable, or list or dictionary of callables, optional
    
            These callable(s) are applied to every value in each field.  The 
            application is done after line strings are loaded and split into 
            fields, but before any typing or missing-value imputation is done.  
            The purpose of the **valuefixer** is to prepare column 
            values for typing and imputation.  The valuefixer callable can 
            return a string or a python object.  If `valuefixer` is a single 
            callable, then that same callable is applied to values in all 
            column; if it is a dictionary, then the keys can be either 
            numbers or names and the value for the key will be applied to 
            values in the corresponding column with that name or number; if 
            it is a list, then the list elements must be in 1-to-1 
            correspondence with the loaded columns, and are applied to each 
            respectively.
               
        **colfixer** : callable, or list or dictionary of callables, optional

            Same as **valuefixer**, but instead of being applied to 
            individual values, are applied to whole columns (and must return 
            columns or numpy arrays of identical length).  Like valuefixer, 
            colfixer callable(s) are applied before typing and missing-value 
            imputation.  
                
        **missingvalues** : string, callable returning string, or list or dictionary of strings or string-valued callable
            
            String value(s) to consider as "missing data" and to be replaced 
            before typing is done.   If specified as a callable, the 
            callable will be applied to the column(s) to determine missing 
            value.  If specified as a dictionary, keys are expected to be 
            numbers of names of columns, and values are individual missing 
            values for those columns (like **valuefixer** inferface).                   
                
        **fillingvalues** : string, pair of strings, callable returning string, or list or dictionary of strings or string-valued callable
            
            Values to be used to replace missing data before typing is done.   
            If specified as a  single non-callable, non-tuple value, this 
            value is used to replace all missing data.  If specified as a 
            callable, the callable is applied to the column and returns the 
            fill value (e.g. to allow the value to depend on the column 
            type).  If specified as a pair of values, the first value acts 
            as the missing value and the second as the value to replace 
            with.  If a dictionary or list of values, then values are 
            applied to corresponding columns.  
    
        NOTE:  all the **missingvalues** and **fillingvalues** 
        functionalities can be replicated (and generalized) using the 
        **valuefixer** or **colfixer** parameters, by specifying function(s) 
        which identify and replace missing values.  While more limited, 
        using **missingvalues** and **fillingvalues**  interface is easier 
        and gives better performance.   
    
        **typer** : callable taking python list of strings (or other values) 
        and returning 1-d numpy array; or list dictionary of such callables  
            
           Function used to infer type and convert string lists into typed 
           numpy arrays, if no format information has been provided.  When 
           applied at all, this function is applied after string have been 
           loaded and split into fields.  This function is expected to 
           impute missing values as well, and will override any setting of 
           **missingvalues** or **fillingvalues**.  If a callable is passed,  
           it is used as typer for all columns, while if a dictionary (or 
           list) of callables is passed, they're used on corresponding 
           columns.  If needed (e.g. because formatting information hasn't 
           been supplied) but **typer** isn't specified (at least, for a 
           given column), the constructor defaults to using the 
           `utils.DEFAULT_TYPEINFERER` function.          
                          
        **kwargs**: keyword argument dictionary of variable length
         
            Contains various parameters to be passed on to loadSVrecs, 
            including **skiprows**, **comments**, **delimiter**, 
            **lineterminator**, **uselines**,  **metametadata**, 
            **namesinheader**,**headerlines**, **linefixer**,  
            **delimiter_regex**, **inflines**, **verbosity**, and various 
            CSV module parameters like **escapechar**, **quoting**, 
            **quotechar**, **doublequote**, **skipinitialspace**. 
            
    **Returns**

        **columns** :  list of numpy arrays

            List of arrays corresponding to columns of data.

        **metadata** :  dictionary

            Metadata read and constructed during process of reading file.

    **See Also:**

            :func:`tabular.io.loadSV`, :func:`tabular.io.saveSV`, 
            :func:`tabular.io.DEFAULT_TYPEINFERER`

    """
    [records, metadata] = loadSVrecs(fname, **kwargs)
     
    lens = np.array([len(r) for r in records])
    assert (lens == lens[0]).all(), 'Not all records have same number of fields'

    l0 = lens[0]
    processmetadata(metadata,items='types,formats', ncols = l0)

    if usecols is not None:
        getcols = [i if i >= 0 else l0 + i for i in usecols 
                   if isinstance(i, int)]
        if 'names' in metadata.keys():
            names = metadata['names']
            getcols += [names.index(c) for c in usecols if c in names]
            if 'coloring' in metadata.keys():
                coloring = metadata['coloring']
                for c in usecols:
                    if c in coloring.keys():
                        getcols += [names.index(n) for n in coloring[c]]
        getcols = uniqify(getcols)
    else:
        if 'names' in metadata.keys():
            names = metadata['names']
            getcols = range(len(names))
        else:
            getcols = range(l0)
        if excludecols is not None:
            dontget = [i if i >= 0 else l0 + i for i in excludecols 
                       if isinstance(i, int)]
            if 'names' in metadata.keys():
                dontget += [names.index(c) for c in excludecols if c in names]
                if 'coloring' in metadata.keys():
                    coloring = metadata['coloring']
                    for c in excludecols:
                        if c in coloring.keys():
                            dontget += [names.index(n) for n in coloring[c]]
            getcols = list(set(getcols).difference(dontget))
    
    getcols.sort()
    if max(getcols) > l0:
        bad = [i for i in getcols if i >= l0]
        getcols = [i for i in getcols if i < l0]
        print 'Too many column names. Discarding columns,', bad
        
    metadatacolthreshold(metadata,getcols)
 
    if 'formats' in metadata.keys() or 'types' in metadata.keys():
        if 'formats' in metadata.keys():
            formats = metadata['formats']
        else:
            formats = metadata['types']
        formats = dict(zip(getcols,formats))
    else:
        formats = dict([(j,None) for j in getcols])
              
    if 'names' in metadata.keys():
        names = metadata['names']
    else:
        names = None
        
    valfix = utils.processvfd(valuefixer, numbers=getcols, names=names)
    colfix = utils.processvfd(colfixer, numbers=getcols, names=names)
    missval = utils.processvfd(missingvalues, numbers=getcols, names=names)
    fillval = utils.processvfd(fillingvalues, numbers=getcols, names=names)
    typer = utils.processvfd(typeinferer, numbers=getcols, names=names)
      
    return [[preparecol(records, j, formats[j], valfix[j], colfix[j],
             missval[j], fillval[j], typer[j]) for j in getcols], metadata]