dragon-ml-toolbox 19.13.0__py3-none-any.whl → 20.0.0__py3-none-any.whl

ml_tools/schema/_gui_schema.py

@@ -0,0 +1,191 @@
+from typing import Union, Any
+from pathlib import Path
+import json
+
+from ..path_manager import make_fullpath
+
+from ..keys._keys import SchemaKeys
+from .._core import get_logger
+
+from ._feature_schema import FeatureSchema
+
+
+_LOGGER = get_logger("GUISchema")
+
+
+__all__ = [
+    "create_guischema_template",
+    "make_multibinary_groups",
+]
+
+
+def create_guischema_template(
+    directory: Union[str, Path],
+    feature_schema: FeatureSchema,
+    targets: list[str],
+    continuous_ranges: dict[str, tuple[float, float]],
+    multibinary_groups: Union[dict[str, list[str]], None] = None,
+) -> None:
+    """
+    Generates a 'GUISchema.json' boilerplate file based on the Model FeatureSchema.
+    
+    The generated JSON contains entries with empty "gui_name" fields for manual mapping.
+    Leave 'gui_name' empty to use auto-formatted Title Case.
+    
+    Args:
+        directory (str | Path): Where to save the json file.
+        feature_schema (FeatureSchema): The source FeatureSchema object.
+        targets (list[str]): List of target names as used in the ML pipeline.
+        continuous_ranges (Dict[str, Tuple[float, float]]): Dict {model_name: (min, max)}.
+        multibinary_groups (Dict[str, list[str]] | None): Optional Dict {GUI_Group_Name: [model_col_1, model_col_2]}.
+                            Used to group binary columns into a single multi-select list.
+    """
+    dir_path = make_fullpath(directory, make=True, enforce="directory")
+        
+    schema = feature_schema
+    output_data: dict[str, Any] = {
+        SchemaKeys.TARGETS: [],
+        SchemaKeys.CONTINUOUS: [],
+        SchemaKeys.BINARY: [],
+        SchemaKeys.MULTIBINARY: {}, # Structure: GroupName: [{model: x, gui: ""}]
+        SchemaKeys.CATEGORICAL: []
+    }
+
+    # Track handled columns to prevent duplicates in binary/categorical
+    handled_cols = set()
+
+    # 1. Targets
+    for t in targets:
+        output_data[SchemaKeys.TARGETS].append({
+            SchemaKeys.MODEL_NAME: t,
+            SchemaKeys.GUI_NAME: "" # User to fill
+        })
+
+    # 2. Continuous
+    # Validate ranges against schema
+    schema_cont_set = set(schema.continuous_feature_names)
+    for name, min_max in continuous_ranges.items():
+        if name in schema_cont_set:
+            output_data[SchemaKeys.CONTINUOUS].append({
+                SchemaKeys.MODEL_NAME: name,
+                SchemaKeys.GUI_NAME: "",
+                SchemaKeys.MIN_VALUE: min_max[0],
+                SchemaKeys.MAX_VALUE: min_max[1]
+            })
+            handled_cols.add(name)
+        else:
+            _LOGGER.warning(f"GUISchema: Provided range for '{name}', but it is not in FeatureSchema continuous list.")
+
+    # 3. Multi-Binary Groups
+    if multibinary_groups:
+        # Check for validity within the generic feature list
+        all_feats = set(schema.feature_names)
+        
+        for group_name, cols in multibinary_groups.items():
+            # Validation: Groups cannot be empty
+            if not cols:
+                # warn and skip
+                _LOGGER.warning(f"GUISchema: Multi-binary group '{group_name}' is empty and will be skipped.")
+                continue
+
+            group_options = []
+            for col in cols:
+                # Validation: Columns must exist in schema
+                if col not in all_feats:
+                    # warn and skip
+                    _LOGGER.warning(f"GUISchema: Multi-binary column '{col}' in group '{group_name}' not found in FeatureSchema. Skipping.")
+                    continue
+                # else, add to group
+                group_options.append({
+                    SchemaKeys.MODEL_NAME: col,
+                    SchemaKeys.GUI_NAME: "" 
+                })
+                handled_cols.add(col)
+            output_data[SchemaKeys.MULTIBINARY][group_name] = group_options
+
+    # 4. Binary & Categorical (Derived from Schema Mappings)
+    if schema.categorical_mappings:
+        for name, mapping in schema.categorical_mappings.items():
+            if name in handled_cols:
+                continue
+            
+            # Heuristic: Cardinality 2 = Binary, >2 = Categorical
+            if len(mapping) == 2:
+                output_data[SchemaKeys.BINARY].append({
+                    SchemaKeys.MODEL_NAME: name,
+                    SchemaKeys.GUI_NAME: "" # User to fill
+                })
+            else:
+                # For categorical, we also allow renaming the specific options
+                options_with_names = {k: "" for k in mapping.keys()} # Default gui_option = model_option
+                
+                output_data[SchemaKeys.CATEGORICAL].append({
+                    SchemaKeys.MODEL_NAME: name,
+                    SchemaKeys.GUI_NAME: "", # User to fill feature name
+                    SchemaKeys.MAPPING: mapping, # Original mapping
+                    SchemaKeys.OPTIONAL_LABELS: options_with_names # User can edit keys here
+                })
+
+    save_path = dir_path / SchemaKeys.GUI_SCHEMA_FILENAME
+    try:
+        with open(save_path, 'w', encoding='utf-8') as f:
+            json.dump(output_data, f, indent=4)
+        _LOGGER.info(f"GUISchema template generated at: '{dir_path.name}/{SchemaKeys.GUI_SCHEMA_FILENAME}'")
+    except IOError as e:
+        _LOGGER.error(f"Failed to save GUISchema template: {e}")
+
+
+def make_multibinary_groups(
+    feature_schema: FeatureSchema,
+    group_prefixes: list[str],
+    separator: str = "_"
+) -> dict[str, list[str]]:
+    """
+    Helper to automate creating the multibinary_groups dictionary for create_guischema_template.
+
+    Iterates through provided prefixes and groups categorical features that contain
+    the pattern '{prefix}{separator}'.
+
+    Args:
+        feature_schema: The loaded FeatureSchema containing categorical feature names.
+        group_prefixes: A list of group prefixes to search for.
+        separator: The separator used in Multibinary Encoding (default '_').
+
+    Returns:
+        Dict[str, list[str]]: A dictionary mapping group names to their found column names.
+    """
+    groups: dict[str, list[str]] = {}
+    
+    # check that categorical features exist
+    if not feature_schema.categorical_feature_names:
+        _LOGGER.error("FeatureSchema has no categorical features defined.")
+        raise ValueError()
+    
+    # validate separator
+    if not separator or not isinstance(separator, str):
+        _LOGGER.error(f"Invalid separator '{separator}' of type {type(separator)}.")
+        raise ValueError()
+
+    for prefix in group_prefixes:
+        if not prefix or not isinstance(prefix, str):
+            _LOGGER.error(f"Invalid prefix '{prefix}' of type {type(prefix)}.")
+            raise ValueError()
+        
+        search_term = f"{prefix}{separator}"
+        
+        # check if substring exists in the column name. must begin with prefix+separator
+        cols = [
+            name for name in feature_schema.categorical_feature_names
+            if name.startswith(search_term)
+        ]
+
+        if cols:
+            groups[prefix] = cols
+        else:
+            _LOGGER.warning(f"No columns found for group '{prefix}' using search term '{search_term}'")
+            
+    # log resulting groups
+    _LOGGER.info(f"Multibinary groups created: {list(groups.keys())}")
+
+    return groups
+

ml_tools/schema/_imprimir.py

@@ -0,0 +1,10 @@
+from .._core import _imprimir_disponibles
+
+_GRUPOS = [
+    "FeatureSchema",
+    "create_guischema_template",
+    "make_multibinary_groups",
+]
+
+def info():
+    _imprimir_disponibles(_GRUPOS)

ml_tools/{serde.py → serde/__init__.py}

@@ -1,10 +1,12 @@
-from ._core._serde import (
+from ._serde import (
     serialize_object_filename,
     serialize_object,
     deserialize_object,
-    info
 )
 
+from ._imprimir import info
+
+
 __all__ = [
     "serialize_object_filename",
     "serialize_object",

ml_tools/serde/_imprimir.py

@@ -0,0 +1,10 @@
+from .._core import _imprimir_disponibles
+
+_GRUPOS = [
+    "serialize_object_filename",
+    "serialize_object",
+    "deserialize_object",
+]
+
+def info():
+    _imprimir_disponibles(_GRUPOS)

ml_tools/{_core → serde}/_serde.py

@@ -3,9 +3,8 @@ from joblib.externals.loky.process_executor import TerminatedWorkerError
 from typing import Any, Union, TypeVar, get_origin, Type, Optional
 from pathlib import Path
 
-from ._path_manager import make_fullpath, sanitize_filename
-from ._script_info import _script_info
-from ._logger import get_logger
+from ..path_manager import make_fullpath, sanitize_filename
+from .._core import get_logger
 
 
 _LOGGER = get_logger("SERDE")
@@ -95,7 +94,7 @@ def serialize_object(obj: Any, file_path: Path, verbose: bool = True, raise_on_e
 
 # Define a TypeVar to link the expected type to the return type of deserialization
 T = TypeVar('T')
-    
+
 def deserialize_object(
     filepath: Union[str, Path],
     expected_type: Optional[Type[T]] = None,
@@ -146,7 +145,3 @@ def deserialize_object(
                 _LOGGER.info(f"Loaded object '{obj}' from '{true_filepath}'.")
         
         return obj # type: ignore
-
-
-def info():
-    _script_info(__all__)

ml_tools/{utilities.py → utilities/__init__.py}

@@ -1,27 +1,32 @@
-from ._core._utilities import (
+from ._utility_save_load import (
     load_dataframe,
     load_dataframe_greedy,
     load_dataframe_with_schema,
     yield_dataframes_from_dir,
-    merge_dataframes,
     save_dataframe_filename,
     save_dataframe,
-    save_dataframe_with_schema,
+    save_dataframe_with_schema
+)
+
+from ._utility_tools import (
+    merge_dataframes,
     distribute_dataset_by_target,
     train_dataset_orchestrator,
-    train_dataset_yielder,
-    info
+    train_dataset_yielder
 )
 
+from ._imprimir import info
+
+
 __all__ = [
     "load_dataframe",
     "load_dataframe_greedy",
     "load_dataframe_with_schema",
     "yield_dataframes_from_dir",
-    "merge_dataframes",
     "save_dataframe_filename",
     "save_dataframe",
     "save_dataframe_with_schema",
+    "merge_dataframes",
     "distribute_dataset_by_target",
     "train_dataset_orchestrator",
     "train_dataset_yielder"

ml_tools/utilities/_imprimir.py

@@ -0,0 +1,18 @@
+from .._core import _imprimir_disponibles
+
+_GRUPOS = [
+    "load_dataframe",
+    "load_dataframe_greedy",
+    "load_dataframe_with_schema",
+    "yield_dataframes_from_dir",
+    "save_dataframe_filename",
+    "save_dataframe",
+    "save_dataframe_with_schema",
+    "merge_dataframes",
+    "distribute_dataset_by_target",
+    "train_dataset_orchestrator",
+    "train_dataset_yielder"
+]
+
+def info():
+    _imprimir_disponibles(_GRUPOS)

ml_tools/{_core/_utilities.py → utilities/_utility_save_load.py}

@@ -1,16 +1,16 @@
-import numpy as np
 import pandas as pd
 import polars as pl
+import numpy as np
 from pathlib import Path
-from typing import Literal, Union, Optional, Any, Iterator, Tuple, overload
+from typing import Literal, Union, Optional, Any, overload
+
+from ..schema import FeatureSchema
 
-from ._path_manager import sanitize_filename, make_fullpath, list_csv_paths
-from ._script_info import _script_info
-from ._logger import get_logger
-from ._schema import FeatureSchema
+from ..path_manager import make_fullpath, list_csv_paths, sanitize_filename
+from .._core import get_logger
 
 
-_LOGGER = get_logger("Utilities")
+_LOGGER = get_logger("Save/Load Utilities")
 
 
 __all__ = [
@@ -18,16 +18,13 @@ __all__ = [
     "load_dataframe_greedy",
     "load_dataframe_with_schema",
     "yield_dataframes_from_dir",
-    "merge_dataframes",
     "save_dataframe_filename",
     "save_dataframe",
-    "save_dataframe_with_schema",
-    "distribute_dataset_by_target",
-    "train_dataset_orchestrator",
-    "train_dataset_yielder"
+    "save_dataframe_with_schema"
 ]
 
 
+
 # Overload 1: When kind='pandas'
 @overload
 def load_dataframe(
@@ -36,7 +33,7 @@ def load_dataframe(
     kind: Literal["pandas"] = "pandas",
     all_strings: bool = False,
     verbose: bool = True
-) -> Tuple[pd.DataFrame, str]:
+) -> tuple[pd.DataFrame, str]:
     ... # for overload stubs
 
 # Overload 2: When kind='polars'
@@ -47,7 +44,7 @@ def load_dataframe(
     kind: Literal["polars"] = "polars",
     all_strings: bool = False,
     verbose: bool = True
-) -> Tuple[pl.DataFrame, str]:
+) -> tuple[pl.DataFrame, str]:
     ... # for overload stubs
 
 def load_dataframe(
@@ -56,7 +53,7 @@ def load_dataframe(
     kind: Literal["pandas", "polars"] = "pandas",
     all_strings: bool = False,
     verbose: bool = True
-) -> Union[Tuple[pd.DataFrame, str], Tuple[pl.DataFrame, str]]:
+) -> Union[tuple[pd.DataFrame, str], tuple[pl.DataFrame, str]]:
     """
     Load a CSV file into a DataFrame and extract its base name.
 
@@ -187,7 +184,7 @@ def load_dataframe_with_schema(
     df_path: Union[str, Path], 
     schema: "FeatureSchema",
     all_strings: bool = False,
-) -> Tuple[pd.DataFrame, str]:
+) -> tuple[pd.DataFrame, str]:
     """
     Loads a CSV file into a Pandas DataFrame, strictly validating its
     feature columns against a FeatureSchema.
@@ -271,65 +268,6 @@ def yield_dataframes_from_dir(datasets_dir: Union[str,Path], verbose: bool=True)
         yield df, df_name
 
 
-def merge_dataframes(
-    *dfs: pd.DataFrame,
-    reset_index: bool = False,
-    direction: Literal["horizontal", "vertical"] = "horizontal",
-    verbose: bool=True
-) -> pd.DataFrame:
-    """
-    Merges multiple DataFrames either horizontally or vertically.
-
-    Parameters:
-        *dfs (pd.DataFrame): Variable number of DataFrames to merge.
-        reset_index (bool): Whether to reset index in the final merged DataFrame.
-        direction (["horizontal" | "vertical"]):
-            - "horizontal": Merge on index, adding columns.
-            - "vertical": Append rows; all DataFrames must have identical columns.
-
-    Returns:
-        pd.DataFrame: A single merged DataFrame.
-
-    Raises:
-        ValueError:
-            - If fewer than 2 DataFrames are provided.
-            - If indexes do not match for horizontal merge.
-            - If column names or order differ for vertical merge.
-    """
-    if len(dfs) < 2:
-        raise ValueError("❌ At least 2 DataFrames must be provided.")
-    
-    if verbose:
-        for i, df in enumerate(dfs, start=1):
-            print(f"➡️ DataFrame {i} shape: {df.shape}")
-    
-
-    if direction == "horizontal":
-        reference_index = dfs[0].index
-        for i, df in enumerate(dfs, start=1):
-            if not df.index.equals(reference_index):
-                raise ValueError(f"❌ Indexes do not match: Dataset 1 and Dataset {i}.")
-        merged_df = pd.concat(dfs, axis=1)
-
-    elif direction == "vertical":
-        reference_columns = dfs[0].columns
-        for i, df in enumerate(dfs, start=1):
-            if not df.columns.equals(reference_columns):
-                raise ValueError(f"❌ Column names/order do not match: Dataset 1 and Dataset {i}.")
-        merged_df = pd.concat(dfs, axis=0)
-
-    else:
-        _LOGGER.error(f"Invalid merge direction: {direction}")
-        raise ValueError()
-
-    if reset_index:
-        merged_df = merged_df.reset_index(drop=True)
-    
-    if verbose:
-        _LOGGER.info(f"Merged DataFrame shape: {merged_df.shape}")
-
-    return merged_df
-
 
 def save_dataframe_filename(df: Union[pd.DataFrame, pl.DataFrame], save_dir: Union[str,Path], filename: str) -> None:
     """
@@ -448,118 +386,6 @@ def save_dataframe_with_schema(
     save_dataframe(df=df_to_save, full_path=full_path)
 
 
-def distribute_dataset_by_target(
-    df_or_path: Union[pd.DataFrame, str, Path],
-    target_columns: list[str],
-    verbose: bool = False
-) -> Iterator[Tuple[str, pd.DataFrame]]:
-    """
-    Yields cleaned DataFrames for each target column, where rows with missing
-    target values are removed. The target column is placed at the end.
-
-    Parameters
-    ----------
-    df_or_path : [pd.DataFrame | str | Path]
-        Dataframe or path to Dataframe with all feature and target columns ready to split and train a model.
-    target_columns : List[str]
-        List of target column names to generate per-target DataFrames.
-    verbose: bool
-        Whether to print info for each yielded dataset.
-
-    Yields
-    ------
-    Tuple[str, pd.DataFrame]
-        * Target name.
-        * Pandas DataFrame.
-    """
-    # Validate path or dataframe
-    if isinstance(df_or_path, str) or isinstance(df_or_path, Path):
-        df_path = make_fullpath(df_or_path)
-        df, _ = load_dataframe(df_path)
-    else:
-        df = df_or_path
-    
-    valid_targets = [col for col in df.columns if col in target_columns]
-    feature_columns = [col for col in df.columns if col not in valid_targets]
-
-    for target in valid_targets:
-        subset = df[feature_columns + [target]].dropna(subset=[target]) # type: ignore
-        if verbose:
-            print(f"Target: '{target}' - Dataframe shape: {subset.shape}")
-        yield target, subset
-
-
-def train_dataset_orchestrator(list_of_dirs: list[Union[str,Path]], 
-                               target_columns: list[str], 
-                               save_dir: Union[str,Path],
-                               safe_mode: bool=False):
-    """
-    Orchestrates the creation of single-target datasets from multiple directories each with a variable number of CSV datasets.
-
-    This function iterates through a list of directories, finds all CSV files,
-    and splits each dataframe based on the provided target columns. Each resulting
-    single-target dataframe is then saved to a specified directory.
-
-    Parameters
-    ----------
-    list_of_dirs : list[str | Path]
-        A list of directory paths where the source CSV files are located.
-    target_columns : list[str]
-        A list of column names to be used as targets for splitting the datasets.
-    save_dir : str | Path
-        The directory where the newly created single-target datasets will be saved.
-    safe_mode : bool
-        If True, prefixes the saved filename with the source directory name to prevent overwriting files with the same name from different sources.
-    """
-    all_dir_paths: list[Path] = list()
-    for dir in list_of_dirs:
-        dir_path = make_fullpath(dir)
-        if not dir_path.is_dir():
-            _LOGGER.error(f"'{dir}' is not a directory.")
-            raise IOError()
-        all_dir_paths.append(dir_path)
-    
-    # main loop
-    total_saved = 0
-    for df_dir in all_dir_paths:
-        for df_name, df_path in list_csv_paths(df_dir).items():
-            try:
-                for target_name, df in distribute_dataset_by_target(df_or_path=df_path, target_columns=target_columns, verbose=False):
-                    if safe_mode:
-                        filename = df_dir.name + '_' + target_name + '_' + df_name
-                    else:
-                        filename = target_name + '_' + df_name
-                    save_dataframe_filename(df=df, save_dir=save_dir, filename=filename)
-                    total_saved += 1
-            except Exception as e:
-                _LOGGER.error(f"Failed to process file '{df_path}'. Reason: {e}")
-                continue 
-
-    _LOGGER.info(f"{total_saved} single-target datasets were created.")
-
-
-def train_dataset_yielder(
-    df: pd.DataFrame,
-    target_cols: list[str]
-) -> Iterator[Tuple[pd.DataFrame, pd.Series, list[str], str]]:
-    """ 
-    Yields one tuple at a time:
-        (features_dataframe, target_series, feature_names, target_name)
-
-    Skips any target columns not found in the DataFrame.
-    """
-    # Determine which target columns actually exist in the DataFrame
-    valid_targets = [col for col in target_cols if col in df.columns]
-
-    # Features = all columns excluding valid target columns
-    df_features = df.drop(columns=valid_targets)
-    feature_names = df_features.columns.to_list()
-
-    for target_col in valid_targets:
-        df_target = df[target_col]
-        yield (df_features, df_target, feature_names, target_col)
-
-
 def _validate_and_reorder_schema(
     df: pd.DataFrame, 
     schema: "FeatureSchema"
@@ -626,6 +452,3 @@ def _validate_and_reorder_schema(
     
     return df_to_process # type: ignore
 
-
-def info():
-    _script_info(__all__)