core.dictionary#
Submodule of khiops.core
Classes to manipulate Khiops Dictionary files
Note
To have a complete illustration of the access to the information of all classes in
this module look at their write
methods which write them in Khiops Dictionary
file format (.kdic
).
Functions#
Reads a Khiops dictionary file |
Classes#
A Khiops Dictionary |
|
Main class containing the information of a Khiops dictionary file |
|
A metadata container for a dictionary, a variable or variable block |
|
A variable of a Khiops dictionary |
|
A variable block of a Khiops dictionary |
- class khiops.core.dictionary.Dictionary(json_data=None)#
Bases:
object
A Khiops Dictionary
A Khiops Dictionary is a description of a table transformation. Common uses in the Khiops framework are :
Describing the schema of an input table: In this case it is the identity transformation of the table(s).
Describing a predictor (classifier or regressor): In this case it is the transformation between the original table(s) and the prediction values or probabilities.
- Parameters:
- json_datadict, optional
Python dictionary representing an element of the list at the
dictionaries
field of a Khiops Dictionary JSON file. If not specified returns an empty instance.
- Attributes:
- namestr
Dictionary name.
- labelstr
Dictionary label/comment.
- rootbool
True if the dictionary is the root of an dictionary hierarchy.
- keylist of str
Names of the key variables.
- meta_data
MetaData
MetaData object of the dictionary.
- variableslist of
Variable
The dictionary variables.
- variable_blockslist of
VariableBlock
The dictionary variable blocks.
- add_variable(variable)#
Adds a variable to this dictionary
- Parameters:
- variable
Variable
The variable to be added.
- variable
- Raises:
TypeError
If variable is not of type
Variable
ValueError
If the name is empty or if there is already a variable with that name.
- add_variable_block(variable_block)#
Adds a variable block to this dictionary
- Parameters:
- variable_block
VariableBlock
The variable block to be added.
- variable_block
- Raises:
TypeError
If variable is not of type
VariableBlock
ValueError
If the name is empty or if there is already a variable block with that name.
- copy()#
Returns a copy of this instance
- Returns:
Dictionary
A copy of this instance.
- get_value(key)#
Returns the metadata value associated to the specified key
- Raises:
KeyError
If the key is not found
- get_variable(variable_name)#
Returns the specified variable
- get_variable_block(variable_block_name)#
Returns the specified variable block
- Parameters:
- variable_block_namestr
A name of a variable block.
- Returns:
VariableBlock
The specified variable.
- Raises:
KeyError
If no variable block with the specified name exists.
- is_key_variable(variable)#
Returns
True
if a variable belongs to this dictionary’s key- Parameters:
- variable
Variable
The variable for the query.
- variable
- Returns:
- bool
True
if the variable belong to the key.
- remove_variable(variable_name)#
Removes the specified variable from this dictionary
- remove_variable_block(variable_block_name, keep_native_block_variables=True)#
Removes the specified variable block from this dictionary
Note
Non-native block variables (those created from block rules) are never kept in the dictionary.
- Parameters:
- variable_namestr
Name of the variable block to be removed.
- keep_native_block_variablesbool, default
True
If
True
and the block is native then only the block structure is removed from the dictionary but the variables are kept in it; neither the variables point to the block nor the removed block points to the variables. IfFalse
the variables are removed from the dictionary; the block preserves the references to their variables.
- Returns:
VariableBlock
The removed variable block.
- Raises:
KeyError
If no variable block with the specified name exists.
- use_all_variables(is_used)#
Sets the
used
flag of all dictionary variables to the specified value- Parameters:
- is_usedbool
Sets the
used
field tois_used
for all theVariable
objects in this dictionary.
- write(writer)#
Writes the dictionary to a file writer in
.kdic
format- Parameters:
- writer
KhiopsOutputWriter
Output dictionary file.
- writer
- class khiops.core.dictionary.DictionaryDomain(json_data=None)#
Bases:
KhiopsJSONObject
Main class containing the information of a Khiops dictionary file
A DictionaryDomainain is a collection of
Dictionary
objects. These dictionaries usually represent either a database schema or a predictor model.- Parameters:
- json_datadict, optional
Python dictionary representing the data of a Khiops Dictionary JSON file. If not specified it returns an empty instance.
Note
Prefer the
read_dictionary_file
function from the core API to obtain an instance of this class from a Khiops Dictionary file (kdic
orkdicj
).
- Attributes:
- toolstr
Name of the Khiops tool that generated the dictionary file.
- versionstr
Version of the Khiops tool that generated the dictionary file.
- dictionarieslist of
Dictionary
The domain’s dictionaries.
- add_dictionary(dictionary)#
Adds a dictionary to this domain
- Parameters:
- dictionary
DictionaryDomain
The dictionary to be added.
- dictionary
- Raises:
TypeError
If
dictionary
is not of typeDictionary
.
- copy()#
Copies this domain instance
- Returns:
DictionaryDomain
A copy of this instance.
- export_khiops_dictionary_file(kdic_file_path)#
Exports the domain in
.kdic
format- Parameters:
- kdic_file_pathstr
Path of the output dictionary file (
.kdic
).
- extract_data_paths(source_dictionary_name)#
Extracts the data paths for a dictionary in a multi-table schema
See Multi-Table Learning Primer for more details about data paths.
- Parameters:
- source_dictionary_namestr
Name of a dictionary.
- Returns:
- list of str
The additional data paths for the secondary tables of the specified dictionary.
- get_dictionary(dictionary_name)#
Returns the specified dictionary
- Parameters:
- dictionary_namestr
Name of the dictionary.
- Returns:
Dictionary
The specified dictionary.
- Raises:
KeyError
If no dictionary with the specified name exist.
- get_dictionary_at_data_path(data_path)#
Returns the dictionary name for the specified data path
- Parameters:
- data_pathstr
A data path for the specified table. Usually the output of
extract_data_paths
.
- Returns:
Dictionary
The dictionary object pointed by this data path.
- Raises:
ValueError
If the path is not found.
- remove_dictionary(dictionary_name)#
Removes a dictionary from the domain
- Returns:
Dictionary
The removed dictionary.
- Raises:
KeyError
If no dictionary with the specified name exists.
- write(stream_or_writer)#
Writes the domain to a file writer in
.kdic
format- Parameters:
- stream_or_writer
io.IOBase
orKhiopsOutputWriter
Output stream or writer.
- stream_or_writer
- class khiops.core.dictionary.MetaData(json_data=None)#
Bases:
object
A metadata container for a dictionary, a variable or variable block
The metadata for both dictionaries and variables is a list of key-value pairs. The values can be set either to a string, to a number, or to the boolean value True. The latter represents flag metadata: they are either present (
True
) or absent.- Parameters:
- json_datadict, optional
Python dictionary representing the object at a
metaData
field of a dictionary domain, dictionary or variable in a Khiops Dictionary JSON file. If None it returns an empty instance.
- Attributes:
- keyslist of str
The metadata keys.
- valueslist
Metadata values for each key in
keys
(synchronized lists). They can be either str, int or float.
- add_value(key, value)#
Adds a value at the specified key
- Parameters:
- keystr
Key to be added. A valid key is a sequence of non-accented alphanumeric characters which starts with a non-numeric character.
- valuebool, int, float or str
Value to be added.
- Raises:
TypeError
If the key is not a valid string
If the value is not a valid string or if is not bool, int, float.
ValueError
If the key is already stored.
- get_value(key)#
Returns the value at the specified key
- is_empty()#
Returns
True
if the meta-data is empty- Returns:
- bool
Returns
True
if the meta-data is empty
- remove_key(key)#
Removes the value at the specified key
- write(writer)#
Writes the metadata to a file writer in
.kdic
format- Parameters:
- writer
KhiopsOutputWriter
Output writer.
- writer
- class khiops.core.dictionary.Variable(json_data=None)#
Bases:
object
A variable of a Khiops dictionary
- Parameters:
- json_datadict, optional
Python dictionary representing an element of the list at the
variables
field of dictionaries found in a Khiops Dictionary JSON file. If not specified it returns an empty instance.
- Attributes:
- namestr
Variable name.
- labelstr
Variable label/comment.
- usedbool
True if the variable is used.
- typestr
Variable type.
- object_typestr
Type complement for the
Table
andEntity
types.- structure_typestr
Type complement for the
Structure
type. Set to “” for other types.- rulestr
Derivation rule. Set to “” if there is no rule associated to this variable.
- meta_data
MetaData
Variable metadata.
- variable_block
VariableBlock
Block to which the variable belongs. Not set if the variable does not belong to a block.
- full_type()#
Returns the variable’s full type
- Returns:
- str
The full type is the variable type plus its complement if the type is not basic.
- get_value(key)#
Returns the metadata value associated to the specified key
- Raises:
KeyError
If no metadata has this key.
- is_native()#
Returns
True
if the variable comes directly from a data columnVariables are not native if they come from a derivation rule, an external entity, a sub-table or structures.
- Returns:
- bool
True
if a variables comes directly from a data column.
- is_reference_rule()#
Returns
True
if the special reference rule is usedThe reference rule is used to make reference to an external entity.
- Returns:
- bool
True
if the special reference rule is used.
- is_relational()#
Returns
True
if the variable is of relational typeRelational variables reference other tables or external entities.
- Returns:
- bool
True if the variable is of relational type.
- write(writer)#
Writes the domain to a file writer in
.kdic
format- Parameters:
- writer
KhiopsOutputWriter
Output writer.
- writer
- class khiops.core.dictionary.VariableBlock(json_data=None)#
Bases:
object
A variable block of a Khiops dictionary
- Parameters:
- json_datadict, optional
Python dictionary representing an element of the list at the
variables
field of a dictionary object in a Khiops Dictionary JSON file. The element must have ablockName
field. If not specified it returns an empty instance.
- Attributes:
- name
Block name.
- label
Block label/commentary.
- rule
Block derivation rule.
- meta_data
Metadata object of the block.
- variables
List of the Variable objects of the block.
- add_variable(variable)#
Adds a variable to this block
- get_value(key)#
Returns the metadata value associated to the specified key
- Raises:
KeyError
If
key
is not found
- remove_variable(variable)#
Removes a variable from this block
- write(writer)#
Writes the variable block to a file writer in
.kdic
format- Parameters:
- writer
KhiopsOutputWriter
Output writer.
- writer
- khiops.core.dictionary.read_dictionary_file(dictionary_file_path)#
Reads a Khiops dictionary file
- Parameters:
- dictionary_filestr
Path of the file to be imported. The file can be either Khiops Dictionary (extension
kdic
) or Khiops JSON Dictionary (extension.json
or.kdicj
).
- Returns:
DictionaryDomain
An dictionary domain representing the information in the dictionary file.
- Raises:
ValueError
When the file has an extension other than
.kdic
,.kdicj
or.json
.
Examples
- See the following functions of the
samples.py
documentation script: