Black Fox documentation¶

The goal of Black Fox is to dramatically simplify the process of building deployment-ready predictive models.

Black Fox is a cloud-based “one click data-in model-out” robust artificial intelligence software solution for automated generation of the most adequate predictive model for any given dataset. It optimizes all parameters and hyperparameters of neural networks by genetic algorithm. Optimization targets include number of hidden layers, number of neurons per layer, activation functions, dropout, learning algorithms, etc. During an evolutionary process, Black Fox automatically performs adjustments of NN architecture according to the present dataset.

User’s Guide¶

Installation¶

To install Black Fox use pip or pipenv:

$ pip install -U blackfox

Example usage¶

Black Fox NN optimization without any additional parameters save the dataset requires only one function call:

from blackfox import BlackFox
import csv

input_columns = 9
input_set = []
output_set = []

#Example reading and parsing .csv file
#with input and output set filled respectively
with open('..path/to/your/dataset.csv') as csv_file:
csv_reader = csv.reader(csv_file, delimiter=',')
line_count = 0
for row in csv_reader:
    if line_count == 0:
        print('Column names are ' + (", ".join(row)))
    else:
        data = list(map(float, row))
        input_set.append(data[:input_columns])
        output_set.append(data[input_columns:])

    line_count += 1

#Create an instance of the Black Fox class by supplying api URL
bf = BlackFox('bf.endpoint.api.address')

#Call optimization function which returns three entities
#NN bytearray/model, NN info and NN JSON metadata
(nn_io, nn_info, nn_md) = bf.optimize_keras_sync(input_set, output_set)

Optimization parameters, as well as parameters for the NN can be configured if needed, since the optimization method accepts several additional configuration parameters. For example:

from blackfox import BlackFox
from blackfox import KerasOptimizationConfig, OptimizationEngineConfig

#Input and output set read/parse
...
...

#Create instances of the optimization configuration classes
ec = OptimizationEngineConfig(proc_timeout_seconds = 20000,
                              population_size = 50,
                              max_num_of_generations = 20,
                              mutation_probability = 0.2,
                              optimization_algorithm = "VidnerovaNeruda")

c = KerasOptimizationConfig(engine_config = ec,
                            max_epoch = 3000,
                            validation_split = 0.2,
                            problem_type = "BinaryClassification")

(nn_io, nn_info, nn_md) = bf.optimize_keras_sync(
  input_set,
  output_set,
  config = c)

Once invoked, optimization process proceeds until the most optimal NN is created and ultimately returned to the user (nn_io in the example above). After the process, the optimized NN model can be used for prediction, either directly or by saving the model as an h5 file for susequent use. For example:

import pandas as pd
import h5py
from blackfox_extras import prepare_input_data, prepare_output_data
from keras.models import load_model

#Optimization performed as in the first example
#(got nn_io, nn_info, nn_md)
...
...

#Load and prepare test data
#(using functions from the blackfox_extras package)
test_set = pd.read_csv('...path/to/test/dataset.csv')
test_set_prepared = prepare_input_data(test_set, nn_md)

#Save model for subsequent use
nn_h5 = '..path/to/network.h5'
if ann_io is not None:
with open(nn_h5, 'wb') as out:
    out.write(ann_io.read())

#Use model directly (or loaded from an .h5)
f = h5py.File(nn_io)
model = load_model(f) #Directly
# model = load_model(nn_h5) #from .h5 file

#Perform prediction and obtain real values
prediction = model.predict(test_set_prepared)
prediction_real_values = prepare_output_data(prediction, nn_md)

Please note that NN metadata can also be loaded from an h5 file using get_metadata Black Fox method (nn_md = bf.get_metadata(‘..path/to/network.h5’)).

API Guide¶

Module¶

blackfox

Module blackfox exposes BlackFox, a class with all the optimization methods and controls.

Classes¶

BlackFox¶

class blackfox.BlackFox(host='http://localhost:50476/')¶

BlackFox provides methods for neural network parameter optimization.

Parameters: host (str) – Web API url

get_metadata(network_path)¶

Network metadata retrieval

Gets the neural network metadata from a network file.

Parameters: network_path (str) – Load path for the neural network file from wich the metadata would be read
Returns: network metadata
Return type: dict

get_optimization_status_keras(id, integrate_scaler=False, network_type='h5', network_path=None)¶

Gets current async optimization status.

Query of the current optimization status when it is performed asynchronously.

Parameters

id (str) – Optimization process id (i.e. from optimize_keras method)
integrate_scaler (bool) – If True, Black Fox will integrate a scaler function used for data scaling/normalization in the model
network_type (str) – Optimized model file format (.h5 | .onnx | .pb)
network_path (str) – Save path for the optimized NN; will be used after the function finishes to automatically save optimized network

Returns

An object depicting the current optimization status

Return type

KerasOptimizationStatus

optimize_keras(config={'activation_functions': ['SoftMax', 'Elu', 'Selu', 'SoftPlus', 'SoftSign', 'ReLu', 'TanH', 'Sigmoid', 'HardSigmoid', 'Linear'], 'batch_size': 32, 'cross_validation': False, 'dataset_id': None, 'dropout': {'max': 25, 'min': 0}, 'engine_config': {'crossover_distribution_index': 20, 'crossover_probability': 0.9, 'hyper_volume': {'number_of_latest_generations': 10, 'percentage_of_tolerance': 5}, 'max_num_of_generations': 20, 'mutation_distribution_index': 20, 'mutation_probability': 0.2, 'optimization_algorithm': 'VidnerovaNeruda', 'population_size': 50, 'proc_timeout_seconds': 10800}, 'hidden_layer_count_range': {'max': 15, 'min': 1}, 'inputs': None, 'max_epoch': 3000, 'neurons_per_layer': {'max': 10, 'min': 1}, 'output_ranges': None, 'problem_type': 'Regression', 'random_seed': 300, 'training_algorithms': ['SGD', 'RMSprop', 'Adagrad', 'Adadelta', 'Adam', 'Adamax', 'Nadam'], 'validation_split': 0.2}, data_set_path=None)¶

Async optimization call.

Performs the Black Fox optimization asynchronously (non-blocking), so the user must querry the server periodically in order to get the progress info.

Parameters

config (KerasOptimizationConfig) – Configuration for Black Fox optimization
data_set_path (str) – Path to a .csv file holding the training dataset

Returns

Optimization process id

Return type

str

optimize_keras_sync(input_set=None, output_set=None, integrate_scaler=False, network_type='h5', data_set_path=None, config={'activation_functions': ['SoftMax', 'Elu', 'Selu', 'SoftPlus', 'SoftSign', 'ReLu', 'TanH', 'Sigmoid', 'HardSigmoid', 'Linear'], 'batch_size': 32, 'cross_validation': False, 'dataset_id': None, 'dropout': {'max': 25, 'min': 0}, 'engine_config': {'crossover_distribution_index': 20, 'crossover_probability': 0.9, 'hyper_volume': {'number_of_latest_generations': 10, 'percentage_of_tolerance': 5}, 'max_num_of_generations': 20, 'mutation_distribution_index': 20, 'mutation_probability': 0.2, 'optimization_algorithm': 'VidnerovaNeruda', 'population_size': 50, 'proc_timeout_seconds': 10800}, 'hidden_layer_count_range': {'max': 15, 'min': 1}, 'inputs': None, 'max_epoch': 3000, 'neurons_per_layer': {'max': 10, 'min': 1}, 'output_ranges': None, 'problem_type': 'Regression', 'random_seed': 300, 'training_algorithms': ['SGD', 'RMSprop', 'Adagrad', 'Adadelta', 'Adam', 'Adamax', 'Nadam'], 'validation_split': 0.2}, network_path=None, status_interval=5, log_writer=<blackfox.log_writer.LogWriter object>)¶

Starts the optimization.

Performs the Black Fox optimization and finds the best parameters and hyperparameters of a target model neural network.

Parameters

input_set (str) – Input data (x train data)
output_set (str) – Output data (y train data or target data)
integrate_scaler (bool) – If True, Black Fox will integrate a scaler function used for data scaling/normalization in the model
network_type (str) – Optimized model file format (.h5 | .onnx | .pb)
data_set_path (str) – Optional .csv file used instead of input_set/output_set as a source for training data
config (KerasSeriesOptimizationConfig) – Configuration for Black Fox optimization
network_path (str) – Save path for the optimized NN; will be used after the function finishes to automatically save optimized network
status_interval (int) – Time interval for repeated server calls for optimization info and logging
log_writer (str) – Optional log writer used for logging the optimization process

Returns

byte array from network model, optimized network info, network metadata

Return type

(BytesIO, KerasOptimizedNetwork, dict)

optimize_recurrent_keras_sync(input_set=None, output_set=None, integrate_scaler=False, network_type='h5', data_set_path=None, config=None, network_path=None, status_interval=5, log_writer=<blackfox.log_writer.LogWriter object>)¶

Starts the optimization.

Performs the Black Fox optimization using recurrent neural networks and finds the best parameters and hyperparameters of a target model.

Parameters

input_set (str) – Input data (x train data)
output_set (str) – Output data (y train data or target data)
integrate_scaler (bool) – If True, Black Fox will integrate a scaler function used for data scaling/normalization in the model
network_type (str) – Optimized model file format (.h5 | .onnx | .pb)
data_set_path (str) – Optional .csv file used instead of input_set/output_set as a source for training data
config (KerasRecurrentOptimizationConfig) – Configuration for Black Fox optimization
network_path (str) – Save path for the optimized NN; will be used after the function finishes to automatically save optimized network
status_interval (int) – Time interval for repeated server calls for optimization info and logging
log_writer (str) – Optional log writer used for logging the optimization process

Returns

byte array from network model, optimized network info, network metadata

Return type

(BytesIO, KerasOptimizedNetwork, dict)

optimize_series_keras_sync(input_set=None, output_set=None, integrate_scaler=False, network_type='h5', data_set_path=None, config={'activation_functions': ['SoftMax', 'Elu', 'Selu', 'SoftPlus', 'SoftSign', 'ReLu', 'TanH', 'Sigmoid', 'HardSigmoid', 'Linear'], 'batch_size': 32, 'cross_validation': False, 'dataset_id': None, 'dropout': {'max': 25, 'min': 0}, 'engine_config': {'crossover_distribution_index': 20, 'crossover_probability': 0.9, 'hyper_volume': {'number_of_latest_generations': 10, 'percentage_of_tolerance': 5}, 'max_num_of_generations': 20, 'mutation_distribution_index': 20, 'mutation_probability': 0.2, 'optimization_algorithm': 'VidnerovaNeruda', 'population_size': 50, 'proc_timeout_seconds': 10800}, 'hidden_layer_count_range': {'max': 15, 'min': 1}, 'input_window_range_configs': None, 'inputs': None, 'max_epoch': 3000, 'neurons_per_layer': {'max': 10, 'min': 1}, 'output_ranges': None, 'output_sample_step': 1, 'output_window_configs': None, 'problem_type': 'Regression', 'random_seed': 300, 'training_algorithms': ['SGD', 'RMSprop', 'Adagrad', 'Adadelta', 'Adam', 'Adamax', 'Nadam'], 'validation_split': 0.2}, network_path=None, status_interval=5, log_writer=<blackfox.log_writer.LogWriter object>)¶

Starts the optimization.

Performs the Black Fox optimization for timeseries data and finds the best parameters and hyperparameters of a target model neural network.

Parameters

input_set (str) – Input data (x train data)
output_set (str) – Output data (y train data or target data)
integrate_scaler (bool) – If True, Black Fox will integrate a scaler function used for data scaling/normalization in the model
network_type (str) – Optimized model file format (.h5 | .onnx | .pb)
data_set_path (str) – Optional .csv file used instead of input_set/output_set as a source for training data
config (KerasSeriesOptimizationConfig) – Configuration for Black Fox optimization
network_path (str) – Save path for the optimized NN; will be used after the function finishes to automatically save optimized network
status_interval (int) – Time interval for repeated server calls for optimization info and logging
log_writer (str) – Optional log writer used for logging the optimization process

Returns

byte array from network model, optimized network info, network metadata

Return type

(BytesIO, KerasOptimizedNetwork, dict)

stop_optimization_keras(id, network_path=None)¶

Stops current async optimization.

Sends a request for stopping the ongoing optimization, and returns the current best solution.

Parameters

id (str) – Optimization process id (i.e. from optimize_keras method)
network_path (str) – Save path for the optimized NN; will be used after the function finishes to automatically save optimized network

Returns

An object depicting the current optimization status

Return type

KerasOptimizationStatus

LogWriter¶

class blackfox.LogWriter(log_file=<colorama.ansitowin32.StreamWrapper object>)¶

LogWriter provides logging capabilities for an ongoing Black Fox optimization.

Parameters: log_file (str) – Optional file or sys.stdout used for logging

Black Fox documentation¶

User’s Guide¶

Installation¶

Example usage¶

API Guide¶

Module¶

Classes¶

BlackFox¶

LogWriter¶

Indices and tables¶

BlackFox

Table of Contents

Related Topics