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:

dictionaryDictionaryDomain

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:

• samples.export_dictionary_files()

• samples.train_predictor_with_cross_validation()

• samples.multiple_train_predictor()

• samples.deploy_model_expert()