Changeset 9678:928c30f33a6f in orange


Ignore:
Timestamp:
02/06/12 11:53:54 (2 years ago)
Author:
janezd <janez.demsar@…>
Branch:
default
rebase_source:
ba5c78004024fba4c091c10fc26a09c3dc27da1e
Message:

Still more changes to Domain documentation

File:
1 edited

Legend:

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

    r9664 r9678  
    122122Meta attributes hold additional data attached to individual 
    123123instances. Different instances from the same domain or even the same 
    124 table may have different meta attributes. See documentation on 
    125 :obj:`Orange.data.Instance` for a more thorough description of meta 
    126 values. 
    127  
    128 Meta attributes that appear in instances can, but don't need to be 
     124table may have different meta attributes. (See documentation on 
     125:obj:`Orange.data.Instance` for details about meta values.) 
     126 
     127Meta attributes that appear in instances can - but don't need to - be 
    129128listed in the domain. Typically, the meta attribute will be included in 
    130129the domain for the following reasons. 
    131130 
    132      * If the domain knows about a meta attribute, their values can be 
     131     * If the domain knows about meta attributes, their values can be 
    133132       obtained with indexing by names and variable descriptors, 
    134133       e.g. ``inst["age"]``. Values of unknown meta attributes 
     
    136135       id needs to be an integer). 
    137136 
    138      * When printing out an instance, the symbolic values of discrete 
     137     * When printing out a data instance, the symbolic values of discrete 
    139138       meta attributes can only be printed if the attribute is 
    140139       registered. Also, if the attribute is registered, the printed 
     
    149148       unknown. 
    150149 
    151 For the latter two points - saving to a file and construction of new 
    152 instances - there is an additional flag: a meta attribute can be 
    153 marked as "optional". Such meta attributes are not saved and not added 
    154 to newly constructed data instances. 
    155  
    156 Another distinction between the optional and non-optional meta 
    157 attributes is that the latter are *expected to be* present in all 
    158 data instances from that domain. Saving to files expects will fail 
    159 if a non-optional meta value is missing; in most other places, 
    160 these rules are not strictly enforced, so adhering to them is rather up 
    161 to choice. 
    162  
    163 While the list of features and the class value are constant, 
    164 meta attributes can be added and removed at any time (a detailed 
    165 description of methods related to meta attributes is given below):: 
     150Meta attribute can be marked as "optional". Non-optional meta 
     151attributes are *expected to be* present in all data instances from that 
     152domain. This rule is not strictly enforced. As one of the few places 
     153where the difference matters, saving to files fails if a non-optional 
     154meta value is missing; optional attributes are not written to the file 
     155at all. Also, newly constructed data instances initially have all the 
     156non-optional meta attributes. 
     157 
     158While the list of features and the class value are immutable, 
     159meta attributes can be added and removed at any time:: 
    166160 
    167161     >>> misses = Orange.data.variable.Continuous("misses") 
     
    170164 
    171165This does not change the data: no attributes are added to data 
    172 instances. 
     166instances. Methods related to meta attributes are described in more 
     167details later. 
    173168 
    174169Registering meta attributes enables addressing by indexing, either by 
     
    232227     .. attribute:: features 
    233228 
    234     List of domain attributes 
    235     (:obj:`Orange.data.variable.Variables`) without the class 
    236     variable. Read only. 
     229        List of domain attributes 
     230        (:obj:`Orange.data.variable.Variables`) without the class 
     231        variable. Read only. 
    237232 
    238233     .. attribute:: variables 
    239234 
    240     List of domain attributes 
    241      (:obj:`Orange.data.variable.Variables`) including the class 
    242     variable. Read only. 
     235    List of domain attributes 
     236     (:obj:`~Orange.data.variable.Variables`) including the class 
     237    variable. Read only. 
    243238 
    244239     .. attribute:: class_var 
    245240 
    246      The class variable (:obj:`Orange.data.variable.Variable`), or 
    247     :obj:`None` if there is none. Read only. 
     241     The class variable (:obj:`~Orange.data.variable.Variable`), or 
     242    :obj:`None` if there is none. Read only. 
    248243 
    249244     .. attribute:: class_vars 
    250245 
    251     A list of additional class attributes. Read only. 
     246    A list of additional class attributes. Read only. 
    252247 
    253248     .. attribute:: version 
    254249 
    255     An integer value that is changed when the domain is 
    256     modified. The value can be also used as unique domain identifier; two 
    257     different domains have different value of ``version``. 
     250    An integer value that is changed when the domain is 
     251    modified. The value can be also used as unique domain identifier; two 
     252    different domains have different value of ``version``. 
    258253 
    259254     .. method:: __init__(variables[, class_vars=]) 
    260255 
    261     Construct a domain with the given variables; the 
    262     last one is used as the class variable. :: 
    263  
    264          >>> a, b, c = [Orange.data.variable.Discrete(x) for x in "abc"] 
    265          >>> domain = Orange.data.Domain([a, b, c]) 
    266          >>> domain.features 
    267          <EnumVariable 'a', EnumVariable 'b'> 
    268          >>> domain.class_var 
    269          EnumVariable 'c' 
    270  
    271      :param variables: List of variables (instances of :obj:`Orange.data.variable.Variable`) 
    272     :type variables: list 
     256    Construct a domain with the given variables; the 
     257    last one is used as the class variable. :: 
     258 
     259         >>> a, b, c = [Orange.data.variable.Discrete(x) for x in "abc"] 
     260         >>> domain = Orange.data.Domain([a, b, c]) 
     261         >>> domain.features 
     262         <EnumVariable 'a', EnumVariable 'b'> 
     263         >>> domain.class_var 
     264         EnumVariable 'c' 
     265 
     266     :param variables: List of variables (instances of :obj:`~Orange.data.variable.Variable`) 
     267    :type variables: list 
    273268     :param class_vars: A list of multiple classes; must be a keword argument 
    274269     :type class_vars: list 
     
    276271     .. method:: __init__(features, class_variable[, class_vars=]) 
    277272 
    278     Construct a domain with the given list of features and the 
    279     class variable. :: 
    280  
    281          >>> domain = Orange.data.Domain([a, b], c) 
    282          >>> domain.features 
    283          <EnumVariable 'a', EnumVariable 'b'> 
    284          >>> domain.class_var 
    285          EnumVariable 'c' 
    286  
    287      :param features: List of features (instances of :obj:`Orange.data.variable.Variable`) 
     273    Construct a domain with the given list of features and the 
     274    class variable. :: 
     275 
     276         >>> domain = Orange.data.Domain([a, b], c) 
     277         >>> domain.features 
     278         <EnumVariable 'a', EnumVariable 'b'> 
     279         >>> domain.class_var 
     280         EnumVariable 'c' 
     281 
     282     :param features: List of features (instances of :obj:`~Orange.data.variable.Variable`) 
    288283     :type features: list 
    289284     :param class_variable: Class variable 
     
    294289     .. method:: __init__(variables, has_class[, class_vars=]) 
    295290 
    296     Construct a domain with the given variables. If `has_class` is 
    297     :obj:`True`, the last one is used as the class variable. :: 
    298  
    299          >>> domain = Orange.data.Domain([a, b, c], False) 
    300          >>> domain.features 
    301          <EnumVariable 'a', EnumVariable 'b'> 
    302          >>> domain.class_var 
    303          EnumVariable 'c' 
    304  
    305      :param variables: List of variables (instances of :obj:`Orange.data.variable.Variable`) 
    306     :type features: list 
    307     :param has_class: A flag telling whether the domain has a class 
    308     :type has_class: bool 
     291    Construct a domain with the given variables. If `has_class` is 
     292    :obj:`True`, the last one is used as the class variable. :: 
     293 
     294         >>> domain = Orange.data.Domain([a, b, c], False) 
     295         >>> domain.features 
     296         <EnumVariable 'a', EnumVariable 'b'> 
     297         >>> domain.class_var 
     298         EnumVariable 'c' 
     299 
     300     :param variables: List of variables (instances of :obj:`~Orange.data.variable.Variable`) 
     301    :type features: list 
     302    :param has_class: A flag telling whether the domain has a class 
     303    :type has_class: bool 
    309304     :param class_vars: A list of multiple classes; must be a keyword argument 
    310305     :type class_vars: list 
     
    312307     .. method:: __init__(variables, source[, class_vars=]) 
    313308 
    314     Construct a domain with the given variables that can also be 
    315     specified by names if the variables with that names exist in the 
    316     source list. The last variable from the list is used as the class 
    317     variable. :: 
    318  
    319          >>> domain1 = orange.Domain([a, b]) 
    320          >>> domain2 = orange.Domain(["a", b, c], domain) 
    321  
    322      :param variables: List of variables (strings or instances of :obj:`Orange.data.variable.Variable`) 
    323     :type variables: list 
    324     :param source: An existing domain or a list of variables 
    325      :type source: Orange.data.Domain or list of :obj:`Orange.data.variable.Variable` 
     309    Construct a domain with the given variables that can also be 
     310    specified by names if the variables with that names exist in the 
     311    source list. The last variable from the list is used as the class 
     312    variable. :: 
     313 
     314         >>> domain1 = orange.Domain([a, b]) 
     315         >>> domain2 = orange.Domain(["a", b, c], domain) 
     316 
     317     :param variables: List of variables (strings or instances of :obj:`~Orange.data.variable.Variable`) 
     318    :type variables: list 
     319    :param source: An existing domain or a list of variables 
     320     :type source: Orange.data.Domain or list of :obj:`~Orange.data.variable.Variable` 
    326321     :param class_vars: A list of multiple classes; must be a keyword argument 
    327322     :type class_vars: list 
     
    329324     .. method:: __init__(variables, has_class, source[, class_vars=]) 
    330325 
    331     Similar to above except for the flag which tells whether the 
    332     last variable should be used as the class variable. :: 
    333  
    334          >>> domain1 = orange.Domain([a, b], False) 
    335          >>> domain2 = orange.Domain(["a", b, c], False, domain) 
    336  
    337      :param variables: List of variables (strings or instances of :obj:`Orange.data.variable.Variable`) 
    338     :type variables: list 
    339     :param has_class: A flag telling whether the domain has a class 
    340     :type has_class: bool 
    341     :param source: An existing domain or a list of variables 
    342      :type source: Orange.data.Domain or list of :obj:`Orange.data.variable.Variable` 
     326    Similar to above except for the flag which tells whether the 
     327    last variable should be used as the class variable. :: 
     328 
     329         >>> domain1 = orange.Domain([a, b], False) 
     330         >>> domain2 = orange.Domain(["a", b, c], False, domain) 
     331 
     332     :param variables: List of variables (strings or instances of :obj:`~Orange.data.variable.Variable`) 
     333    :type variables: list 
     334    :param has_class: A flag telling whether the domain has a class 
     335    :type has_class: bool 
     336    :param source: An existing domain or a list of variables 
     337     :type source: Orange.data.Domain or list of :obj:`~Orange.data.variable.Variable` 
    343338     :param class_vars: A list of multiple classes; must be a keyword argument 
    344339     :type class_vars: list 
     
    346341     .. method:: __init__(domain, class_var[, class_vars=]) 
    347342 
    348      Construct a copy of an existing domain 
    349      except that the class variable is replaced with the given one 
    350      and the class variable of the existing domain becomes an 
    351      ordinary feature. If the new class is one of the original 
    352      domain's features, it can also be specified by a name. 
    353  
    354      :param domain: An existing domain 
    355      :type domain: :obj:`Orange.variable.Domain` 
    356      :param class_var: Class variable for the new domain 
    357      :type class_var: string or :obj:`Orange.data.variable.Variable` 
     343     Construct a copy of an existing domain 
     344     except that the class variable is replaced with the given one 
     345     and the class variable of the existing domain becomes an 
     346     ordinary feature. If the new class is one of the original 
     347     domain's features, it can also be specified by a name. 
     348 
     349     :param domain: An existing domain 
     350     :type domain: :obj:`~Orange.variable.Domain` 
     351     :param class_var: Class variable for the new domain 
     352     :type class_var: string or :obj:`~Orange.data.variable.Variable` 
     353     :param class_vars: A list of multiple classes; must be a keyword argument 
     354     :type class_vars: list 
     355 
     356     .. method:: __init__(domain, has_class=False[, class_vars=]) 
     357 
     358     Construct a copy of the domain. If the ``has_class`` 
     359     flag is given and is :obj:`False`, it moves the class 
     360     attribute to ordinary features. 
     361 
     362     :param domain: An existing domain 
     363     :type domain: :obj:`~Orange.variable.Domain` 
     364     :param has_class: A flag telling whether the domain has a class 
     365     :type has_class: bool 
    358366     :param class_vars: A list of multiple classes; must be a keword argument 
    359367     :type class_vars: list 
    360368 
    361      .. method:: __init__(domain, has_class=False[, class_vars=]) 
    362  
    363      Construct a copy of the domain. If the ``has_class`` 
    364      flag is given and is :obj:`False`, it moves the class 
    365      attribute to ordinary features. 
    366  
    367      :param domain: An existing domain 
    368      :type domain: :obj:`Orange.variable.Domain` 
    369      :param has_class: A flag telling whether the domain has a class 
    370      :type has_class: bool 
    371      :param class_vars: A list of multiple classes; must be a keword argument 
    372      :type class_vars: list 
    373  
    374369     .. method:: has_discrete_attributes(include_class=True) 
    375370 
    376     Return :obj:`True` if the domain has any discrete variables; 
    377     class is included unless ``include_class`` is ``False``. 
    378  
    379     :param has_class: Tells whether to consider the class variable 
    380     :type has_class: bool 
    381     :rtype: bool 
     371    Return :obj:`True` if the domain has any discrete variables; 
     372    class is included unless ``include_class`` is ``False``. 
     373 
     374    :param has_class: Tells whether to consider the class variable 
     375    :type has_class: bool 
     376    :rtype: bool 
    382377 
    383378     .. method:: has_continuous_attributes(include_class=True) 
    384379 
    385     Return :obj:`True` if the domain has any continuous variables; 
    386     class is included unless ``include_class`` is ``False``. 
    387  
    388     :param has_class: Tells whether to consider the class variable 
    389     :type has_class: bool 
    390     :rtype: bool 
     380    Return :obj:`True` if the domain has any continuous variables; 
     381    class is included unless ``include_class`` is ``False``. 
     382 
     383    :param has_class: Tells whether to consider the class variable 
     384    :type has_class: bool 
     385    :rtype: bool 
    391386 
    392387     .. method:: has_other_attributes(include_class=True) 
    393388 
    394     Return :obj:`True` if the domain has any variables which are 
    395     neither discrete nor continuous, such as, for instance string variables. 
    396     class is included unless ``include_class`` is ``False``. 
    397  
    398     :param has_class: Tells whether to consider the class variable 
    399     :type has_class: bool 
    400     :rtype: bool 
     389    Return :obj:`True` if the domain has any variables which are 
     390    neither discrete nor continuous, such as, for instance string variables. 
     391    class is included unless ``include_class`` is ``False``. 
     392 
     393    :param has_class: Tells whether to consider the class variable 
     394    :type has_class: bool 
     395    :rtype: bool 
    401396 
    402397 
    403398     .. method:: add_meta(id, variable, optional=0) 
    404399 
    405     Register a meta attribute with the given id (obtained by 
    406     :obj:`Orange.data.new_meta_id`). The same meta attribute should 
    407     have the same id in all domain in which it is registered. :: 
    408  
    409          >>> newid = Orange.data.new_meta_id() 
    410          >>> domain.add_meta(newid, Orange.data.variable.String("origin")) 
    411          >>> data[55]["origin"] = "Nepal" 
    412          >>> data[55] 
    413          ['1', '0', '0', '1', '0', '0', '0', '1', '1', '1', '0', '0', 
    414          '4', '1', '0', '1', 'mammal'], {"name":'oryx', "origin":'Nepal'} 
    415  
    416     The third argument tells whether the meta attribute is optional or 
    417     not. The parameter is an integer, with any non-zero value meaning that 
    418     the attribute is optional. Different values can be used to distinguish 
    419     between various types optional attributes; the meaning of the value 
    420     is not defined in advance and can be used arbitrarily by the 
    421     application. 
    422  
    423     :param id: id of the new meta attribute 
    424     :type id: int 
    425     :param variable: variable descriptor 
    426     :type variable: Orange.data.variable.Variable 
    427     :param optional: tells whether the meta attribute is optional 
    428     :type optional: int 
     400    Register a meta attribute with the given id (obtained by 
     401    :obj:`Orange.data.new_meta_id`). The same meta attribute should 
     402    have the same id in all domain in which it is registered. :: 
     403 
     404         >>> newid = Orange.data.new_meta_id() 
     405         >>> domain.add_meta(newid, Orange.data.variable.String("origin")) 
     406         >>> data[55]["origin"] = "Nepal" 
     407         >>> data[55] 
     408         ['1', '0', '0', '1', '0', '0', '0', '1', '1', '1', '0', '0', 
     409         '4', '1', '0', '1', 'mammal'], {"name":'oryx', "origin":'Nepal'} 
     410 
     411    The third argument tells whether the meta attribute is optional or 
     412    not. The parameter is an integer, with any non-zero value meaning that 
     413    the attribute is optional. Different values can be used to distinguish 
     414    between various types optional attributes; the meaning of the value 
     415    is not defined in advance and can be used arbitrarily by the 
     416    application. 
     417 
     418    :param id: id of the new meta attribute 
     419    :type id: int 
     420    :param variable: variable descriptor 
     421    :type variable: Orange.data.variable.Variable 
     422    :param optional: tells whether the meta attribute is optional 
     423    :type optional: int 
    429424 
    430425     .. method:: add_metas(attributes, optional=0) 
    431426 
    432     Add multiple meta attributes at once. The dictionary contains id's as 
    433     keys and variables (:obj:~Orange.data.variable as the corresponding 
    434     values. The following example shows how to add all meta attributes 
    435     from one domain to another:: 
    436  
    437           newdomain.add_metas(domain.get_metas()) 
    438  
    439     The optional second argument has the same meaning as in :obj:`add_meta`. 
    440  
    441     :param attributes: dictionary of id's and variables 
    442     :type attributes: dict 
    443     :param optional: tells whether the meta attribute is optional 
    444     :type optional: int 
     427    Add multiple meta attributes at once. The dictionary contains id's as 
     428    keys and variables (:obj:~Orange.data.variable as the corresponding 
     429    values. The following example shows how to add all meta attributes 
     430    from one domain to another:: 
     431 
     432          newdomain.add_metas(domain.get_metas()) 
     433 
     434    The optional second argument has the same meaning as in :obj:`add_meta`. 
     435 
     436    :param attributes: dictionary of id's and variables 
     437    :type attributes: dict 
     438    :param optional: tells whether the meta attribute is optional 
     439    :type optional: int 
    445440 
    446441     .. method:: remove_meta(attribute) 
    447442 
    448     Removes one or multiple meta attributes. Removing a meta attribute has 
    449     no effect on data instances. 
    450  
    451     :param attribute: attribute(s) to be removed, given as name, id, variable descriptor or a list of them 
    452     :type attribute: string, int, Orange.data.variable.Variable; or a list 
     443    Removes one or multiple meta attributes. Removing a meta attribute has 
     444    no effect on data instances. 
     445 
     446    :param attribute: attribute(s) to be removed, given as name, id, variable descriptor or a list of them 
     447    :type attribute: string, int, Orange.data.variable.Variable; or a list 
    453448 
    454449     .. method:: has_attribute(attribute) 
    455450 
    456     Return True if the domain contains the specified meta attribute. 
    457  
    458     :param attribute: attribute to be checked 
    459     :type attribute: string, int, Orange.data.variable.Variable 
    460     :rtype: bool 
     451    Return True if the domain contains the specified meta attribute. 
     452 
     453    :param attribute: attribute to be checked 
     454    :type attribute: string, int, Orange.data.variable.Variable 
     455    :rtype: bool 
    461456 
    462457     .. method:: meta_id(attribute) 
    463458 
    464     Return an id of a meta attribute. 
    465  
    466     :param attribute: name or variable descriptor of the attribute 
    467     :type attribute: string or Orange.data.variable.Variable 
    468     :rtype: int 
     459    Return an id of a meta attribute. 
     460 
     461    :param attribute: name or variable descriptor of the attribute 
     462    :type attribute: string or Orange.data.variable.Variable 
     463    :rtype: int 
    469464 
    470465     .. method:: get_meta(attribute) 
    471466 
    472     Return a variable descriptor corresponding to the meta attribute. 
    473  
    474     :param attribute: name or id of the attribute 
    475     :type attribute: string or int 
    476     :rtype: Orange.data.variable.Variable 
     467    Return a variable descriptor corresponding to the meta attribute. 
     468 
     469    :param attribute: name or id of the attribute 
     470    :type attribute: string or int 
     471    :rtype: Orange.data.variable.Variable 
    477472 
    478473     .. method:: get_metas() 
    479474 
    480       Return a dictionary with meta attribute id's as keys and corresponding 
    481       variable descriptors as values. 
     475      Return a dictionary with meta attribute id's as keys and corresponding 
     476      variable descriptors as values. 
    482477 
    483478     .. method:: get_metas(optional) 
    484479 
    485       Return a dictionary with meta attribute id's as keys and corresponding 
    486       variable descriptors as values. The dictionary contains only meta 
    487       attributes for which the argument ``optional`` matches the flag given 
    488       when the attributes were added using :obj:`add_meta` or :obj:`add_metas`. 
    489  
    490       :param optional: flag that specifies the attributes to be returned 
    491       :type optional: int 
    492       :rtype: dict 
     480      Return a dictionary with meta attribute id's as keys and corresponding 
     481      variable descriptors as values. The dictionary contains only meta 
     482      attributes for which the argument ``optional`` matches the flag given 
     483      when the attributes were added using :obj:`add_meta` or :obj:`add_metas`. 
     484 
     485      :param optional: flag that specifies the attributes to be returned 
     486      :type optional: int 
     487      :rtype: dict 
    493488 
    494489     .. method:: is_optional_meta(attribute) 
    495490 
    496     Return True if the given meta attribute is optional, and False if it is 
    497     not. 
    498  
    499     :param attribute: attribute to be checked 
    500     :type attribute: string, int, Orange.data.variable.Variable 
    501     :rtype: bool 
     491    Return True if the given meta attribute is optional, and False if it is 
     492    not. 
     493 
     494    :param attribute: attribute to be checked 
     495    :type attribute: string, int, Orange.data.variable.Variable 
     496    :rtype: bool 
Note: See TracChangeset for help on using the changeset viewer.