Changeset 9788:6da516e4e6e9 in orange


Ignore:
Timestamp:
02/06/12 17:55:08 (2 years ago)
Author:
janezd <janez.demsar@…>
Branch:
default
rebase_source:
fd1aaaa4ba9f5f284dc0e9ed2902e0eeb8bd6bbe
Message:

Polished documentation for Orange.data.instance

File:
1 edited

Legend:

Unmodified
Added
Removed
  • docs/reference/rst/Orange.data.instance.rst

    r9525 r9788  
    55============================= 
    66 
    7 Class `Orange.data.Instance` holds data instances. Each data instance 
     7Class `Orange.data.Instance` holds a data instance. Each data instance 
    88corresponds to a domain, which defines its length, data types and 
    99values for symbolic indices. 
     
    1313-------- 
    1414 
    15 The data instance is described by a list of features, defined by the 
    16 domain descriptor. Instances support indexing with either integer 
    17 indices, strings or variable descriptors. 
     15The data instance is described by a list of features defined by the 
     16domain descriptor (:obj:`Orange.data.domain`). Instances support indexing 
     17with either integer indices, strings or variable descriptors. 
    1818 
    1919Since "age" is the the first attribute in dataset lenses, the 
    20 below statements are equivalent.:: 
    21  
     20below statements are equivalent:: 
     21 
     22    >>> data = Orange.data.Table("lenses") 
    2223    >>> age = data.domain["age"] 
    2324    >>> example = data[0] 
     
    2930    young 
    3031 
    31 Negative indices do not work as usual in Python, since they return 
     32Negative indices do not work as usual in Python, since they refer to 
    3233the values of meta attributes. 
    3334 
    34 The last element of data instance is the class label, if it 
    35 exists. It should be accessed using :obj:`get_class` and 
    36 :obj:`set_class`. 
    37  
    38 Data instances can be traversed using a for loop. 
    39  
    40 The list has a fixed length, determined by the domain to which the 
    41 instance corresponds. 
     35The last element of data instance is the class label, 
     36if the domain has a class. It should be accessed using 
     37:obj:`~Orange.data.Instance.get_class()` and 
     38:obj:`~Orange.data.Instance.set_class()`. 
     39 
     40The list has a fixed length that equals the number of variables. 
    4241 
    4342--------------- 
     
    4544--------------- 
    4645 
    47 Meta attributes provide a way to attach additional information to 
    48 examples. These attributes are treated specially, for instance, they 
    49 are not used for learning, but can carry additional information, such 
    50 as, for example, a name of a patient or the number of times the 
    51 instance was missclassified during some test procedure. The most 
    52 common additional information is the instance's weight. 
    53  
    54 For contrast from ordinary features, instances from the same domain do 
    55 not need to have the same meta attributes. Meta attributes are hence 
    56 not addressed by positions, but by their id's, which are represented 
    57 by negative indices. Id's are generated by function 
    58 :obj:`Orange.data.variable.new_meta_id()`. Id's can be reused for 
    59 multiple domains. 
    60  
    61 If ordinary features resemble lists, meta attributes can be seen as a 
    62 dictionaries. 
     46Meta attributes provide a way to attach additional information to data 
     47instances, such as, for example, an id of a patient or the number of times 
     48the instance was missclassified during some test procedure. The most 
     49common additional information is the instance's weight. These attributes 
     50do not appear in induced models. 
     51 
     52Instances from the same domain do not need to have the same meta 
     53attributes. Meta attributes are hence not addressed by positions, 
     54but by their id's, which are represented by negative indices. Id's are 
     55generated by function :obj:`Orange.data.variable.new_meta_id()`. Id's can 
     56be reused for multiple domains. 
    6357 
    6458Domain descriptor can, but doesn't need to know about 
     
    6963for the domain, attribute or its name can also be used for 
    7064indexing. When registering meta attributes with domains, it is 
    71 recommended to used the same id for the same attribute in all domains. 
     65recommended to use the same id for the same attribute in all domains. 
    7266 
    7367Meta values can also be loaded from files in tab-delimited format. 
     
    7569Meta attributes are often used as weights. Many procedures, such as 
    7670learning algorithms, accept the id of the meta attribute defining the 
    77 weights of instances as an additional argument besides the data. 
     71weights of instances as an additional argument. 
    7872 
    7973The following example adds a meta attribute with a random value to 
    80 each data instance 
     74each data instance. 
    8175 
    8276.. literalinclude:: code/instance-metavar.py 
    8377    :lines: 1- 
    8478 
    85 The code prints out something like:: 
     79The code prints out:: 
    8680 
    8781    ['young', 'myope', 'no', 'reduced', 'none'], {-2:0.84} 
    8882 
    89 Data instance now consists of two parts, ordinary features that 
     83(except for a different random value). Data instance now consists of 
     84two parts, ordinary features that 
    9085resemble a list since they are addressed by positions (eg. the first 
    9186value is "psby"), and meta values that are more like dictionaries, 
    92 where the id (-2) is a key and 0.34 is a value (of type 
     87where the id (-2) is a key and 0.84 is a value (of type 
    9388:obj:`Orange.data.Value`). 
    9489 
     
    10095Many other functions accept weights in similar fashion. 
    10196 
    102 Code:: 
     97Code :: 
    10398 
    10499    print orange.getClassDistribution(data) 
    105100    print orange.getClassDistribution(data, id) 
    106101 
    107 prints out:: 
     102prints out :: 
    108103 
    109104    <15.000, 5.000, 4.000> 
    110105    <9.691, 3.232, 1.969> 
    111106 
    112 Registering the meta attribute changes how the data instance is 
    113 printed out and how it can be accessed:: 
     107where the first line is the actual distribution and the second a 
     108distribution with random weights assigned to the instances. 
     109 
     110Registering the meta attribute using :obj:`Orange.data.Domain.add_meta` 
     111changes how the data instance is printed out and how it can be 
     112accessed:: 
    114113 
    115114    w = orange.FloatVariable("w") 
     
    152151 
    153152        Construct a data instance with the given domain and initialize 
    154         the values. Values should be given as a list containing 
     153        the values. Values are given as a list of 
    155154        objects that can be converted into values of corresponding 
    156         variables; generally, they can be given as strings and 
    157         integer indices (for discrete varaibles) or numbers (for 
    158         continuous variables), and also as instances of 
     155        variables: strings and integer indices (for discrete varaibles), 
     156        strings or numbers (for continuous variables), or instances of 
    159157        :obj:`Orange.data.Value`. 
    160158 
     
    181179        Construct a new data instance as a shallow copy of the 
    182180        original. If a domain descriptor is given, the instance is 
    183         converted; conversion can add or remove variables, including 
    184         transformations, like discretization ets. 
     181        converted to another domain. 
    185182 
    186183        :param domain: domain descriptor 
     
    197194    .. method:: __init__(domain, instances) 
    198195 
    199         Construct a new data instance for the given domain, where 
    200         attribute values are taken from the provided instances, using 
    201         both their ordinary features and meta attributes, which are 
    202         registered with their corresponding domains. Meta attributes 
    203         which appear in the provided instances and do not appear in 
    204         the domain of the new instance, are copied as well. 
     196        Construct a new data instance for the given domain, where the 
     197        feature values are found in the provided instances using 
     198        both their ordinary features and meta attributes that are 
     199        registered with their corresponding domains. The new instance 
     200        also includes the meta attributes that appear in the provided 
     201        instances and whose values are not used for the instance's 
     202        features. 
    205203 
    206204        :param domain: domain descriptor 
     
    237235    .. method:: native([level]) 
    238236 
    239         Converts the instance into an ordinary Python list. If the 
    240         optional argument is 1 (default), the result is a list of 
    241         objects of :obj:`orange.Data.value`. If it is 0, it contains 
    242         pure Pyhon objects, that is, strings for discrete variables 
     237        Convert the instance into an ordinary Python list. If the 
     238        optional argument `level` is 1 (default), the result is a list of 
     239        instances of :obj:`orange.data.Value`. If it is 0, it contains 
     240        pure Python objects, that is, strings for discrete variables 
    243241        and numbers for continuous ones. 
    244242 
    245     .. method:: compatible(other, ignore_class=0) 
    246  
    247         Return :obj:`True` if the two instances are compatible, that 
     243    .. method:: compatible(other, ignore_class=False) 
     244 
     245        Return ``True`` if the two instances are compatible, that 
    248246        is, equal in all features which are not missing in one of 
    249247        them. The optional second argument can be used to omit the 
     
    276274 
    277275        Return a dictionary containing meta values of the data 
    278         instance. The key type can be :obj:`int` (default), :obj:`str` 
    279         or :obj:`Orange.data.variable.Variable` and determines whether 
    280         the dictionary keys will be meta ids, variables names or 
     276        instance. The argument ``key_type`` can be ``int`` (default), 
     277        ``str`` or :obj:`Orange.data.variable.Variable` and 
     278        determines whether 
     279        the dictionary keys are meta ids, variables names or 
    281280        variable descriptors. In the latter two cases, only registered 
    282281        attributes are returned. :: 
     
    289288            print example.getmetas(orange.Variable) 
    290289 
    291         :param key_type: the key type; either :obj:`int`, :obj:`str` or :obj:`Orange.data.variable.Variable` 
    292         :type key_type: :obj:`type` 
     290        :param key_type: the key type; either ``int``, ``str`` or :obj:`~Orange.data.variable.Variable` 
     291        :type key_type: ``type`` 
    293292 
    294293    .. method:: get_metas(optional, [key_type]) 
    295294 
    296         Similar to above, but return a dictionary containing meta 
    297         values of the data instance which are or which are not 
    298         optional. 
     295        Similar to above, but return a dictionary that contains 
     296        only non-optional attributes (if ``optional`` is 0) or 
     297        only optional attributes. 
    299298 
    300299        :param optional: tells whether to return optional or non-optional attributes 
    301         :type optional: :obj:`bool` 
    302         :param key_type: the key type; either :obj:`int`, :obj:`str` or :obj:`Orange.data.variable.Variable` 
    303         :type key_type: :obj:`type` 
     300        :type optional: ``bool`` 
     301        :param key_type: the key type; either ``int``, ``str`` or :obj:`~Orange.data.variable.Variable` 
     302        :type key_type: `type`` 
    304303 
    305304    .. method:: has_meta(meta_attr) 
    306305 
    307         Return :obj:`True` if the data instance has the specified meta 
    308         attribute, specified by id, string or descriptor. 
     306        Return ``True`` if the data instance has the specified meta 
     307        attribute. 
    309308 
    310309        :param meta_attr: meta attribute 
    311         :type meta_attr: :obj:`id`, :obj:`str` or :obj:`Orange.data.variable.Variable` 
     310        :type meta_attr: :obj:`id`, ``str`` or :obj:`~Orange.data.variable.Variable` 
    312311 
    313312    .. method:: remove_meta(meta_attr) 
    314313 
    315         Remove meta attribute. 
     314        Remove the specified meta attribute. 
    316315 
    317316        :param meta_attr: meta attribute 
    318         :type meta_attr: :obj:`id`, :obj:`str` or :obj:`Orange.data.variable.Variable` 
     317        :type meta_attr: :obj:`id`, ``str`` or :obj:`~Orange.data.variable.Variable` 
    319318 
    320319    .. method:: get_weight(meta_attr) 
    321320 
    322         Return the value of the specified meta attribute. The value 
    323         must be continuous; it is returned as a :obj:`float`. 
     321        Return the value of the specified meta attribute. The 
     322        attribute's value must be continuous and is returned as ``float``. 
    324323 
    325324        :param meta_attr: meta attribute 
    326         :type meta_attr: :obj:`id`, :obj:`str` or :obj:`Orange.data.variable.Variable` 
     325        :type meta_attr: :obj:`id`, ``str`` or :obj:`~Orange.data.variable.Variable` 
    327326 
    328327    .. method:: set_weight(meta_attr, weight=1) 
    329328 
    330         Set the value of the specified meta attribute to `weight`. The value 
    331         must be continuous; it is returned as a :obj:`float`. 
     329        Set the value of the specified meta attribute to ``weight``. 
    332330 
    333331        :param meta_attr: meta attribute 
    334         :type meta_attr: :obj:`id`, :obj:`str` or :obj:`Orange.data.variable.Variable` 
    335         :param weight: weight of the instance 
    336         :type weight: :obj:`float` 
     332        :type meta_attr: :obj:`id`, ``str`` or :obj:`~Orange.data.variable.Variable` 
     333        :param weight: weight of instance 
     334        :type weight: ``float`` 
Note: See TracChangeset for help on using the changeset viewer.