API¶

Model¶

class Model¶

Class representing a PMML model.

Public Functions

Model(const std::string &model_filepath, const bool zipped)¶

Constructs a cpmml::Model instance representing the PMML model stored at model_filepath.

It triggers the model load process: the XML elements are visited and the corresponding internal cPMML objects are built.

It is responsibility of the user to ensure the input file is compliant with the PMML XML schema. Creating cpmml::Model instances from incorrect PMML files may result in undefined behavior.

cpmml::ParsingException will be thrown in case model_path does not exists.

File extension is not taken into account.

Parameters

model_filepath: path to the XML file containing the PMML model.
zipped: *(optional)* it allows to specify whether the input file is compressed in zip format. The default value is false.

Exceptions

cpmml::ParsingException:
cpmml::InvalidValueException:
cpmml::MissingValueException:

Examples

cpmml::Model model("IrisTree.xml");

cpmml::Model model("AuditRandomForest.zip", true);

bool validate(const std::unordered_map<std::string, std::string> &sample) const¶

Validates user input in sample against the constraints defined in the PMML DataDictionary.

The PMML standard allows to define constraints on every input field of the model in order to determine the validity of the values assumed by the variables. For continuous fields, it is verified they fall in a certain range. For categorical fields, it is checked they assume a value among a list of possible ones. Being PMML strongly typed, also the type of the input variables is checked.

In addition, if PMML TransformationDictionary is present, it is also checked the possibility to compute all transformations needed for the model.

Return

true in case of valid input sample. false otherwise.

Parameters

sample: hash map where the keys are strings representing feature names and the values are strings representing features values.

Examples

cpmml::Model model("IrisTree.xml");
std::unordered_map<std::string, std::string> sample = {
  {"sepal_length", "6.6"},
  {"sepal_width", "2.9"},
  {"petal_length", "4.6"},
  {"petal_width", "1.3"}
};

if(!model.validate(sample)) std::cout << "Invalid input for model" <<
std::endl;

Prediction score(const std::unordered_map<std::string, std::string> &sample) const¶

Scores the model against the user input in sample.

It triggers the model scoring process: the input values are preprocessed, validated, used as input for the PMML model and the resulting prediction is postprocessed.

Return

An instance of cpmml::Prediction

Parameters

sample: hash map where the keys are strings representing feature names and the values are strings representing features values.

Exceptions

cpmml::InvalidValueException:
cpmml::MissingValueException:
cpmml::MathException:

Examples

cpmml::Model model("IrisTree.xml");
std::unordered_map<std::string, std::string> sample = {
  {"sepal_length", "6.6"},
  {"sepal_width", "2.9"},
  {"petal_length", "4.6"},
  {"petal_width", "1.3"}
};

cpmml::Prediction prediction = model.score(sample);

std::string predict(const std::unordered_map<std::string, std::string> &sample) const¶

Scores the model against the user input in sample.

It triggers a minimal version of the model scoring process: the input values are preprocessed, validated, used as input for the PMML model and the raw resulting prediction is returned.

It has been included to easily retrieve the raw prediction value in case of no interest for other model outputs (eg. probabilities, etc.).

In addition, returning the raw prediction allows further internal optimization. Thus, cpmml::Model::predict achieves a significant speedup compared to cpmml::Model::score.

Return

A string containing the raw prediction.

Parameters

sample: hash map where the keys are strings representing feature names and the values are strings representing features values.

Exceptions

cpmml::InvalidValueException:
cpmml::MissingValueException:
cpmml::MathException:

Examples

cpmml::Model model("IrisTree.xml");
std::unordered_map<std::string, std::string> sample = {
  {"sepal_length", "6.6"},
  {"sepal_width", "2.9"},
  {"petal_length", "4.6"},
  {"petal_width", "1.3"}
};

std::cout << model.predict(sample); // "Iris-versicolor"

Prediction¶

class Prediction¶

Class representing a prediction.

This class has no corresponding PMML element since it contains the output of a PMML model evaluation.

It stores the predicted value, already transformed through PMML Target, along with the additional outputs provided by PMML Output. In addition, for classification models allowing the calculation of target probabilities, it provides the probability for each target class.

Public Functions

std::string as_string() const¶: It returns the predicted value as a string.

double as_double() const¶: It returns the predicted value as a double. In case the predicted value cannot be converted to double, it will return std::numeric_limits<double>::min().

std::unordered_map<std::string, double> distribution() const¶

It returns an hash map of string -> double pairs, where the keys are the target categories and the values are the associated probabilities computed by the model.

Examples

cpmml::Model model(model_filepath);
std::unordered_map<std::string, std::string> sample = {
 {"sepal_length", "6.6"},
 {"sepal_width", "2.9"},
 {"petal_length", "4.6"},
 {"petal_width", "1.3"}
};

cpmml::Prediction prediction = model.score(sample);
for (const auto &probability : prediction.distribution())
   std::cout << probability.first << ": " << probability.second <<
std::endl;

// "Iris-virginica: 0.0810811"
// "Iris-setosa: 0"
// "Iris-versicolor: 0.918919"

std::unordered_map<std::string, double> num_outputs() const¶

It returns an hash map of string -> double pairs, where the keys are the output field names and the values their corresponding value. Among all the output fields available for a model, it contains just numeric output fields.

Examples

cpmml::Model model(model_filepath);
std::unordered_map<std::string, std::string> sample = {
 {"sepal_length", "6.6"},
 {"sepal_width", "2.9"},
 {"petal_length", "4.6"},
 {"petal_width", "1.3"}
};

cpmml::Prediction prediction = model.score(sample);
for (const auto &output : prediction.num_outputs())
   std::cout << output.first << ": " << output.second << std::endl;

// "Probability_Iris-setosa: 0"
// "Probability_Iris-virginica: 0.0810811"
// "Probability_Iris-versicolor: 0.918919"

std::unordered_map<std::string, std::string> str_outputs() const¶: It returns an hash map of string -> string pairs, where the keys are the output field names and the values their corresponding value. Among all the output fields available for a model, it contains just categorical output fields.

Errors¶

class Exception : public exception¶

Base class for all exceptions generated by cPMML.

Subclassed by cpmml::InvalidValueException, cpmml::MathException, cpmml::MissingValueException, cpmml::ParsingException

Public Functions

Exception(const std::string &message)¶

Constructs a new Exception object.

Parameters

message: explanatory string providing more details about the error.

virtual const char *what() const¶

Return: an explanatory string providing more details about the error.

class MissingValueException : public cpmml::Exception ¶

Reports errors related to the absence of values in user input.

For instance a missing feature in a sample to be scored. Notice that, depending on the underlying PMML, some models may tolerate missing values. It is generated during model scoring.

Public Functions

MissingValueException(const std::string &message)¶

Constructs a new MissingValueException object.

Parameters

message: explanatory string providing more details about the error.

class InvalidValueException : public cpmml::Exception ¶

Reports errors related to the presence of wrong values in user input.

For instance a categorical feature assuming a value not in the domain or continuous features assuming a value outside certain boundaries. It is generated during input validation or during model scoring.

See: Model::validate

Public Functions

InvalidValueException(const std::string &message)¶

Constructs a new InvalidValueException object.

Parameters

message: explanatory string providing more details about the error.

class MathException : public cpmml::Exception ¶

Reports errors encountered in the computation of a mathematical function. For example when a normalization methods receives wrong values.

Public Functions

MathException(const std::string &message)¶

Constructs a new MathException object.

Parameters

message: explanatory string providing more details about the error.

class ParsingException : public cpmml::Exception ¶

Reports errors related to the parsing of the user input or of the PMML file representing the model.

For instance this error could be triggered in case a certain PMML element or attribute, needed for the scoring, is missing.

See: Model

Public Functions

ParsingException(const std::string &message)¶

Constructs a new ParsingException object.

Parameters

message: explanatory string providing more details about the error.