khiops.core.helpers

Submodule of khiops.core

Helper functions for specific and/or advanced treatments

FUNCTION	DESCRIPTION
`deploy_coclustering`	Deploys a coclustering on a data table
`deploy_predictor_for_metrics`	Deploys the necessary data to estimate the performance metrics of a predictor
`visualize_report`	Opens a Khiops or Khiops Coclustering report with the desktop visualization app

Classes

Functions:

deploy_coclustering(dictionary_file_path_or_domain, dictionary_name, data_table_path, coclustering_file_path, key_variable_names, deployed_variable_name, coclustering_dictionary_file_path, output_data_table_path, detect_format=True, header_line=None, field_separator=None, output_header_line=True, output_field_separator='\t', 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)

Deploys a coclustering on a data table

This procedure generates the following files: - coclustering_dictionary_file_path: A multi-table dictionary file for further deployments of the coclustering with deploy_model - output_data_table_path: A data table file containing the deployed coclustering model

PARAMETER	DESCRIPTION
`dictionary_file_path_or_domain`	Path of a Khiops dictionary file or a DictionaryDomain object. TYPE: `str or DictionaryDomain`
`dictionary_name`	Name of the dictionary to be analyzed. TYPE: `str`
`data_table_path`	Path of the data table file. TYPE: `str`
`coclustering_file_path`	Path of the coclustering model file (extension `.khc` or `.khcj`). Note Instance-variable coclustering is not currently supported. TYPE: `str`
`key_variable_names`	Names of the variables forming the unique keys of the individuals. TYPE: `list of str`
`deployed_variable_name`	Name of the coclustering variable to deploy. TYPE: `str`
`coclustering_dictionary_file_path`	Path of the coclustering dictionary file to deploy. TYPE: `str`
`output_data_table_path`	Path of the output data file. TYPE: `str`
`detect_format`	If True detects automatically whether the data table file has a header and its field separator. It's ignored if `header_line` or `field_separator` are set. TYPE: `bool` DEFAULT: `True`
`header_line`	If True it uses the first line of the data as column names. Overrides `detect_format` if set. TYPE: bool, optional (default `True` if `detect_format` is False) DEFAULT: `None`
`field_separator`	A field separator character, overrides `detect_format` if set ("" counts as "\t"). TYPE: str, optional (default "\\t" if `detect_format` is False) DEFAULT: `None`
`output_header_line`	If True writes a header line containing the column names in the output table. TYPE: `bool` DEFAULT: `True`
`output_field_separator`	A field separator character (empty string counts as tab). TYPE: `str` DEFAULT: `"\\t"`
`max_preserved_information`	Maximum information preserve in the simplified coclustering. If equal to 0 there is no limit. TYPE: `int` DEFAULT: `0`
`max_cells`	Maximum number of cells in the simplified coclustering. If equal to 0 there is no limit. TYPE: `int` DEFAULT: `0`
`max_total_parts`	Maximum number of parts totaled over all variables. If equal to 0 there is no limit. TYPE: `int` DEFAULT: `0`
`max_part_numbers`	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. TYPE: `dict` DEFAULT: `None`
`build_cluster_variable`	If True includes a cluster id variable in the deployment. TYPE: `bool` DEFAULT: `True`
`build_distance_variables`	If True includes a cluster distance variable in the deployment. TYPE: `bool` DEFAULT: `False`
`build_frequency_variables`	If True includes the frequency variables in the deployment. TYPE: `bool` DEFAULT: `False`
`variables_prefix`	Prefix for the variables in the deployment dictionary. TYPE: `str` DEFAULT: `""`

`deploy_predictor_for_metrics(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=70, sampling_mode='Include sample', additional_data_tables=None, output_header_line=True, output_field_separator='\t', trace=False)`

Deploys the necessary data to estimate the performance metrics of a predictor

For each instance for each instance it deploys:

The true value of the target variable
The predicted value of the target variable
The probabilities of each value of the target variable (classifier only)

Note

To obtain the data of the default Khiops test dataset use sample_percentage = 70` and `sampling_mode = "Exclude sample".

PARAMETER	DESCRIPTION
`dictionary_file_path_or_domain`	Path of a Khiops dictionary file or a DictionaryDomain object. TYPE: `str or DictionaryDomain`
`dictionary_name`	Name of the predictor dictionary. TYPE: `str`
`data_table_path`	Path of the data table file. TYPE: `str`
`output_data_table_path`	Path of the scores output data file. TYPE: `str`
`detect_format`	If True detects automatically whether the data table file has a header and its field separator. It's ignored if `header_line` or `field_separator` are set. TYPE: `bool` DEFAULT: `True`
`header_line`	If True it uses the first line of the data as column names. Overrides `detect_format` if set. TYPE: bool, optional (default `True` if `detect_format` is `False`) DEFAULT: `None`
`field_separator`	A field separator character, overrides `detect_format` if set ("" counts as "\t"). TYPE: str, optional (default "\\t" if `detect_format` is `False`) DEFAULT: `None`
`sample_percentage`	See `sampling_mode` option below. TYPE: `int` DEFAULT: `70`
`sampling_mode`	If equal to "Include sample" deploys the predictor on `sample_percentage` percent of data and if equal to "Exclude sample" on the complementary `100 - sample_percentage` percent of data. TYPE: `'Include sample' or 'Exclude sample'` DEFAULT: `"Include sample"`
`additional_data_tables`	A dictionary containing the data paths and file paths for a multi-table dictionary file. For more details see Multi-Table Learning Primer documentation. TYPE: `dict` DEFAULT: `None`
`output_header_line`	If True writes a header line containing the column names in the output table. TYPE: `bool` DEFAULT: `True`
`output_field_separator`	A field separator character ("" counts as "\t"). TYPE: `str` DEFAULT: `"\\t"`

`visualize_report(report_path)`

Opens a Khiops or Khiops Coclustering report with the desktop visualization app

Before using this function, make sure you have installed the Khiops Visualization app and/or the Khiops Co-Visualization app. More info at https://khiops.org/setup/visualization/

PARAMETER	DESCRIPTION
`report_path`	The path of the report file to be open. It must have extension '.khj' (Khiops report) or '.khcj' (Khiops Coclustering report). TYPE: `str`

RAISES	DESCRIPTION
`ValueError`	If the report file path does not have extension '.khj' or '.khcj'.
`FileNotFoundError`	If the report file does not exist.
`RuntimeError`	If the report file is executable.

RAISES	DESCRIPTION
`TypeError`	Invalid type `dictionary_file_path_or_domain` or `key_variable_names`
`ValueError`	If the type of the dictionary key variables is not equal to `Categorical`
`NotImplementedError`	If the coclustering to be deployed is of the instance-variable type