core.api

Submodule of khiops.core

API for the execution of the Khiops AutoML suite

The methods in this module allow to execute all Khiops and Khiops Coclustering tasks.

See also:

• Common Parameters

• Input Types

• Database Sampling

• Samples Directory Customization

Functions

build_deployed_dictionary	Builds a dictionary file to read the output table of a deployed model
build_dictionary_from_data_table	Builds a dictionary file by analyzing a data table file
check_database	Checks if a data table is compatible with a dictionary file
deploy_model	Deploys a model on a data table
detect_data_table_format	Detects the format of a data table
evaluate_predictor	Evaluates the predictors in a dictionary file on a database
export_dictionary_as_json	Exports a Khiops dictionary file to JSON format (.kdicj)
extract_clusters	Extracts clusters to a tab separated (TSV) file
extract_keys_from_data_table	Extracts from data table unique occurrences of a key variable
get_khiops_version	Returns the Khiops version
get_samples_dir	Returns the Khiops' samples directory path
interpret_predictor	Builds an interpretation dictionary from a predictor
prepare_coclustering_deployment	Prepares a individual-variable coclustering deployment
reinforce_predictor	Builds a reinforced predictor from a predictor
simplify_coclustering	Simplifies a coclustering model
sort_data_table	Sorts a data table
train_coclustering	Trains a coclustering model from a data table
train_instance_variable_coclustering	Trains an instance-variable coclustering model from a data table .. note::.
train_predictor	Trains a model from a data table
train_recoder	Trains a recoding model from a data table

khiops.core.api.build_deployed_dictionary(dictionary_file_path_or_domain, dictionary_name, output_dictionary_file_path, log_file_path=None, output_scenario_path=None, task_file_path=None, trace=False, stdout_file_path='', stderr_file_path='', max_cores=None, memory_limit_mb=None, temp_dir='', scenario_prologue='', **kwargs)

Builds a dictionary file to read the output table of a deployed model

Parameters:

dictionary_file_path_or_domainstr or DictionaryDomain

Path of a Khiops dictionary file or a DictionaryDomain object.

dictionary_namestr

Name of the dictionary to be analyzed.

output_dictionary_file_pathstr

Path of the output dictionary file.

…

See Common Parameters.

Raises:

TypeError

Invalid type of an argument

Examples

See the following functions of the samples.py documentation script:

• samples.build_deployed_dictionary()

khiops.core.api.build_dictionary_from_data_table(data_table_path, output_dictionary_name, output_dictionary_file_path, detect_format=True, header_line=None, field_separator=None, log_file_path=None, output_scenario_path=None, task_file_path=None, trace=False, stdout_file_path='', stderr_file_path='', max_cores=None, memory_limit_mb=None, temp_dir='', scenario_prologue='', **kwargs)

Builds a dictionary file by analyzing a data table file

Parameters:

data_table_pathstr

Path of the data table file.

output_dictionary_namestr

Name dictionary to be created.

output_dictionary_file_pathstr

Path of the output dictionary file.

detect_formatbool, default True

If True detects automatically whether the data table file has a header and its field separator. It is set to False if header_line or field_separator are set.

header_linebool, optional (default True)

If True it uses the first line of the data as column names. Sets detect_format to False if set. Ignored if detect_format is True.

field_separatorstr, optional (default “\t”)

A field separator character. “” has the same effect as “\t”. Sets detect_format to False if set. Ignored if detect_format is True.

…

See Common Parameters.

khiops.core.api.check_database(dictionary_file_path_or_domain, dictionary_name, data_table_path, detect_format=True, header_line=None, field_separator=None, sample_percentage=100.0, sampling_mode='Include sample', selection_variable='', selection_value='', additional_data_tables=None, max_messages=20, log_file_path=None, output_scenario_path=None, task_file_path=None, trace=False, stdout_file_path='', stderr_file_path='', max_cores=None, memory_limit_mb=None, temp_dir='', scenario_prologue='', **kwargs)

Checks if a data table is compatible with a dictionary file

Parameters:

dictionary_file_path_or_domainstr or DictionaryDomain

Path of a Khiops dictionary file or a DictionaryDomain object.

dictionary_namestr

Name of the dictionary of the table to be checked.

data_table_pathstr

Path of the data table file.

detect_formatbool, default True

If True detects automatically whether the data table file has a header and its field separator. It is set to False if header_line or field_separator are set.

header_linebool, optional (default True)

If True it uses the first line of the data as column names. Sets detect_format to False if set. Ignored if detect_format is True.

field_separatorstr, optional (default “\t”)

A field separator character. “” has the same effect as “\t”. Sets detect_format to False if set. Ignored if detect_format is True.

sample_percentagefloat, default 100.0

See the sampling_mode option below.

sampling_mode“Include sample” or “Exclude sample”

If equal to “Include sample” it checks sample_percentage percent of the data; if equal to “Exclude sample” it checks the complement of the data selected with “Include sample”. See also Database Sampling.

selection_variablestr, default “”

It checks only the records such that the value of selection_variable is equal to selection_value. Ignored if equal to “”.

selection_value: str or int or float, default “”

See selection_variable option above. Ignored if equal to “”.

additional_data_tablesdict, optional

A dictionary containing the data paths and file paths for a multi-table dictionary file. For more details see Multi-Table Learning Primer.

max_messagesint, default 20

Maximum number of error messages to write in the log file.

…

See Common Parameters.

Examples

See the following function of the samples.py documentation script:

• samples.check_database()

khiops.core.api.deploy_model(dictionary_file_path_or_domain, dictionary_name, data_table_path, output_data_table_path, detect_format=True, header_line=None, field_separator=None, sample_percentage=100.0, sampling_mode='Include sample', selection_variable='', selection_value='', additional_data_tables=None, output_header_line=True, output_field_separator='\t', output_additional_data_tables=None, log_file_path=None, output_scenario_path=None, task_file_path=None, trace=False, stdout_file_path='', stderr_file_path='', max_cores=None, memory_limit_mb=None, temp_dir='', scenario_prologue='', **kwargs)

Deploys a model on a data table

Parameters:

dictionary_file_path_or_domainstr or DictionaryDomain

Path of a Khiops dictionary file or a DictionaryDomain object. This file/object defines the model to be deployed. Note that this model is not necessarily a predictor, it can be a generic table transformation.

dictionary_namestr

Name of the dictionary to be analyzed.

data_table_pathstr

Path of the data table file.

output_data_table_pathstr

Path of the output data file.

detect_formatbool, default True

If True detects automatically whether the data table file has a header and its field separator. It is set to False if header_line or field_separator are set.

header_linebool, optional (default True)

If True it uses the first line of the data as column names. Sets detect_format to False if set. Ignored if detect_format is True.

field_separatorstr, optional (default “\t”)

A field separator character. “” has the same effect as “\t”. Sets detect_format to False if set. Ignored if detect_format is True.

sample_percentagefloat, default 100.0

See sampling_mode option below.

sampling_mode“Include sample” or “Exclude sample”

If equal to “Include sample” it deploys the model on sample_percentage percent of the data. If equal to “Exclude sample” it deploys the model on the complement of the data selected with “Include sample”. See also Database Sampling.

selection_variablestr, default “”

It deploys only the records such that the value of selection_variable is equal to selection_value. Ignored if equal to “”.

selection_value: str or int or float, default “”

See selection_variable option above. Ignored if equal to “”.

additional_data_tablesdict, optional

A dictionary containing the data paths and file paths for a multi-table dictionary file. For more details see Multi-Table Learning Primer.

output_header_linebool, default True

If True writes a header line with the column names in the output table.

output_field_separatorstr, default “\t”

The field separator character for the output table (”” counts as “\t”).

output_additional_data_tablesdict, optional

A dictionary containing the output data paths and file paths for a multi-table dictionary file. For more details see Multi-Table Learning Primer.

…

See Common Parameters.

Raises:

TypeError

Invalid type of an argument.

Examples

See the following functions of the samples.py documentation script:

• samples.deploy_model()

• samples.deploy_model_mt()

• samples.deploy_model_mt_with_interpretation()

• samples.deploy_model_mt_snowflake()

• samples.deploy_model_expert()

khiops.core.api.detect_data_table_format(data_table_path, dictionary_file_path_or_domain=None, dictionary_name=None, log_file_path=None, output_scenario_path=None, task_file_path=None, trace=False, stdout_file_path='', stderr_file_path='', max_cores=None, memory_limit_mb=None, temp_dir='', scenario_prologue='', **kwargs)

Detects the format of a data table

Runs an heuristic to detect the format of a data table. The detection heuristic is more accurate if a dictionary with the table schema is provided.

Parameters:

data_table_pathstr

Path of the data table file.

dictionary_file_path_or_domainstr or DictionaryDomain, optional

Path of a Khiops dictionary file or a DictionaryDomain object.

dictionary_namestr, optional

Name of the dictionary.

…

See Common Parameters.

Returns:

tuple

A 2-tuple containing:

• the header_line boolean

• the field_separator character

These are exactly the parameters expected in many Khiops Python API functions.

Examples

See the following function of the samples.py documentation script:

• samples.detect_data_table_format()

khiops.core.api.evaluate_predictor(dictionary_file_path_or_domain, train_dictionary_name, data_table_path, evaluation_report_file_path, detect_format=True, header_line=None, field_separator=None, sample_percentage=100.0, sampling_mode='Include sample', selection_variable='', selection_value='', additional_data_tables=None, main_target_value='', log_file_path=None, output_scenario_path=None, task_file_path=None, trace=False, stdout_file_path='', stderr_file_path='', max_cores=None, memory_limit_mb=None, temp_dir='', scenario_prologue='', **kwargs)

Evaluates the predictors in a dictionary file on a database

Parameters:

dictionary_file_path_or_domainstr or DictionaryDomain

Path of a Khiops dictionary file or a DictionaryDomain object.

train_dictionary_namestr

Name of the main dictionary used while training the models.

data_table_pathstr

Path of the evaluation data table file.

evaluation_report_file_pathstr

Path to the evaluation report file, in the JSON format.

detect_formatbool, default True

If True detects automatically whether the data table file has a header and its field separator. It is set to False if header_line or field_separator are set.

header_linebool, optional (default True)

If True it uses the first line of the data as column names. Sets detect_format to False if set. Ignored if detect_format is True.

field_separatorstr, optional (default “\t”)

A field separator character. “” has the same effect as “\t”. Sets detect_format to False if set. Ignored if detect_format is True.

sample_percentagefloat, default 100.0

See sampling_mode option below.

sampling_mode“Include sample” or “Exclude sample”

If equal to “Include sample” it evaluates the predictor on sample_percentage percent of the data. If equal to “Exclude sample” it evaluates the predictor on the complement of the data selected with “Include sample”. See also Database Sampling.

selection_variablestr, default “”

It trains with only the records such that the value of selection_variable is equal to selection_value. Ignored if equal “”.

selection_value: str or int or float, default “”

See selection_variable option above. Ignored if equal to “”.

additional_data_tablesdict, optional

A dictionary containing the data paths and file paths for a multi-table dictionary file. For more details see Multi-Table Learning Primer.

Note

Use the initial dictionary name in the data paths.

main_target_valuestr, default “”

If this target value is specified then it guarantees the calculation of lift curves for it.

…

See Common Parameters.

Returns:

str

The path of the JSON evaluation report (extension .khj).

Raises:

TypeError

Invalid type of an argument.

Examples

See the following functions of the samples.py documentation script:

• samples.evaluate_predictor()

• samples.access_predictor_evaluation_report()

• samples.train_predictor_with_cross_validation()

khiops.core.api.export_dictionary_as_json(dictionary_file_path_or_domain, json_dictionary_file_path, log_file_path=None, output_scenario_path=None, task_file_path=None, trace=False, stdout_file_path='', stderr_file_path='', max_cores=None, memory_limit_mb=None, temp_dir='', scenario_prologue='')

Exports a Khiops dictionary file to JSON format (.kdicj)

Parameters:

dictionary_file_path_or_domainstr or DictionaryDomain

Path of a Khiops dictionary file or a DictionaryDomain object.

…

See Common Parameters.

Examples

See the following function of the samples.py documentation script:

• samples.export_dictionary_files()

khiops.core.api.extract_clusters(coclustering_file_path, cluster_variable, clusters_file_path, max_preserved_information=0, max_cells=0, max_total_parts=0, max_part_numbers=None, log_file_path=None, output_scenario_path=None, task_file_path=None, trace=False, stdout_file_path='', stderr_file_path='', max_cores=None, memory_limit_mb=None, temp_dir='', scenario_prologue='', **kwargs)

Extracts clusters to a tab separated (TSV) file

Parameters:

coclustering_file_pathstr

Path of the coclustering model file (extension .khc or .khcj).

cluster_variablestr

Name of the variable for which the clusters are extracted.

clusters_file_pathstr

Path of the output clusters TSV file.

max_preserved_informationint, default 0

Maximum information preserve in the simplified coclustering. If equal to 0 there is no limit.

max_cellsint, default 0

Maximum number of cells in the simplified coclustering. If equal to 0 there is no limit.

max_total_partsint, default 0

Maximum number of parts totaled over all variables. If equal to 0 there is no limit.

max_part_numbersdict, optional

Dictionary that associate variable names to their maximum number of parts to preserve in the simplified coclustering. If not set there is no limit.

…

See Common Parameters.

Examples

See the following function of the samples.py documentation script:

• samples.extract_clusters()

khiops.core.api.extract_keys_from_data_table(dictionary_file_path_or_domain, dictionary_name, data_table_path, output_data_table_path, detect_format=True, header_line=None, field_separator=None, output_header_line=True, output_field_separator='\t', log_file_path=None, output_scenario_path=None, task_file_path=None, trace=False, stdout_file_path='', stderr_file_path='', max_cores=None, memory_limit_mb=None, temp_dir='', scenario_prologue='', **kwargs)

Extracts from data table unique occurrences of a key variable

Parameters:

dictionary_file_path_or_domainstr or DictionaryDomain

Path of a Khiops dictionary file or a DictionaryDomain object.

dictionary_namestr

Name of the dictionary of the data table.

data_table_pathstr

Path of the data table file.

output_data_table_pathstr

Path of the output data file.

detect_formatbool, default True

If True detects automatically whether the data table file has a header and its field separator. It is set to False if header_line or field_separator are set.

header_linebool, optional (default True)

If True it uses the first line of the data as column names. Sets detect_format to False if set. Ignored if detect_format is True.

field_separatorstr, optional (default “\t”)

A field separator character. “” has the same effect as “\t”. Sets detect_format to False if set. Ignored if detect_format is True.

output_header_linebool, default True

If True writes a header line with the column names in the output table.

output_field_separatorstr, default “\t”

The field separator character for the output table (”” counts as “\t”).

…

See Common Parameters.

Raises:

TypeError

Invalid type of an argument.

Examples

See the following function of the samples.py documentation script:

• samples.extract_keys_from_data_table()

khiops.core.api.get_khiops_version()

Returns the Khiops version

Returns:

str

The Khiops version of the current KhiopsRunner backend.

khiops.core.api.get_samples_dir()

Returns the Khiops’ samples directory path

Returns:

str

The path of the Khiops samples directory.

khiops.core.api.interpret_predictor(dictionary_file_path_or_domain, predictor_dictionary_name, interpretor_file_path, max_variable_importances=100, importance_ranking='Global', log_file_path=None, output_scenario_path=None, task_file_path=None, trace=False, stdout_file_path='', stderr_file_path='', max_cores=None, memory_limit_mb=None, temp_dir='', scenario_prologue='', **kwargs)

Builds an interpretation dictionary from a predictor

Parameters:

dictionary_file_path_or_domainstr or DictionaryDomain

Path of a Khiops dictionary file or a DictionaryDomain object.

predictor_dictionary_namestr

Name of the predictor dictionary used while building the interpretation model.

interpretor_file_pathstr

Path to the interpretor dictionary file.

max_variable_importancesint, default 100

Maximum number of variable importances to be selected in the interpretation model. If the predictor contains fewer variables than this number, then all the variables of the predictor are considered.

importance_rankingstr, default “Global”

Ranking of the Shapley values produced by the interpretor. Ca be one of:

• “Global”: predictor variables are ranked by decreasing global importance.

• “Individual”: predictor variables are ranked by decreasing individual Shapley value.

…

See Common Parameters.

Raises:

ValueError

Invalid values of an argument

TypeError

Invalid type of an argument

Examples

See the following functions of the samples.py documentation script:

• samples.interpret_predictor()

• samples.deploy_model_mt_with_interpretation()

khiops.core.api.prepare_coclustering_deployment(dictionary_file_path_or_domain, dictionary_name, coclustering_file_path, table_variable, deployed_variable_name, coclustering_dictionary_file_path, max_preserved_information=0, max_cells=0, max_total_parts=0, max_part_numbers=None, build_cluster_variable=True, build_distance_variables=False, build_frequency_variables=False, variables_prefix='', log_file_path=None, output_scenario_path=None, task_file_path=None, trace=False, stdout_file_path='', stderr_file_path='', max_cores=None, memory_limit_mb=None, temp_dir='', scenario_prologue='', **kwargs)

Prepares a individual-variable coclustering deployment

Parameters:

dictionary_file_path_or_domainstr or DictionaryDomain

Path of a Khiops dictionary file or a DictionaryDomain object.

dictionary_namestr

Name of the dictionary to be analyzed.

coclustering_file_pathstr

Path of the coclustering model file (extension .khc or .khcj).

table_variablestr

Name of the table variable in the dictionary.

deployed_variable_namestr

Name of the coclustering variable to deploy.

coclustering_dictionary_file_pathstr

Path of the coclustering dictionary file for deployment.

max_preserved_informationint, default 0

Maximum information preserve in the simplified coclustering. If equal to 0 there is no limit.

max_cellsint, default 0

Maximum number of cells in the simplified coclustering. If equal to 0 there is no limit.

max_total_partsint, default 0

Maximum number of parts totaled over all variables. If equal to 0 there is no limit.

max_part_numbersdict, optional

Dictionary associating variable names to their maximum number of parts to preserve in the simplified coclustering. For variables not present in max_part_numbers there is no limit.

build_cluster_variablebool, default True

If True includes a cluster id variable in the deployment.

build_distance_variablesbool, default False

If True includes a cluster distance variable in the deployment.

build_frequency_variablesbool, default False

If True includes the frequency variables in the deployment.

variables_prefixstr, default “”

Prefix for the variables in the deployment dictionary.

…

See Common Parameters.

Raises:

TypeError

Invalid type of an argument

Examples

See the following function of the samples.py documentation script:

• samples.deploy_model_expert()

khiops.core.api.reinforce_predictor(dictionary_file_path_or_domain, predictor_dictionary_name, reinforced_predictor_file_path, reinforcement_target_value='', reinforcement_lever_variables=None, log_file_path=None, output_scenario_path=None, task_file_path=None, trace=False, stdout_file_path='', stderr_file_path='', max_cores=None, memory_limit_mb=None, temp_dir='', scenario_prologue='', **kwargs)

Builds a reinforced predictor from a predictor

A reinforced predictor is a model which increases the importance of specified lever variables in order to increase the probability of occurrence of the specified target value.

Parameters:

dictionary_file_path_or_domainstr or DictionaryDomain

Path of a Khiops dictionary file or a DictionaryDomain object.

predictor_dictionary_namestr

Name of the predictor dictionary used while building the reinforced predictor.

reinforced_predictor_file_pathstr

Path to the reinforced predictor dictionary file.

reinforcement_target_valuestr, default “”

If this target value is specified, then its probability of occurrence is tentatively increased.

reinforcement_lever_variableslist of str

The names of variables to use as lever variables while building the reinforced predictor. Min length: 1. Max length: the total number of variables in the prediction model.

…

See Common Parameters.

Raises:

ValueError

Invalid values of an argument

TypeError

Invalid type of an argument

Examples

See the following functions of the samples.py documentation script:

• samples.reinforce_predictor()

• samples.deploy_reinforced_model_mt()

khiops.core.api.simplify_coclustering(coclustering_file_path, simplified_coclustering_file_path, results_dir=None, max_preserved_information=0, max_cells=0, max_total_parts=0, max_part_numbers=None, log_file_path=None, output_scenario_path=None, task_file_path=None, trace=False, stdout_file_path='', stderr_file_path='', max_cores=None, memory_limit_mb=None, temp_dir='', scenario_prologue='', **kwargs)

Simplifies a coclustering model

Parameters:

coclustering_file_pathstr

Path of the coclustering file (extension .khc, or .khcj).

simplified_coclustering_file_pathstr

Path of the output coclustering file.

max_preserved_informationint, default 0

Maximum information preserve in the simplified coclustering. If equal to 0 there is no limit.

max_cellsint, default 0

Maximum number of cells in the simplified coclustering. If equal to 0 there is no limit.

max_total_partsint, default 0

Maximum number of parts totaled over all variables. If equal to 0 there is no limit.

max_part_numbersdict, optional

Dictionary that associate variable names to their maximum number of parts to preserve in the simplified coclustering. If not set there is no limit.

…

See Common Parameters.

Raises:

TypeError

Invalid type of an argument.

Examples

See the following function of the samples.py documentation script:

• samples.simplify_coclustering()

khiops.core.api.sort_data_table(dictionary_file_path_or_domain, dictionary_name, data_table_path, output_data_table_path, sort_variables=None, detect_format=True, header_line=None, field_separator=None, output_header_line=True, output_field_separator='\t', log_file_path=None, output_scenario_path=None, task_file_path=None, trace=False, stdout_file_path='', stderr_file_path='', max_cores=None, memory_limit_mb=None, temp_dir='', scenario_prologue='', **kwargs)

Sorts a data table

Parameters:

dictionary_file_path_or_domainstr or DictionaryDomain

Path of a Khiops dictionary file or a DictionaryDomain object.

dictionary_namestr

Name of the dictionary to be analyzed.

data_table_pathstr

Path of the data table file.

output_data_table_pathstr

Path of the output data file.

sort_variableslist of str, optional

The names of the variables to sort. If not set sorts the table by its key.

detect_formatbool, default True

If True detects automatically whether the data table file has a header and its field separator. It is set to False if header_line or field_separator are set.

header_linebool, optional (default True)

If True it uses the first line of the data as column names. Sets detect_format to False if set. Ignored if detect_format is True.

field_separatorstr, optional (default “\t”)

A field separator character. “” has the same effect as “\t”. Sets detect_format to False if set. Ignored if detect_format is True.

output_header_linebool, default True

If True writes a header line with the column names in the output table.

output_field_separatorstr, default “\t”

The field separator character for the output table (”” counts as “\t”).

…

See Common Parameters.

Raises:

TypeError

Invalid type of a argument.

Examples

See the following functions of the samples.py documentation script:

• samples.sort_data_table()

• samples.sort_data_table_expert()

khiops.core.api.train_coclustering(dictionary_file_path_or_domain, dictionary_name, data_table_path, coclustering_variables, coclustering_report_file_path, detect_format=True, header_line=None, field_separator=None, sample_percentage=100.0, sampling_mode='Include sample', selection_variable='', selection_value='', additional_data_tables=None, frequency_variable='', min_optimization_time=0, log_file_path=None, output_scenario_path=None, task_file_path=None, trace=False, stdout_file_path='', stderr_file_path='', max_cores=None, memory_limit_mb=None, temp_dir='', scenario_prologue='', **kwargs)

Trains a coclustering model from a data table

Parameters:

dictionary_file_path_or_domainstr or DictionaryDomain

Path of a Khiops dictionary file or a DictionaryDomain object.

dictionary_namestr

Name of the dictionary to be analyzed.

data_table_pathstr

Path of the data table file.

coclustering_variableslist of str

The names of variables to use in coclustering. Min length: 2. Max length: 10.

coclustering_report_file_pathstr

Path to the coclustering report file in the JSON format.

detect_formatbool, default True

If True detects automatically whether the data table file has a header and its field separator. It is set to False if header_line or field_separator are set.

header_linebool, optional (default True)

If True it uses the first line of the data as column names. Sets detect_format to False if set. Ignored if detect_format is True.

field_separatorstr, optional (default “\t”)

A field separator character. “” has the same effect as “\t”. Sets detect_format to False if set. Ignored if detect_format is True.

sample_percentagefloat, default 100.0

See sampling_mode option below.

sampling_mode“Include sample” or “Exclude sample”

If equal to “Include sample” it trains the coclustering estimator on sample_percentage percent of the data. If equal to “Exclude sample” it trains the coclustering estimator on the complement of the data selected with “Include sample”. See also Database Sampling.

selection_variablestr, default “”

It trains with only the records such that the value of selection_variable is equal to selection_value. Ignored if equal to “”.

selection_value: str or int or float, default “”

See selection_variable option above. Ignored if equal to “”.

additional_data_tablesdict, optional

A dictionary containing the data paths and file paths for a multi-table dictionary file. For more details see Multi-Table Learning Primer.

frequency_variablestr, default “”

Name of frequency variable.

min_optimization_timeint, default 0

Minimum optimization time in seconds.

…

See Common Parameters.

Returns:

str

The path of the of the resulting coclustering file.

Raises:

ValueError

Number of coclustering variables out of the range 2-10.

TypeError

Invalid type of an argument.

Examples

See the following function of the samples.py documentation script:

• samples.train_coclustering()

khiops.core.api.train_instance_variable_coclustering(dictionary_file_path_or_domain, dictionary_name, data_table_path, coclustering_report_file_path, detect_format=True, header_line=None, field_separator=None, sample_percentage=100.0, sampling_mode='Include sample', selection_variable='', selection_value='', additional_data_tables=None, min_optimization_time=0, log_file_path=None, output_scenario_path=None, task_file_path=None, trace=False, stdout_file_path='', stderr_file_path='', max_cores=None, memory_limit_mb=None, temp_dir='', scenario_prologue='', **kwargs)

Trains an instance-variable coclustering model from a data table .. note:

If keys are available in the input dictionary, they are used as instance
identifiers. Otherwise, line numbers in the instance data table are used as
instance idenfitiers.

Parameters:

dictionary_file_path_or_domainstr or DictionaryDomain

Path of a Khiops dictionary file or a DictionaryDomain object.

dictionary_namestr

Name of the dictionary to be analyzed.

data_table_pathstr

Path of the data table file.

coclustering_report_file_pathstr

Path to the coclustering report file in the JSON format.

detect_formatbool, default True

If True detects automatically whether the data table file has a header and its field separator. It is set to False if header_line or field_separator are set.

header_linebool, optional (default True)

If True it uses the first line of the data as column names. Sets detect_format to False if set. Ignored if detect_format is True.

field_separatorstr, optional (default “\t”)

A field separator character. “” has the same effect as “\t”. Sets detect_format to False if set. Ignored if detect_format is True.

sample_percentagefloat, default 100.0

See sampling_mode option below.

sampling_mode“Include sample” or “Exclude sample”

If equal to “Include sample” it trains the coclustering estimator on sample_percentage percent of the data. If equal to “Exclude sample” it trains the coclustering estimator on the complement of the data selected with “Include sample”. See also Database Sampling.

selection_variablestr, default “”

It trains with only the records such that the value of selection_variable is equal to selection_value. Ignored if equal to “”.

selection_value: str or int or float, default “”

See selection_variable option above. Ignored if equal to “”.

additional_data_tablesdict, optional

A dictionary containing the data paths and file paths for a multi-table dictionary file. For more details see Multi-Table Learning Primer.

min_optimization_timeint, default 0

Minimum optimization time in seconds.

…

See Common Parameters.

Returns:

str

The path of the of the resulting coclustering file.

Raises:

ValueError

Number of coclustering variables out of the range 2-10.

TypeError

Invalid type of an argument.

Examples

See the following function of the samples.py documentation script:

• samples.train_instance_variable_coclustering()

khiops.core.api.train_predictor(dictionary_file_path_or_domain, dictionary_name, data_table_path, target_variable, analysis_report_file_path, detect_format=True, header_line=None, field_separator=None, sample_percentage=70.0, sampling_mode='Include sample', use_complement_as_test=True, selection_variable='', selection_value='', additional_data_tables=None, do_data_preparation_only=False, main_target_value='', keep_selected_variables_only=True, max_evaluated_variables=0, max_selected_variables=0, max_constructed_variables=1000, construction_rules=None, max_text_features=10000, text_features='words', max_trees=10, max_pairs=0, all_possible_pairs=True, specific_pairs=None, group_target_value=False, discretization_method='MODL', grouping_method='MODL', max_parts=0, log_file_path=None, output_scenario_path=None, task_file_path=None, trace=False, stdout_file_path='', stderr_file_path='', max_cores=None, memory_limit_mb=None, temp_dir='', scenario_prologue='', **kwargs)

Trains a model from a data table

Parameters:

dictionary_file_path_or_domainstr or DictionaryDomain

Path of a Khiops dictionary file or a DictionaryDomain object.

dictionary_namestr

Name of the dictionary to be analyzed.

data_table_pathstr

Path of the data table file.

target_variablestr

Name of the target variable. If the specified variable is categorical it constructs a classifier and if it is numerical a regressor. If equal to “” it performs an unsupervised analysis.

analysis_report_file_pathstr

Path to the analysis report file in the JSON format. An additional dictionary file with the same name and extension .model.kdic is built, which contains the trained models.

detect_formatbool, default True

If True detects automatically whether the data table file has a header and its field separator. It is set to False if header_line or field_separator are set.

header_linebool, optional (default True)

If True it uses the first line of the data as column names. Sets detect_format to False if set. Ignored if detect_format is True.

field_separatorstr, optional (default “\t”)

A field separator character. “” has the same effect as “\t”. Sets detect_format to False if set. Ignored if detect_format is True.

sample_percentagefloat, default 70.0

See the sampling_mode option below.

sampling_mode“Include sample” or “Exclude sample”

If equal to “Include sample” it trains the predictor on sample_percentage percent of the data and tests the model on the remainder of the data if use_complement_as_test is set to True. If equal to “Exclude sample” the train and test datasets above are exchanged. See also Database Sampling.

use_complement_as_testbool, default True

Uses the complement of the sampled database as test database for computing the model’s performance metrics.

selection_variablestr, default “”

It trains with only the records such that the value of selection_variable is equal to selection_value. Ignored if equal to “”.

selection_value: str or int or float, default “”

See selection_variable option above. Ignored if equal to “”.

additional_data_tablesdict, optional

A dictionary containing the data paths and file paths for a multi-table dictionary file. For more details see Multi-Table Learning Primer.

do_data_preparation_onlybool, default False

If True it only does data preparation via MODL preprocessing without training a Selective Naive Bayes Predictor.

main_target_valuestr, default “”

If this target value is specified then it guarantees the calculation of lift curves for it.

keep_selected_variables_onlybool, default True

Keeps only predictor-selected variables in the supervised analysis report.

max_evaluated_variablesint, default 0

Maximum number of variables to be evaluated in the SNB predictor training. If equal to 0 it evaluates all informative variables.

max_selected_variablesint, default 0

Maximum number of variables to be selected in the SNB predictor. If equal to 0 it selects all the variables kept in the training.

max_constructed_variablesint, default 1000

Maximum number of variables to construct.

construction_ruleslist of str, optional

Allowed rules for the automatic variable construction. If not set it uses all possible rules.

max_text_featuresint, default 10000

Maximum number of text features to construct.

text_featuresstr, default “words”

Type of the text features. Can be either one of: - “words”: sequences of non-space characters - “ngrams”: sequences of bytes - “tokens”: user-defined

max_treesint, default 10

Maximum number of trees to construct.

max_pairsint, default 0

Maximum number of variable pairs to construct.

specific_pairslist of tuple, optional

User-specified pairs as a list of 2-tuples of feature names. If a given tuple contains only one non-empty feature name, then it generates all the pairs containing it (within the maximum limit max_pairs). These pairs have top priority: they are constructed first.

all_possible_pairsbool, default True

If True tries to create all possible pairs within the limit max_pairs. Pairs specified with specific_pairs have top priority: they are constructed first.

group_target_valuebool, default False

Allows grouping of the target variable values in classification. It can substantially increase the training time.

discretization_methodstr, default “MODL”

Name of the discretization method in case of unsupervised analysis. Its valid values are: “MODL”, “EqualWidth”, “EqualFrequency” or “none”. Ignored for supervised analysis.

grouping_methodstr, default “MODL”

Name of the grouping method in case of unsupervised analysis. Its valid values are: “MODL”, “BasicGrouping” or “none”. Ignored for supervised analysis.

max_partsint, default 0

Maximum number of variable parts produced by preprocessing methods. If equal to 0 it is automatically calculated. Special default values for unsupervised analysis: - If discretization_method is “EqualWidth” or “EqualFrequency”: 10 - If grouping_method is “BasicGrouping”: 10

…

See Common Parameters.

Returns:

tuple

A 2-tuple containing:

• The reports file path

• The modeling dictionary file path in the supervised case.

Raises:

ValueError

Invalid values of an argument

TypeError

Invalid type of an argument

Examples

See the following functions of the samples.py documentation script:

• samples.train_predictor()

• samples.train_predictor_file_paths()

• samples.train_predictor_error_handling()

• samples.train_predictor_mt()

• samples.train_predictor_mt_with_specific_rules()

• samples.train_predictor_with_train_percentage()

• samples.train_predictor_with_trees()

• samples.train_predictor_with_pairs()

• samples.train_predictor_with_multiple_parameters()

• samples.train_predictor_detect_format()

• samples.train_predictor_with_cross_validation()

• samples.multiple_train_predictor()

khiops.core.api.train_recoder(dictionary_file_path_or_domain, dictionary_name, data_table_path, target_variable, analysis_report_file_path, detect_format=True, header_line=None, field_separator=None, sample_percentage=100.0, sampling_mode='Include sample', selection_variable='', selection_value='', additional_data_tables=None, max_constructed_variables=100, construction_rules=None, max_text_features=10000, text_features='words', max_trees=10, max_pairs=0, all_possible_pairs=True, specific_pairs=None, informative_variables_only=True, max_variables=0, keep_initial_categorical_variables=False, keep_initial_numerical_variables=False, categorical_recoding_method='part Id', numerical_recoding_method='part Id', pairs_recoding_method='part Id', group_target_value=False, discretization_method='MODL', grouping_method='MODL', max_parts=0, log_file_path=None, output_scenario_path=None, task_file_path=None, trace=False, stdout_file_path='', stderr_file_path='', max_cores=None, memory_limit_mb=None, temp_dir='', scenario_prologue='', **kwargs)

Trains a recoding model from a data table

A recoding model consists in the discretization of numerical variables and the grouping of categorical variables.

If the target_variable is specified these partitions are constructed in supervised mode, meaning that each resulting discretizations/groupings best separates the target variable while maintaining a simple interval/group model of the data. Different recoding methods can be specified via the numerical_recoding_method, categorical_recoding_method and pairs_recoding_method options.

The output files of this process contain a dictionary file (.kdic) that can be used to recode databases with the deploy_model function.

Parameters:

dictionary_file_path_or_domainstr or DictionaryDomain

Path of a Khiops dictionary file or a DictionaryDomain object.

dictionary_namestr

Name of the dictionary to be recoded.

data_table_pathstr

Path of the data table file.

target_variablestr

Name of the target variable. If equal to “” it trains an unsupervised recoder.

analysis_report_file_pathstr

Path to the analysis report file in the JSON format. An additional dictionary file with the same name and extension .model.kdic is built, which contains the trained recoding model.

detect_formatbool, default True

If True detects automatically whether the data table file has a header and its field separator. It is set to False if header_line or field_separator are set.

header_linebool, optional (default True)

If True it uses the first line of the data as column names. Sets detect_format to False if set. Ignored if detect_format is True.

field_separatorstr, optional (default “\t”)

A field separator character. “” has the same effect as “\t”. Sets detect_format to False if set. Ignored if detect_format is True.

sample_percentagefloat, default 100.0

See sampling_mode option below.

sampling_mode“Include sample” or “Exclude sample”

If equal to “Include sample” it trains the recoder on sample_percentage percent of the data. If equal to “Exclude sample” it trains the recoder on the complement of the data selected with “Include sample”. See also Database Sampling.

selection_variablestr, default “”

It trains with only the records such that the value of selection_variable is equal to selection_value. Ignored if equal to “”.

selection_value: str or int or float, default “”

See selection_variable option above. Ignored if equal to “”.

additional_data_tablesdict, optional

A dictionary containing the data paths and file paths for a multi-table dictionary file. For more details see Multi-Table Learning Primer.

max_constructed_variablesint, default 100

Maximum number of variables to construct.

construction_ruleslist of str, optional

Allowed rules for the automatic variable construction. If not set it uses all possible rules.

max_text_featuresint, default 10000

Maximum number of text features to construct.

text_featuresstr, default “words”

Type of the text features. Can be either one of: - “words”: sequences of non-space characters - “ngrams”: sequences of bytes - “tokens”: user-defined

max_treesint, default 10

Maximum number of trees to construct.

max_pairsint, default 0

Maximum number of variables pairs to construct.

specific_pairslist of tuple, optional

User-specified pairs as a list of 2-tuples of feature names. If a given tuple contains only one non-empty feature name, then it generates all the pairs containing it (within the maximum limit max_pairs). These pairs have top priority: they are constructed first.

all_possible_pairsbool, default True

If True tries to create all possible pairs within the limit max_pairs. Pairs specified with specific_pairs have top priority: they are constructed first.

group_target_valuebool, default False

Allows grouping of the target variable values in classification. It can substantially increase the training time.

informative_variables_onlybool, default True

If True keeps only informative variables.

max_variablesint, default 0

Maximum number of variables to keep. If equal to 0 keeps all variables.

keep_initial_categorical_variablesbool, default False

If True keeps the initial categorical variables.

keep_initial_numerical_variablesbool, default False

If True keeps initial numerical variables.

categorical_recoding_methodstr

Type of recoding for categorical variables. Types available:

• “part Id” (default): An id for the interval/group

• “part label”: A label for the interval/group

• “0-1 binarization”: A 0’s and 1’s coding the interval/group id

• “conditional info”: Conditional information of the interval/group

• “none”: Keeps the variable as-is

numerical_recoding_methodstr

Type of recoding recoding for numerical variables. Types available:

• “part Id” (default): An id for the interval/group

• “part label”: A label for the interval/group

• “0-1 binarization”: A 0’s and 1’s coding the interval/group id

• “conditional info”: Conditional information of the interval/group

• “center-reduction”: “(X - Mean(X)) / StdDev(X)”

• “0-1 normalization”: “(X - Min(X)) / (Max(X) - Min(X))”

• “rank normalization”: mean normalized rank (between 0 and 1) of the instances

• “none”: Keeps the variable as-is

pairs_recoding_methodstr

Type of recoding for bivariate variables. Types available:

• “part Id” (default): An id for the interval/group

• “part label”: A label for the interval/group

• “0-1 binarization”: A 0’s and 1’s coding the interval/group id

• “conditional info”: Conditional information of the interval/group

• “none”: Keeps the variable as-is

discretization_methodstr, default “MODL”

Name of the discretization method in case of unsupervised analysis. Its valid values are: “MODL”, “EqualWidth”, “EqualFrequency” or “none”. Ignored for supervised analysis.

grouping_methodstr, default “MODL”

Name of the grouping method in case of unsupervised analysis. Its valid values are: “MODL”, “BasicGrouping” or “none”. Ignored for supervised analysis.

max_partsint, default 0

Maximum number of variable parts produced by preprocessing methods. If equal to 0 it is automatically calculated. Special default values for unsupervised analysis: - If discretization_method is “EqualWidth” or “EqualFrequency”: 10 - If grouping_method is “BasicGrouping”: 10

…

See Common Parameters.

Returns:

tuple

A 2-tuple containing:

• The path of the JSON file report of the process

• The path of the dictionary containing the recoding model

Examples

See the following functions of the samples.py documentation script:

• samples.train_recoder()

• samples.train_recoder_with_multiple_parameters()

• samples.train_recoder_mt_flatten()