Skip to content

Commit dfdaf34

Browse files
tramoratramora
authored
Merge pull request #452 from KhiopsML/440-document-possible-variable-types
List all possible variable types in class ``Variable`` docstring
2 parents d47193a + 0e98c12 commit dfdaf34

4 files changed

Lines changed: 257 additions & 0 deletions

File tree

‎doc/samples/samples.rst‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,80 @@ Samples
5656
kh.build_dictionary_from_data_table(
5757
data_table_path, dictionary_name, dictionary_file_path
5858
)
59+
.. autofunction:: create_dictionary_domain
60+
.. code-block:: python
61+
62+
# Imports
63+
import os
64+
from khiops import core as kh
65+
66+
# Create a Root dictionary
67+
root_dictionary = kh.Dictionary(
68+
json_data={"name": "dict_from_scratch", "root": True, "key": ["Id"]}
69+
)
70+
71+
# Start with simple variables to declare
72+
simple_variables = [
73+
{"name": "Id", "type": "Categorical"},
74+
{"name": "Num", "type": "Numerical"},
75+
{"name": "text", "type": "Text"},
76+
{"name": "hour", "type": "Time"},
77+
{"name": "date", "type": "Date"},
78+
{"name": "ambiguous_ts", "type": "Timestamp"},
79+
{"name": "ts", "type": "TimestampTZ"},
80+
]
81+
for var_spec in simple_variables:
82+
var = kh.Variable()
83+
var.name = var_spec["name"]
84+
var.type = var_spec["type"]
85+
root_dictionary.add_variable(var)
86+
87+
# Create a second dictionary
88+
second_dictionary = kh.Dictionary(
89+
json_data={"name": "Service", "key": ["Id", "id_product"]}
90+
)
91+
second_dictionary.add_variable(
92+
kh.Variable(json_data={"name": "Id", "type": "Categorical"})
93+
)
94+
second_dictionary.add_variable(
95+
kh.Variable(json_data={"name": "id_product", "type": "Categorical"})
96+
)
97+
# Create a third dictionary
98+
third_dictionary = kh.Dictionary(json_data={"name": "Address", "key": ["Id"]})
99+
third_dictionary.add_variable(
100+
kh.Variable(json_data={"name": "StreetNumber", "type": "Numerical"})
101+
)
102+
third_dictionary.add_variable(
103+
kh.Variable(json_data={"name": "StreetName", "type": "Categorical"})
104+
)
105+
third_dictionary.add_variable(
106+
kh.Variable(json_data={"name": "id_city", "type": "Categorical"})
107+
)
108+
109+
# Add the variables used in a multi-table context in the first dictionary.
110+
# They link the root dictionary to the additional ones
111+
root_dictionary.add_variable(
112+
kh.Variable(json_data={"name": "Services", "type": "Table(Service)"})
113+
)
114+
root_dictionary.add_variable(
115+
kh.Variable(json_data={"name": "Address", "type": "Entity(Address)"})
116+
)
117+
118+
# Create a DictionaryDomain (set of dictionaries)
119+
dictionary_domain = kh.DictionaryDomain()
120+
dictionary_domain.add_dictionary(root_dictionary)
121+
dictionary_domain.add_dictionary(second_dictionary)
122+
dictionary_domain.add_dictionary(third_dictionary)
123+
124+
output_dir = os.path.join("kh_samples", "create_dictionary_domain")
125+
dictionary_file_path = os.path.join(output_dir, "dict_from_scratch.kdic")
126+
127+
# Create the output directory if needed
128+
if not os.path.isdir(output_dir):
129+
os.mkdir(output_dir)
130+
131+
# Write the dictionary domain to a file
132+
dictionary_domain.export_khiops_dictionary_file(dictionary_file_path)
59133
.. autofunction:: detect_data_table_format
60134
.. code-block:: python
61135

‎khiops/core/dictionary.py‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -971,6 +971,17 @@ class Variable:
971971
True if the variable is used.
972972
type : str
973973
Variable type.
974+
It can be either native (``Categorical``, ``Numerical``, ``Time``,
975+
``Date``, ``Timestamp``, ``TimestampTZ``, ``Text``),
976+
internal (``TextList``, ``Structure``)
977+
978+
- See https://khiops.org/11.0.0-b.0/api-docs/kdic/text-list-rules/
979+
- See https://khiops.org/11.0.0-b.0/api-docs/kdic/structures-introduction/
980+
981+
or relational (``Entity`` - 0-1 relationship, ``Table`` - 0-n relationship)
982+
983+
- See https://khiops.org/11.0.0-b.0/tutorials/kdic_multi_table/
984+
974985
object_type : str
975986
Type complement for the ``Table`` and ``Entity`` types.
976987
structure_type : str
@@ -989,6 +1000,11 @@ class Variable:
9891000
List of variable comments.
9901001
meta_data : `MetaData`
9911002
Variable metadata.
1003+
1004+
Examples
1005+
--------
1006+
See the following function of the ``samples.py`` documentation script:
1007+
- `samples.create_dictionary_domain()`
9921008
"""
9931009

9941010
def __init__(self, json_data=None):

‎khiops/samples/samples.ipynb‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,93 @@
5757
")"
5858
]
5959
},
60+
{
61+
"cell_type": "markdown",
62+
"metadata": {},
63+
"source": [
64+
"### `create_dictionary_domain()`\n\n",
65+
"Creates a dictionary domain from scratch\n\n This dictionary domain contains a set of dictionaries,\n with all possible variable types.\n \n"
66+
]
67+
},
68+
{
69+
"cell_type": "code",
70+
"execution_count": null,
71+
"metadata": {},
72+
"outputs": [],
73+
"source": [
74+
"# Imports\n",
75+
"import os\n",
76+
"from khiops import core as kh\n",
77+
"\n",
78+
"# Create a Root dictionary\n",
79+
"root_dictionary = kh.Dictionary(\n",
80+
" json_data={\"name\": \"dict_from_scratch\", \"root\": True, \"key\": [\"Id\"]}\n",
81+
")\n",
82+
"\n",
83+
"# Start with simple variables to declare\n",
84+
"simple_variables = [\n",
85+
" {\"name\": \"Id\", \"type\": \"Categorical\"},\n",
86+
" {\"name\": \"Num\", \"type\": \"Numerical\"},\n",
87+
" {\"name\": \"text\", \"type\": \"Text\"},\n",
88+
" {\"name\": \"hour\", \"type\": \"Time\"},\n",
89+
" {\"name\": \"date\", \"type\": \"Date\"},\n",
90+
" {\"name\": \"ambiguous_ts\", \"type\": \"Timestamp\"},\n",
91+
" {\"name\": \"ts\", \"type\": \"TimestampTZ\"},\n",
92+
"]\n",
93+
"for var_spec in simple_variables:\n",
94+
" var = kh.Variable()\n",
95+
" var.name = var_spec[\"name\"]\n",
96+
" var.type = var_spec[\"type\"]\n",
97+
" root_dictionary.add_variable(var)\n",
98+
"\n",
99+
"# Create a second dictionary\n",
100+
"second_dictionary = kh.Dictionary(\n",
101+
" json_data={\"name\": \"Service\", \"key\": [\"Id\", \"id_product\"]}\n",
102+
")\n",
103+
"second_dictionary.add_variable(\n",
104+
" kh.Variable(json_data={\"name\": \"Id\", \"type\": \"Categorical\"})\n",
105+
")\n",
106+
"second_dictionary.add_variable(\n",
107+
" kh.Variable(json_data={\"name\": \"id_product\", \"type\": \"Categorical\"})\n",
108+
")\n",
109+
"# Create a third dictionary\n",
110+
"third_dictionary = kh.Dictionary(json_data={\"name\": \"Address\", \"key\": [\"Id\"]})\n",
111+
"third_dictionary.add_variable(\n",
112+
" kh.Variable(json_data={\"name\": \"StreetNumber\", \"type\": \"Numerical\"})\n",
113+
")\n",
114+
"third_dictionary.add_variable(\n",
115+
" kh.Variable(json_data={\"name\": \"StreetName\", \"type\": \"Categorical\"})\n",
116+
")\n",
117+
"third_dictionary.add_variable(\n",
118+
" kh.Variable(json_data={\"name\": \"id_city\", \"type\": \"Categorical\"})\n",
119+
")\n",
120+
"\n",
121+
"# Add the variables used in a multi-table context in the first dictionary.\n",
122+
"# They link the root dictionary to the additional ones\n",
123+
"root_dictionary.add_variable(\n",
124+
" kh.Variable(json_data={\"name\": \"Services\", \"type\": \"Table(Service)\"})\n",
125+
")\n",
126+
"root_dictionary.add_variable(\n",
127+
" kh.Variable(json_data={\"name\": \"Address\", \"type\": \"Entity(Address)\"})\n",
128+
")\n",
129+
"\n",
130+
"# Create a DictionaryDomain (set of dictionaries)\n",
131+
"dictionary_domain = kh.DictionaryDomain()\n",
132+
"dictionary_domain.add_dictionary(root_dictionary)\n",
133+
"dictionary_domain.add_dictionary(second_dictionary)\n",
134+
"dictionary_domain.add_dictionary(third_dictionary)\n",
135+
"\n",
136+
"output_dir = os.path.join(\"kh_samples\", \"create_dictionary_domain\")\n",
137+
"dictionary_file_path = os.path.join(output_dir, \"dict_from_scratch.kdic\")\n",
138+
"\n",
139+
"# Create the output directory if needed\n",
140+
"if not os.path.isdir(output_dir):\n",
141+
" os.mkdir(output_dir)\n",
142+
"\n",
143+
"# Write the dictionary domain to a file\n",
144+
"dictionary_domain.export_khiops_dictionary_file(dictionary_file_path)"
145+
]
146+
},
60147
{
61148
"cell_type": "markdown",
62149
"metadata": {},

‎khiops/samples/samples.py‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,85 @@ def build_dictionary_from_data_table():
6565
)
6666

6767

68+
def create_dictionary_domain():
69+
"""Creates a dictionary domain from scratch
70+
71+
This dictionary domain contains a set of dictionaries,
72+
with all possible variable types.
73+
"""
74+
# Imports
75+
import os
76+
from khiops import core as kh
77+
78+
# Create a Root dictionary
79+
root_dictionary = kh.Dictionary(
80+
json_data={"name": "dict_from_scratch", "root": True, "key": ["Id"]}
81+
)
82+
83+
# Start with simple variables to declare
84+
simple_variables = [
85+
{"name": "Id", "type": "Categorical"},
86+
{"name": "Num", "type": "Numerical"},
87+
{"name": "text", "type": "Text"},
88+
{"name": "hour", "type": "Time"},
89+
{"name": "date", "type": "Date"},
90+
{"name": "ambiguous_ts", "type": "Timestamp"},
91+
{"name": "ts", "type": "TimestampTZ"},
92+
]
93+
for var_spec in simple_variables:
94+
var = kh.Variable()
95+
var.name = var_spec["name"]
96+
var.type = var_spec["type"]
97+
root_dictionary.add_variable(var)
98+
99+
# Create a second dictionary
100+
second_dictionary = kh.Dictionary(
101+
json_data={"name": "Service", "key": ["Id", "id_product"]}
102+
)
103+
second_dictionary.add_variable(
104+
kh.Variable(json_data={"name": "Id", "type": "Categorical"})
105+
)
106+
second_dictionary.add_variable(
107+
kh.Variable(json_data={"name": "id_product", "type": "Categorical"})
108+
)
109+
# Create a third dictionary
110+
third_dictionary = kh.Dictionary(json_data={"name": "Address", "key": ["Id"]})
111+
third_dictionary.add_variable(
112+
kh.Variable(json_data={"name": "StreetNumber", "type": "Numerical"})
113+
)
114+
third_dictionary.add_variable(
115+
kh.Variable(json_data={"name": "StreetName", "type": "Categorical"})
116+
)
117+
third_dictionary.add_variable(
118+
kh.Variable(json_data={"name": "id_city", "type": "Categorical"})
119+
)
120+
121+
# Add the variables used in a multi-table context in the first dictionary.
122+
# They link the root dictionary to the additional ones
123+
root_dictionary.add_variable(
124+
kh.Variable(json_data={"name": "Services", "type": "Table(Service)"})
125+
)
126+
root_dictionary.add_variable(
127+
kh.Variable(json_data={"name": "Address", "type": "Entity(Address)"})
128+
)
129+
130+
# Create a DictionaryDomain (set of dictionaries)
131+
dictionary_domain = kh.DictionaryDomain()
132+
dictionary_domain.add_dictionary(root_dictionary)
133+
dictionary_domain.add_dictionary(second_dictionary)
134+
dictionary_domain.add_dictionary(third_dictionary)
135+
136+
output_dir = os.path.join("kh_samples", "create_dictionary_domain")
137+
dictionary_file_path = os.path.join(output_dir, "dict_from_scratch.kdic")
138+
139+
# Create the output directory if needed
140+
if not os.path.isdir(output_dir):
141+
os.mkdir(output_dir)
142+
143+
# Write the dictionary domain to a file
144+
dictionary_domain.export_khiops_dictionary_file(dictionary_file_path)
145+
146+
68147
def detect_data_table_format():
69148
"""Detects the format of a data table with and without a dictionary file
70149
@@ -1987,6 +2066,7 @@ def build_deployed_dictionary():
19872066
exported_samples = [
19882067
get_khiops_version,
19892068
build_dictionary_from_data_table,
2069+
create_dictionary_domain,
19902070
detect_data_table_format,
19912071
check_database,
19922072
export_dictionary_files,

0 commit comments

Comments
 (0)