Changeset 9089:cabd367ac91f in orange


Ignore:
Timestamp:
10/10/11 16:08:50 (3 years ago)
Author:
ales_erjavec <ales.erjavec@…>
Branch:
default
Convert:
cb46453d764fa8db1391fc9e41cd5b100b9c1b11
Message:

Added basic documentation for io module.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • orange/Orange/data/io.py

    r8926 r9089  
     1"""\ 
     2***************** 
     3Data I/O (``io``) 
     4***************** 
     5 
     6Import/Export 
     7============= 
     8 
     9This module contains the functions for importing and exporting Orange 
     10data tables from/to different file formats. This works by associating 
     11a filename extension with a set of loading/saving functions using 
     12:obj:`register_file_type`. 
     13 
     14Support for some formats is already implemented:   
     15     
     16    - Weka `.arff` format 
     17    - C4.5 `.data/.names` format 
     18    - LibSVM data format 
     19    - R `.R` data frame source (export only) 
     20 
     21 
     22.. function:: register_file_type(format_name, load_func, save_func, extension) 
     23 
     24    Register the ``save_func``, ``load_func`` pair for the  
     25    ``format_name``. The format is identified by the ``extension``. 
     26     
     27    :param format_name: the name of the format. 
     28    :type format_name: str 
     29     
     30    :param load_func: a function used for loading the data (see  
     31        :ref:`custom-formats` for details) 
     32    :type load_func: function 
     33     
     34    :param save_func: a function used for saving the data (see  
     35        :ref:`custom-formats` for details) 
     36    :type save_func: function 
     37     
     38    :param extension: the file extension associated with this format  
     39        (e.g. '.myformat'). This can be a list of extension if the  
     40        format uses multiple extensions (for instance the  
     41        `.data` and `.names` file pairs in the C4.5 format) 
     42     
     43    Example from the :obj:`~Orange.data.io` module that registers the Weka .arff  
     44    format :: 
     45         
     46        register_file_type("Weka", load_ARFF, to_ARFF, ".arff") 
     47         
     48``load_func`` or ``save_func`` can be None, indicating that the 
     49corresponding functionality is not supported. 
     50  
     51Loading and saving from/to custom formats then works the same way as 
     52the standard Orange `.tab` file but with a different filename 
     53extension. :: 
     54 
     55    >>> import Orange 
     56    >>> data = Orange.data.Table("iris.arff") 
     57    >>> data.save("Copy of iris.arff") 
     58   
     59     
     60 
     61.. _custom-formats: 
     62 
     63Implementing custom import/export functions. 
     64-------------------------------------------- 
     65 
     66The signature for the custom load functions should be 
     67 
     68``load_myformat(filename, create_new_on=Variable.MakeStatus.NoRecognizedValues, **kwargs)`` 
     69     
     70When constructing variables :obj:`Orange.data.variable.make` should  
     71be used with the ``create_new_on`` parameter.  
     72:obj:`~Orange.data.variable.make` will return an attribute and the  
     73status of the variable, telling whether a new attribute was created  
     74or the old one reused and why (see :mod:`Orange.data.variable`).  
     75Additional keyword arguments can be provided in the call to  
     76:obj:`~Orange.data.Table` constructor. These will be passed in the  
     77``**kwargs``.  
     78The function should return the build :obj:`~Orange.data.Table` object. 
     79For examples see the source code for the ``Orange.data.io`` module 
     80 
     81The save function is easier to implement. 
     82 
     83``save_myformat(filename, table, **kwargs)`` 
     84 
     85Similar as above the ``**kwargs`` contains any additional arguments 
     86:obj:`~Orange.data.Table.save`. 
     87   
     88""" 
    189import os 
    290 
     
    694from Orange.core import \ 
    795     BasketFeeder, FileExampleGenerator, BasketExampleGenerator, \ 
    8      C45ExampleGenerator, TabDelimExampleGenerator, registerFileType 
     96     C45ExampleGenerator, TabDelimExampleGenerator, \ 
     97     registerFileType as register_file_type 
    998 
    1099from Orange.data import variable 
     
    646735     
    647736         
    648  
    649 registerFileType("R", None, toR, ".R") 
    650 registerFileType("Weka", loadARFF, toARFF, ".arff") 
     737register_file_type("R", None, toR, ".R") 
     738register_file_type("Weka", loadARFF, toARFF, ".arff") 
    651739#registerFileType("C50", None, toC50, [".names", ".data", ".test"]) 
    652 registerFileType("libSVM", loadLibSVM, toLibSVM, ".svm") 
    653   
     740register_file_type("libSVM", loadLibSVM, toLibSVM, ".svm") 
     741 
     742registerFileType = Orange.misc.deprecated_function_name(register_file_type) 
Note: See TracChangeset for help on using the changeset viewer.