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¶

read_dictionary_file

Reads a Khiops dictionary file

Classes¶

`Dictionary`	A Khiops Dictionary
`DictionaryDomain`	Main class containing the information of a Khiops dictionary file
`MetaData`	A metadata container for a dictionary, a variable or variable block
`Variable`	A variable of a Khiops dictionary
`VariableBlock`	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_dataMetaData: 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:

variableVariable: The variable to be added.

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_blockVariableBlock: The variable block to be added.

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

Parameters:

variable_namestr: A name of a variable.

Returns:

Variable: The specified variable.

Raises:

KeyError: If no variable with the specified name exists.

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:

variableVariable: The variable for the query.

Returns:

bool: True if the variable belong to the key.

remove_variable(variable_name)¶

Removes the specified variable from this dictionary

Parameters:

variable_namestr: Name of the variable to be removed.

Returns:

Variable: The removed variable.

Raises:

KeyError: If no variable with the specified name exists.

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. If False 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 to is_used for all the Variable objects in this dictionary.

write(writer)¶

Writes the dictionary to a file writer in .kdic format

Parameters:

writerKhiopsOutputWriter: Output dictionary file.

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 or kdicj).

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:

dictionaryDictionary: The dictionary to be added.

Raises:

TypeError: If dictionary is not of type Dictionary.

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_writerio.IOBase or KhiopsOutputWriter: Output 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.

copy()¶

Copies this metadata instance

Returns:

MetaData: A copy of this instance.

get_value(key)¶

Returns the value at the specified key

Returns:

int, str or float: The value at the specified key

Raises:

TypeError: If key is not str.
KeyError: If key is not found.

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

Parameters:

keystr: The key to be removed.

Returns:

bool, int, float, str: The value associated to the key removed.

Raises:

TypeError: If the key is not str.
KeyError: If the key is not contained in this metadata.

write(writer)¶

Writes the metadata to a file writer in .kdic format

Parameters:

writerKhiopsOutputWriter: Output 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 and Entity 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_dataMetaData: Variable metadata.
variable_blockVariableBlock: Block to which the variable belongs. Not set if the variable does not belong to a block.

copy()¶

Copies this variable instance

Returns:

Variable: A copy of this instance.

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 column

Variables 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 used

The 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 type

Relational 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:

writerKhiopsOutputWriter: Output 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 a blockName 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

Parameters:

variableVariable: The variable to be added.

Raises:

TypeError: If the variable is not of type Variable.

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

Parameters:

variableVariable: The variable to be removed.

Raises:

TypeError: If the variable is not of type Variable.

write(writer)¶

Writes the variable block to a file writer in .kdic format

Parameters:

writerKhiopsOutputWriter: Output 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: