CreateNeuralNetwork_SingleOutcome

Introduction

When a relationship between features and an outcome is genuinely non-linear and full of interactions that trip up simpler models, a neural network can capture patterns they can't — at the cost of needing more careful setup and diagnosis. CreateNeuralNetwork_SingleOutcome builds and trains a fully connected Keras/TensorFlow network for tabular data — binary, multi-class, or regression — automating the hidden-layer architecture, feature normalization, and L2 regularization, then plotting the training loss curve, test-set performance, and a training-vs-test comparison so you can actually see whether the network converged and generalized.

Teaching Note

Neural networks are essential for:

Detecting complex, non-linear patterns in high-dimensional financial or security data
Predicting credit risk or fraud where interactions between features are non-linear
Classifying multi-category intelligence reports or customer segments
Forecasting continuous variables like market volatility or housing prices
Building multi-class classifiers for sentiment analysis or product categorization
Modeling operational throughput in complex manufacturing or supply chain environments
Identifying subtle behavioral trends in large-scale consumer or medical datasets

Parameters

Parameter	Default	Description
`dataframe`required	—	The input pandas DataFrame containing the feature set and target variable.
`outcome_variable`required	—	The name of the target column to be predicted.
`list_of_predictor_variables`required	—	A list of column names to be used as input features (X).
`number_of_hidden_layers`required	—	The number of dense layers to insert between the input and output. Higher values increase the capacity to model complex relationships.
`is_outcome_categorical`	`True`	If True, treats the task as classification. If False, treats it as regression. Defaults to True.
`test_size`	`0.2`	The proportion of data reserved for model evaluation. Defaults to 0.2.
`scale_predictor_variables`	`True`	If True, utilizes a Keras Normalization layer to standardize feature inputs. Recommended for neural network stability. Defaults to True.
`initial_learning_rate`	`0.01`	The step size for the Adam optimizer. Small values are more stable but slower to converge. Defaults to 0.01.
`number_of_steps_gradient_descent`	`100`	The number of training epochs. Defaults to 100.
`lambda_for_regularization`	`0.001`	The L2 penalty weight applied to all dense layers to mitigate overfitting. Defaults to 0.001.
`random_seed`	`412`	The integer seed used for TensorFlow's random state and data partitioning. Defaults to 412.
`print_peak_to_peak_range_of_each_predictor`	`False`	If True, prints the scale of the predictor variables to help assess data range. Defaults to False.
`print_model_training_performance`	`False`	If True, prints training and test MSE (regression) or training and test accuracy (classification) after training. Defaults to False.
`plot_loss`	`True`	Whether to render the training loss curve as a function of epochs. Defaults to True.
`plot_model_test_performance`	`True`	Whether to generate a diagnostic plot (confusion matrix, probability scatter, or regression plot) for the test dataset. Defaults to True.
`plot_training_and_test_performance`	`True`	Whether to render a bar chart comparing the training and test metric (MSE for regression, error rate for classification). Defaults to True.
`training_bar_color`	`'#3a86ff'`	Bar color for the training metric bar. Defaults to '#3a86ff'.
`test_bar_color`	`'#b0170c'`	Bar color for the test metric bar. Defaults to '#b0170c'.
`figure_size_for_performance_comparison_plot`	`(7, 5)`	Dimensions (width, height) for the comparison chart. Defaults to (7, 5).
`title_for_performance_comparison_plot`	`None`	Title text for the comparison chart. Defaults to a sensible built-in title when None.
`subtitle_for_performance_comparison_plot`	`None`	Subtitle text for the comparison chart. Defaults to a sensible built-in subtitle when None.
`caption_for_performance_comparison_plot`	`None`	Optional caption text for the comparison chart. Defaults to None.
`title_y_indent_for_performance_comparison_plot`	`1.1`	Vertical position of the title on the comparison chart. Defaults to 1.1.
`subtitle_y_indent_for_performance_comparison_plot`	`1.05`	Vertical position of the subtitle on the comparison chart. Defaults to 1.05.
`caption_y_indent_for_performance_comparison_plot`	`-0.15`	Vertical position of the caption on the comparison chart. Defaults to -0.15.
`x_indent_for_performance_comparison_plot`	`-0.115`	Horizontal starting position for text on the comparison chart. Defaults to -0.115.

Returns

If scale_predictor_variables=False, returns the fitted tf.keras.Model. If True, returns a dictionary containing the 'model' and the 'scaler' (Normalization layer) so new observations can be normalized consistently before prediction.

Example

python

from analysistoolbox.predictive_analytics import CreateNeuralNetwork_SingleOutcome

# 3-layer classifier to predict employee attrition
model = CreateNeuralNetwork_SingleOutcome(
    df,
    outcome_variable='attrition',
    list_of_predictor_variables=['salary', 'tenure', 'hours'],
    number_of_hidden_layers=3,
)