focal.config_schema module¶

Configuration schema module for the FOCAL application.

This module defines Pydantic models for validating and loading JSON configuration files for all CLI modes. Each mode has its own config class, inheriting common fields and validators from BaseConfig, EarlyStoppingMixin, and CheckpointMixin.

class focal.config_schema.BaseConfig(*, csv_path: Path, img_folder: Path, mode: str, image_shape: List[int], set_mask: str | None = None, feature_shape: List[int] | None = None)[source]¶

Bases: BaseModel

Basic config for all classes.

csv_path: Path¶

feature_shape: List[int] | None¶

image_shape: List[int]¶

img_folder: Path¶

mode: str¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod path_exists(value)[source]¶

set_mask: str | None¶

classmethod valid_modes(value)[source]¶

class focal.config_schema.CNNHyperparameterConfig(*, csv_path: Path, img_folder: Path, mode: str, image_shape: List[int], set_mask: str | None = None, feature_shape: List[int] | None = None, tuner_directory: str, project_name: str, model_path: str, backbone: str, angle_threshold: float, diameter_threshold: float, test_size: float, batch_size: int, buffer_size: int, max_epochs: int, train_p: float, test_p: float, save_model_file: str | None)[source]¶

Bases: BaseConfig

angle_threshold: float¶

backbone: str¶

batch_size: int¶

buffer_size: int¶

diameter_threshold: float¶

max_epochs: int¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_path: str¶

project_name: str¶

save_model_file: str | None¶

test_p: float¶

test_size: float¶

train_p: float¶

tuner_directory: str¶

class focal.config_schema.CheckpointMixin(*, checkpoints: str | None = 'n', checkpoint_filepath: Path | None = None, monitor: str | None = 'val_accuracy', method: Literal['max', 'min'] = 'max')[source]¶

Bases: BaseModel

Adds model-checkpointing configuration parameters.

checkpoint_filepath: Path | None¶

checkpoints: str | None¶

method: Literal['max', 'min']¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

monitor: str | None¶

class focal.config_schema.EarlyStoppingMixin(*, early_stopping: str | None = 'n', patience: int | None = 3, monitor: str | None = 'val_accuracy', method: Literal['max', 'min'] = 'max')[source]¶

Bases: BaseModel

Adds early-stopping configuration parameters.

early_stopping: str | None¶

method: Literal['max', 'min']¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

monitor: str | None¶

patience: int | None¶

class focal.config_schema.GradCamConfig(*, mode: str, image_path: str, model_path: str, class_index: int, title: str, multiple_images: str | None = 'y', save_path: str | None, img_folder: str | None, fig_size: List[int] | None = (9, 5), backbone: str | None = 'efficientnet', conv_layer_name: str | None = 'top_conv', heatmap_file: str | None = None)[source]¶

Bases: BaseModel

backbone: str | None¶

class_index: int¶

conv_layer_name: str | None¶

fig_size: List[int] | None¶

heatmap_file: str | None¶

image_path: str¶

img_folder: str | None¶

mode: str¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_path: str¶

multiple_images: str | None¶

save_path: str | None¶

title: str¶

Bases: TrainImageOnlyConfig

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class focal.config_schema.MLPHyperparameterConfig(*, csv_path: Path, img_folder: Path, mode: str, image_shape: List[int], set_mask: str | None = None, feature_shape: List[int] | None = None, tuner_directory: str, project_name: str, model_path: str, backbone: str, angle_threshold: float, diameter_threshold: float, test_size: float, batch_size: int, buffer_size: int, max_epochs: int, save_model_file: str | None)[source]¶

Bases: BaseConfig

angle_threshold: float¶

backbone: str¶

batch_size: int¶

buffer_size: int¶

diameter_threshold: float¶

max_epochs: int¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_path: str¶

project_name: str¶

save_model_file: str | None¶

test_size: float¶

tuner_directory: str¶

Bases: BaseConfig, EarlyStoppingMixin, CheckpointMixin

Configuration for building, training, and evaluating a machine learning model.

This class centralizes all hyperparameters and paths needed for the entire ML pipeline, from data loading and augmentation to model training, tuning, and saving artifacts. It inherits settings for early stopping and model checkpointing from its mixins.

batch_size: int | None¶

brightness: float | None¶

buffer_size: int | None¶

classification_path: str | None¶

continue_train: str | None¶

contrast: float | None¶

encoder_path: str | None¶

feature_scaler_path: str | None¶

height: float | None¶

initial_epochs: int | None¶

label_scaler_path: str | None¶

learning_rate: float | None¶

max_epochs: int | None¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_path: str | None¶

objective: str | None¶

project_name: str | None¶

rotation: float | None¶

save_history_file: str | None¶

save_model_file: str | None¶

test_size: float | None¶

tuner_directory: str | None¶

width: float | None¶

class focal.config_schema.TestCNNConfig(*, csv_path: Path, img_folder: Path, mode: str, image_shape: List[int], set_mask: str | None = None, feature_shape: List[int] | None = None, classification_threshold: float | None = 0.5, cnn_mode: str, tension_threshold: int | None = 190, tension_model_path: str | None = None, feature_scaler_path: str | None = None, model_path: str | None = None, test_features: List[float] | None = None, img_path: str | None = None, label_scaler_path: str | None = None, encoder_path: str | None = None, backbone: str | None = None, classification_path: str | None = None, angle_threshold: float, diameter_threshold: float)[source]¶

Bases: BaseConfig

angle_threshold: float¶

backbone: str | None¶

classification_path: str | None¶

classification_threshold: float | None¶

cnn_mode: str¶

diameter_threshold: float¶

encoder_path: str | None¶

feature_scaler_path: str | None¶

img_path: str | None¶

label_scaler_path: str | None¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_path: str | None¶

tension_model_path: str | None¶

tension_threshold: int | None¶

test_features: List[float] | None¶

valid_shapes()[source]¶

class focal.config_schema.TestImageOnlyConfig(*, csv_path: Path, img_folder: Path, mode: str, image_shape: List[int], set_mask: str | None = None, feature_shape: List[int] | None = None, angle_threshold: float, diameter_threshold: float, model_path: str | None = None, encoder_path: str | None = None, img_path: str | None = None, backbone: str | None = None, classification_type: Literal['binary', 'multiclass'] = 'binary', classification_path: str | None = None)[source]¶

Bases: BaseConfig

angle_threshold: float¶

backbone: str | None¶

classification_path: str | None¶

classification_type: Literal['binary', 'multiclass']¶

diameter_threshold: float¶

encoder_path: str | None¶

img_path: str | None¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_path: str | None¶

class focal.config_schema.TestMLPConfig(*, csv_path: Path, img_folder: Path, mode: str, image_shape: List[int], set_mask: str | None = None, feature_shape: List[int] | None = None, angle_threshold: float, diameter_threshold: float, label_scaler_path: str | None = None, model_path: str | None = None, img_path: str | None = None, test_features: List[float] | None = None)[source]¶

Bases: BaseConfig

angle_threshold: float¶

diameter_threshold: float¶

img_path: str | None¶

label_scaler_path: str | None¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_path: str | None¶

test_features: List[float] | None¶

valid_shapes()[source]¶

class focal.config_schema.TestRLConfig(*, csv_path: str, cnn_path: str, agent_path: str, mode: str, img_folder: str, threshold: float, max_tension_change: float | None = 10.0, max_steps: int | None = 15, feature_shape: List[int], buffer_size: int | None = 1000000, batch_size: int | None = 256, tau: float | None = 0.1, learning_rate: float | None = 0.0001, timesteps: int | None = 5000, low_range: float | None = 0.7, high_range: float | None = 1.4, max_delta: float | None = 5.0, episodes: int, run_name: str)[source]¶

Bases: TrainRLConfig

episodes: int¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

run_name: str¶

class focal.config_schema.TestXGBoostConfig(*, csv_path: Path, img_folder: Path, mode: str, image_shape: List[int], set_mask: str | None = None, feature_shape: List[int] | None = None, angle_threshold: float, diameter_threshold: float, label_scaler_path: str | None = None, model_path: str | None = None, img_path: str | None = None, test_features: List[float] | None = None, xgb_path: str)[source]¶

Bases: TestMLPConfig

angle_threshold: float¶

diameter_threshold: float¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

xgb_path: str¶

class focal.config_schema.TrainCNNConfig(*, checkpoints: str | None = 'n', checkpoint_filepath: Path | None = None, monitor: str | None = 'val_accuracy', method: Literal['max', 'min'] = 'max', early_stopping: str | None = 'n', patience: int | None = 3, csv_path: Path, img_folder: Path, mode: str, image_shape: List[int], set_mask: str | None = None, feature_shape: List[int], brightness: float | None = 0.0, rotation: float | None = 0.0, height: float | None = 0.0, width: float | None = 0.0, contrast: float | None = 0.0, feature_scaler_path: str | None = None, label_scaler_path: str | None = None, model_path: str | None = None, classification_path: str | None = None, encoder_path: str | None = None, save_model_file: str | None = None, save_history_file: str | None = None, tuner_directory: str | None = None, project_name: str | None = None, learning_rate: float | None = 0.001, buffer_size: int | None = 32, batch_size: int | None = 8, test_size: float | None = 0.2, max_epochs: int | None = None, objective: str | None = None, initial_epochs: int | None = None, continue_train: str | None = None, cnn_mode: str, num_classes: int, dropout1: float, dense1: int, dropout2: float, dense2: int, dropout3: float, angle_threshold: float, diameter_threshold: float, train_p: float, test_p: float, tension_threshold: int | None = 190, backbone: str | None = 'efficientnet', unfreeze_from: int | None = None, reduce_lr: float | None = None, reduce_lr_patience: int | None = None, classification_type: Literal['binary', 'multiclass'] = 'binary')[source]¶

Bases: ModelConfig

angle_threshold: float¶

backbone: str | None¶

classification_type: Literal['binary', 'multiclass']¶

cnn_mode: str¶

dense1: int¶

dense2: int¶

diameter_threshold: float¶

dropout1: float¶

dropout2: float¶

dropout3: float¶

feature_shape: List[int]¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

num_classes: int¶

reduce_lr: float | None¶

reduce_lr_patience: int | None¶

tension_threshold: int | None¶

test_p: float¶

train_p: float¶

unfreeze_from: int | None¶

valid_shapes()[source]¶

Bases: ModelConfig

Configuration for training an image-only classification model.

angle_threshold: float¶

backbone: str¶

best_tuner_params: str | None¶

brightness: float | None¶

classification_type: str¶

contrast: float | None¶

dense1: int | None¶

diameter_threshold: float¶

dropout1: float | None¶

dropout2: float | None¶

height: float | None¶

l2_factor: float | None¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

num_classes: int | None¶

reduce_lr: float | None¶

reduce_lr_patience: int | None¶

rotation: float | None¶

unfreeze_from: int | None¶

valid_shapes()[source]¶

width: float | None¶

class focal.config_schema.TrainKFoldCNNConfig(*, checkpoints: str | None = 'n', checkpoint_filepath: Path | None = None, monitor: str | None = 'val_accuracy', method: Literal['max', 'min'] = 'max', early_stopping: str | None = 'n', patience: int | None = 3, csv_path: Path, img_folder: Path, mode: str, image_shape: List[int], set_mask: str | None = None, feature_shape: List[int], brightness: float | None = 0.0, rotation: float | None = 0.0, height: float | None = 0.0, width: float | None = 0.0, contrast: float | None = 0.0, feature_scaler_path: str | None = None, label_scaler_path: str | None = None, model_path: str | None = None, classification_path: str | None = None, encoder_path: str | None = None, save_model_file: str | None = None, save_history_file: str | None = None, tuner_directory: str | None = None, project_name: str | None = None, learning_rate: float | None = 0.001, buffer_size: int | None = 32, batch_size: int | None = 8, test_size: float | None = 0.2, max_epochs: int | None = None, objective: str | None = None, initial_epochs: int | None = None, continue_train: str | None = None, cnn_mode: str, num_classes: int, dropout1: float, dense1: int, dropout2: float, dense2: int, dropout3: float, angle_threshold: float, diameter_threshold: float, train_p: float, test_p: float, tension_threshold: int | None = 190, backbone: str | None = 'efficientnet', unfreeze_from: int | None = None, reduce_lr: float | None = None, reduce_lr_patience: int | None = None, classification_type: Literal['binary', 'multiclass'] = 'binary')[source]¶

Bases: TrainCNNConfig

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class focal.config_schema.TrainKFoldMLPConfig(*, checkpoints: str | None = 'n', checkpoint_filepath: Path | None = None, monitor: str | None = 'val_accuracy', method: Literal['max', 'min'] = 'max', early_stopping: str | None = 'n', patience: int | None = 3, csv_path: Path, img_folder: Path, mode: str, image_shape: List[int], set_mask: str | None = None, feature_shape: List[int] | None = None, brightness: float | None = 0.0, rotation: float | None = 0.0, height: float | None = 0.0, width: float | None = 0.0, contrast: float | None = 0.0, feature_scaler_path: str | None = None, label_scaler_path: str | None = None, model_path: str | None = None, classification_path: str | None = None, encoder_path: str | None = None, save_model_file: str | None = None, save_history_file: str | None = None, tuner_directory: str | None = None, project_name: str | None = None, learning_rate: float | None = 0.001, buffer_size: int | None = 32, batch_size: int | None = 8, test_size: float | None = 0.2, max_epochs: int | None = None, objective: str | None = None, initial_epochs: int | None = None, continue_train: str | None = None, backbone: str, dropout1: float, dense1: int, dropout2: float, dense2: int, dropout3: float, img_path: str | None = None, num_classes: int, angle_threshold: float, diameter_threshold: float, reduce_lr: float | None = None, reduce_lr_patience: int | None = None)[source]¶

Bases: TrainMLPConfig

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class focal.config_schema.TrainMLPConfig(*, checkpoints: str | None = 'n', checkpoint_filepath: Path | None = None, monitor: str | None = 'val_accuracy', method: Literal['max', 'min'] = 'max', early_stopping: str | None = 'n', patience: int | None = 3, csv_path: Path, img_folder: Path, mode: str, image_shape: List[int], set_mask: str | None = None, feature_shape: List[int] | None = None, brightness: float | None = 0.0, rotation: float | None = 0.0, height: float | None = 0.0, width: float | None = 0.0, contrast: float | None = 0.0, feature_scaler_path: str | None = None, label_scaler_path: str | None = None, model_path: str | None = None, classification_path: str | None = None, encoder_path: str | None = None, save_model_file: str | None = None, save_history_file: str | None = None, tuner_directory: str | None = None, project_name: str | None = None, learning_rate: float | None = 0.001, buffer_size: int | None = 32, batch_size: int | None = 8, test_size: float | None = 0.2, max_epochs: int | None = None, objective: str | None = None, initial_epochs: int | None = None, continue_train: str | None = None, backbone: str, dropout1: float, dense1: int, dropout2: float, dense2: int, dropout3: float, img_path: str | None = None, num_classes: int, angle_threshold: float, diameter_threshold: float, reduce_lr: float | None = None, reduce_lr_patience: int | None = None)[source]¶

Bases: ModelConfig

angle_threshold: float¶

backbone: str¶

dense1: int¶

dense2: int¶

diameter_threshold: float¶

dropout1: float¶

dropout2: float¶

dropout3: float¶

img_path: str | None¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

num_classes: int¶

reduce_lr: float | None¶

reduce_lr_patience: int | None¶

valid_shapes()[source]¶

class focal.config_schema.TrainRLConfig(*, csv_path: str, cnn_path: str, agent_path: str, mode: str, img_folder: str, threshold: float, max_tension_change: float | None = 10.0, max_steps: int | None = 15, feature_shape: List[int], buffer_size: int | None = 1000000, batch_size: int | None = 256, tau: float | None = 0.1, learning_rate: float | None = 0.0001, timesteps: int | None = 5000, low_range: float | None = 0.7, high_range: float | None = 1.4, max_delta: float | None = 5.0)[source]¶

Bases: BaseModel

agent_path: str¶

batch_size: int | None¶

buffer_size: int | None¶

cnn_path: str¶

csv_path: str¶

feature_shape: List[int]¶

high_range: float | None¶

img_folder: str¶

learning_rate: float | None¶

low_range: float | None¶

max_delta: float | None¶

max_steps: int | None¶

max_tension_change: float | None¶

mode: str¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

tau: float | None¶

threshold: float¶

timesteps: int | None¶

Bases: ModelConfig

angle_threshold: float¶

diameter_threshold: float¶

error_type: str¶

gamma: float | None¶

max_depth: int | None¶

model_config: ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

n_estimators: int | None¶

random_state: int | None¶

reg_lambda: float | None¶

subsample: float | None¶

xgb_path: str | None¶

focal.config_schema.load_config(filepath: str) → BaseConfig[source]¶: Loads a configuration object from a JSON file based on the ‘mode’ field.