khiops.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).
| CLASS | DESCRIPTION |
|---|---|
DictionaryDomain |
Main class containing the information of a Khiops dictionary file |
Dictionary |
A Khiops Dictionary |
Variable |
A variable of a Khiops dictionary |
VariableBlock |
A variable block of a Khiops dictionary |
Rule |
A rule of a variable or variable block in a Khiops dictionary |
MetaData |
A metadata container for a dictionary, a variable or variable block |
| FUNCTION | DESCRIPTION |
|---|---|
read_dictionary_file |
Reads a Khiops dictionary file |
upper_scope |
Applies the upper-scope operator |
Classes
DictionaryDomain(json_data=None)
Main class containing the information of a Khiops dictionary file
A DictionaryDomain is a collection of Dictionary objects. These
dictionaries
usually represent either a database schema or a predictor model.
| PARAMETER | DESCRIPTION |
|---|---|
json_data
|
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 (
TYPE:
|
| ATTRIBUTE | DESCRIPTION |
|---|---|
tool |
Name of the Khiops tool that generated the dictionary file.
TYPE:
|
version |
Version of the Khiops tool that generated the dictionary file.
TYPE:
|
dictionaries |
The domain's dictionaries.
TYPE:
|
See class docstring
| METHOD | DESCRIPTION |
|---|---|
__repr__ |
Returns a human readable string representation |
copy |
Copies this domain instance |
get_dictionary |
Returns the specified dictionary |
add_dictionary |
Adds a dictionary to this domain |
remove_dictionary |
Removes a dictionary from the domain |
extract_data_paths |
Extracts the data paths for a dictionary in a multi-table schema |
get_dictionary_at_data_path |
Returns the dictionary name for the specified data path |
export_khiops_dictionary_file |
Exports the domain in |
write |
Writes the domain to a file writer in |
Methods:
__repr__()
Returns a human readable string representation
copy()
Copies this domain instance
| RETURNS | DESCRIPTION |
|---|---|
DictionaryDomain
|
A copy of this instance. |
get_dictionary(dictionary_name)
Returns the specified dictionary
| PARAMETER | DESCRIPTION |
|---|---|
dictionary_name
|
Name of the dictionary.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Dictionary
|
The specified dictionary. |
add_dictionary(dictionary)
Adds a dictionary to this domain
| PARAMETER | DESCRIPTION |
|---|---|
dictionary
|
The dictionary to be added.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If |
remove_dictionary(dictionary_name)
Removes a dictionary from the domain
| RETURNS | DESCRIPTION |
|---|---|
Dictionary
|
The removed dictionary. |
| RAISES | DESCRIPTION |
|---|---|
KeyError
|
If no dictionary with the specified name exists. |
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.
| PARAMETER | DESCRIPTION |
|---|---|
source_dictionary_name
|
Name of a dictionary.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list of str
|
The additional data paths for the secondary tables of the specified dictionary. |
get_dictionary_at_data_path(data_path)
Returns the dictionary name for the specified data path
| PARAMETER | DESCRIPTION |
|---|---|
data_path
|
A data path for the specified table. Usually the output of extract_data_paths.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Dictionary
|
The dictionary object pointed by this data path. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If the path is not found. |
export_khiops_dictionary_file(kdic_file_path)
Exports the domain in .kdic format
| PARAMETER | DESCRIPTION |
|---|---|
kdic_file_path
|
Path of the output dictionary file (
TYPE:
|
write(stream_or_writer)
Writes the domain to a file writer in .kdic format
| PARAMETER | DESCRIPTION |
|---|---|
stream_or_writer
|
Output stream or writer.
TYPE:
|
Dictionary(json_data=None)
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.
| PARAMETER | DESCRIPTION |
|---|---|
json_data
|
Python dictionary representing an element of the list at the
TYPE:
|
| ATTRIBUTE | DESCRIPTION |
|---|---|
name |
Dictionary name.
TYPE:
|
root |
True if the dictionary is the root of an dictionary hierarchy.
TYPE:
|
key |
Names of the key variables.
TYPE:
|
variables |
The dictionary variables.
TYPE:
|
variable_blocks |
The dictionary variable blocks.
TYPE:
|
label |
Dictionary label.
TYPE:
|
comments |
List of dictionary comments.
TYPE:
|
internal_comments |
List of internal dictionary comments.
TYPE:
|
meta_data |
MetaData object of the dictionary.
TYPE:
|
See class docstring
| METHOD | DESCRIPTION |
|---|---|
__repr__ |
Returns a human readable string representation |
copy |
Returns a copy of this instance |
get_value |
Returns the metadata value associated to the specified key |
use_all_variables |
Sets the |
get_variable |
Returns the specified variable |
get_variable_block |
Returns the specified variable block |
add_variable |
Adds a variable to this dictionary |
add_variable_from_spec |
Adds a variable to this dictionary using a complete specification |
remove_variable |
Removes the specified variable from this dictionary |
add_variable_block |
Adds a variable block to this dictionary |
remove_variable_block |
Removes the specified variable block from this dictionary |
is_key_variable |
Returns |
write |
Writes the dictionary to a file writer in |
Methods:
__repr__()
Returns a human readable string representation
copy()
Returns a copy of this instance
| RETURNS | DESCRIPTION |
|---|---|
Dictionary
|
A copy of this instance. |
get_value(key)
Returns the metadata value associated to the specified key
| RETURNS | DESCRIPTION |
|---|---|
MetaData
|
Metadata value associated to the specified key. |
use_all_variables(is_used)
get_variable(variable_name)
get_variable_block(variable_block_name)
Returns the specified variable block
| PARAMETER | DESCRIPTION |
|---|---|
variable_block_name
|
A name of a variable block.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
VariableBlock
|
The specified variable block. |
add_variable(variable)
Adds a variable to this dictionary
| PARAMETER | DESCRIPTION |
|---|---|
variable
|
The variable to be added.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
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_from_spec(name, type, label='', used=True, object_type=None, structure_type=None, rule=None, meta_data=None)
Adds a variable to this dictionary using a complete specification
| PARAMETER | DESCRIPTION |
|---|---|
name
|
Variable name.
TYPE:
|
type
|
Variable type. See Variable.
TYPE:
|
label
|
Label of the variable.
TYPE:
|
used
|
Usage status of the variable.
TYPE:
|
object_type
|
Object type. Ignored if variable type not in ["Entity", "Table"].
TYPE:
|
structure_type
|
Structure type. Ignored if variable type is not "Structure".
TYPE:
|
rule
|
String representation of a variable rule.
TYPE:
|
meta_data
|
A Python dictionary which holds the metadata specification. The dictionary keys are str. The values can be str, bool, float or int.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
|
remove_variable(variable_name)
add_variable_block(variable_block)
Adds a variable block to this dictionary
| PARAMETER | DESCRIPTION |
|---|---|
variable_block
|
The variable block to be added.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
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. |
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.
| PARAMETER | DESCRIPTION |
|---|---|
variable_block_name
|
Name of the variable block to be removed.
TYPE:
|
keep_native_block_variables
|
If
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
VariableBlock
|
The removed variable block. |
| RAISES | DESCRIPTION |
|---|---|
KeyError
|
If no variable block with the specified name exists. |
is_key_variable(variable)
write(writer)
Writes the dictionary to a file writer in .kdic format
| PARAMETER | DESCRIPTION |
|---|---|
writer
|
Output dictionary file.
TYPE:
|
Variable(json_data=None)
A variable of a Khiops dictionary
| PARAMETER | DESCRIPTION |
|---|---|
json_data
|
Python dictionary representing an element of the list at the
TYPE:
|
| ATTRIBUTE | DESCRIPTION |
|---|---|
name |
Variable name.
TYPE:
|
used |
True if the variable is used.
TYPE:
|
type |
Variable type.
It can be either native ( or relational (
TYPE:
|
object_type |
Type complement for the
TYPE:
|
structure_type |
Type complement for the
TYPE:
|
rule |
Derivation rule or external table reference. Set to "" if there is no rule associated to this variable. Examples:
TYPE:
|
variable_block |
Block to which the variable belongs. Not set if the variable does not belong to a block.
TYPE:
|
label |
Variable label.
TYPE:
|
comments |
List of variable comments.
TYPE:
|
meta_data |
Variable metadata.
TYPE:
|
Examples:
See the following function of the samples.py documentation script:
- samples.create_dictionary_domain()
See class docstring
| METHOD | DESCRIPTION |
|---|---|
__repr__ |
Returns a human-readable string representation |
copy |
Copies this variable instance |
get_value |
Returns the metadata value associated to the specified key |
is_native |
Returns |
is_relational |
Returns |
is_reference_rule |
Returns |
full_type |
Returns the variable's full type |
write |
Writes the domain to a file writer in |
Methods:
__repr__()
Returns a human-readable string representation
copy()
Copies this variable instance
| RETURNS | DESCRIPTION |
|---|---|
Variable
|
A copy of this instance. |
get_value(key)
Returns the metadata value associated to the specified key
| RETURNS | DESCRIPTION |
|---|---|
MetaData
|
Metadata value associated to the specified 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 | DESCRIPTION |
|---|---|
bool
|
|
is_relational()
Returns True if the variable is of relational type
Relational variables reference other tables or external entities.
| RETURNS | DESCRIPTION |
|---|---|
bool
|
True if the variable is of relational type. |
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 | DESCRIPTION |
|---|---|
bool
|
|
full_type()
Returns the variable's full type
| RETURNS | DESCRIPTION |
|---|---|
str
|
The full type is the variable type plus its complement if the type is not basic. |
write(writer)
Writes the domain to a file writer in .kdic format
| PARAMETER | DESCRIPTION |
|---|---|
writer
|
Output writer.
TYPE:
|
VariableBlock(json_data=None)
A variable block of a Khiops dictionary
| PARAMETER | DESCRIPTION |
|---|---|
json_data
|
Python dictionary representing an element of the list at the
TYPE:
|
| ATTRIBUTE | DESCRIPTION |
|---|---|
name |
Block name.
TYPE:
|
rule |
Block derivation rule.
|
variables |
List of the Variable objects of the block.
|
label |
Block label.
TYPE:
|
comments |
List of block comments.
TYPE:
|
internal_comments |
List of internal block comments.
TYPE:
|
meta_data |
Metadata object of the block.
|
See class docstring
| METHOD | DESCRIPTION |
|---|---|
__repr__ |
Returns a human readable string representation |
add_variable |
Adds a variable to this block |
remove_variable |
Removes a variable from this block |
get_value |
Returns the metadata value associated to the specified key |
write |
Writes the variable block to a file writer in |
Methods:
__repr__()
Returns a human readable string representation
add_variable(variable)
remove_variable(variable)
get_value(key)
Returns the metadata value associated to the specified key
| RETURNS | DESCRIPTION |
|---|---|
MetaData
|
Metadata value associated to the specified key. |
write(writer)
Writes the variable block to a file writer in .kdic format
| PARAMETER | DESCRIPTION |
|---|---|
writer
|
Output writer.
TYPE:
|
Rule(*name_and_operands, verbatim=None, is_reference=False)
A rule of a variable or variable block in a Khiops dictionary
This object is a convenience feature which eases rule creation and serialization, especially in complex cases (rule operands which are variables or rules themselves, sometimes upper-scoped). A Rule instance must be converted to str before setting it in a Variable or VariableBlock instance.
Rule instances can be created either from full operand specifications, or from verbatim rules. The latter is useful when the rule is retrieved from an existing variable or variable block and is used as an operand in another rule.
| PARAMETER | DESCRIPTION |
|---|---|
name_and_operands
|
Each tuple member can have one of the following types: The first element of the
TYPE:
|
verbatim
|
Verbatim representation of an entire rule. If set, then |
is_reference
|
If set to
TYPE:
|
| ATTRIBUTE | DESCRIPTION |
|---|---|
name |
Name of the rule. It is
TYPE:
|
operands |
Each operand has one of the following types:
TYPE:
|
is_reference |
The reference status of the rule. Note This attribute cannot be changed on a Rule instance.
TYPE:
|
Examples:
-
basic rule, with variables as operands:
-
verbatim:
-
object construction:
-
-
multi-table rule:
-
verbatim:
-
object construction:
-
-
multi-table rule with upper-scoped operands (advanced usage):
-
verbatim:
-
object construction:
vehicles_var = accidents_dictionary.get_variable("Vehicles") passenger_number_var = vehicles_dictionary.get_variable( "PassengerNumber" ) rule = kh.Rule( "TableSelection", vehicles_var, kh.Rule( "EQ", passenger_number_var, kh.upper_scope( kh.Rule( "TableMax", vehicle_var, passenger_number_var ) ) ) )
-
See class docstring
| METHOD | DESCRIPTION |
|---|---|
copy |
Copies this rule instance |
write |
Writes the rule to a file writer in the |
Methods:
copy()
Copies this rule instance
| RETURNS | DESCRIPTION |
|---|---|
Rule
|
A copy of this instance. |
write(writer)
Writes the rule to a file writer in the .kdic format
This method ensures proper Rule serialization, automatically handling:
- back-quote recoding in variable names
- double-quote recoding in categorical constants
- missing data (`inf`, `-inf`, `NaN`) serialization as `#Missing`
- upper-scope operator serialization as `.`
| PARAMETER | DESCRIPTION |
|---|---|
writer
|
Output writer. Note
TYPE:
|
MetaData(json_data=None)
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.
| PARAMETER | DESCRIPTION |
|---|---|
json_data
|
Python dictionary representing the object at a
TYPE:
|
| ATTRIBUTE | DESCRIPTION |
|---|---|
keys |
The metadata keys.
TYPE:
|
values |
Metadata values for each key in
TYPE:
|
See class docstring
| METHOD | DESCRIPTION |
|---|---|
copy |
Copies this metadata instance |
is_empty |
Returns |
get_value |
Returns the value at the specified key |
add_value |
Adds a value at the specified key |
remove_key |
Removes the value at the specified key |
write |
Writes the metadata to a file writer in |
Methods:
copy()
Copies this metadata instance
| RETURNS | DESCRIPTION |
|---|---|
MetaData
|
A copy of this instance. |
is_empty()
Returns True if the meta-data is empty
| RETURNS | DESCRIPTION |
|---|---|
bool
|
Returns |
get_value(key)
add_value(key, value)
Adds a value at the specified key
| PARAMETER | DESCRIPTION |
|---|---|
key
|
Key to be added. A valid key is a sequence of non-accented alphanumeric characters which starts with a non-numeric character.
TYPE:
|
value
|
Value to be added. |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
|
ValueError
|
If the key is already stored. |
remove_key(key)
write(writer)
Writes the metadata to a file writer in .kdic format
| PARAMETER | DESCRIPTION |
|---|---|
writer
|
Output writer.
TYPE:
|
Functions:
read_dictionary_file(dictionary_file_path)
Reads a Khiops dictionary file
| PARAMETER | DESCRIPTION |
|---|---|
dictionary_file_path
|
Path of the file to be imported. The file can be either Khiops Dictionary
(extension
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
DictionaryDomain
|
An dictionary domain representing the information in the dictionary file. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
When the file has an extension other than |
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()
upper_scope(operand)
Applies the upper-scope operator . to an operand
| PARAMETER | DESCRIPTION |
|---|---|
operand
|
Operand that is upper-scoped.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
| RETURNS | DESCRIPTION |
|---|---|
upper-scoped operand
|
The upper-scoped operand, as if the upper-scope operator |