Class XGBoostExternalModel<T extends Output<T>>
- All Implemented Interfaces:
com.oracle.labs.mlrg.olcut.provenance.Provenancable<ModelProvenance>,Serializable,ProtoSerializable<org.tribuo.protos.core.ModelProto>
Model which wraps around a XGBoost.Booster which was trained by a system other than Tribuo.
XGBoost is a fast implementation of gradient boosted decision trees.
Throws IllegalStateException if the XGBoost C++ library fails to load or throws an exception.
See:
Chen T, Guestrin C. "XGBoost: A Scalable Tree Boosting System" Proceedings of the 22nd ACM SIGKDD International Conference on Knowledge Discovery and Data Mining, 2016.
and for the original algorithm:
Friedman JH. "Greedy Function Approximation: a Gradient Boosting Machine" Annals of statistics, 2001.
N.B.: XGBoost4J wraps the native C implementation of xgboost that links to various C libraries, including libgomp and glibc (on Linux). If you're running on Alpine, which does not natively use glibc, you'll need to install glibc into the container. On the macOS binary on Maven Central is compiled without OpenMP support, meaning that XGBoost is single threaded on macOS. You can recompile the macOS binary with OpenMP support after installing libomp from homebrew if necessary.
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final intProtobuf serialization version.protected ml.dmlc.xgboost4j.java.BoosterTransient as we rely upon the native serialisation mechanism to bytes rather than Java serializing the Booster.Fields inherited from class org.tribuo.interop.ExternalModel
DEFAULT_BATCH_SIZE, featureBackwardMapping, featureForwardMappingFields inherited from class org.tribuo.Model
ALL_OUTPUTS, BIAS_FEATURE, featureIDMap, generatesProbabilities, name, outputIDInfo, provenance, provenanceOutputFields inherited from interface org.tribuo.protos.ProtoSerializable
DESERIALIZATION_METHOD_NAME, PROVENANCE_SERIALIZER -
Method Summary
Modifier and TypeMethodDescriptionprotected ml.dmlc.xgboost4j.java.DMatrixconvertFeatures(SparseVector input) protected ml.dmlc.xgboost4j.java.DMatrixconvertFeaturesList(List<SparseVector> input) protected List<Prediction<T>> convertOutput(float[][] output, int[] numValidFeatures, List<Example<T>> examples) protected Prediction<T> convertOutput(float[][] output, int numValidFeatures, Example<T> example) protected XGBoostExternalModel<T> copy(String newName, ModelProvenance newProvenance) static <T extends Output<T>>
XGBoostExternalModel<T> createXGBoostModel(OutputFactory<T> factory, Map<String, Integer> featureMapping, Map<T, Integer> outputMapping, XGBoostOutputConverter<T> outputFunc, String path) Creates anXGBoostExternalModelfrom the supplied model on disk.static <T extends Output<T>>
XGBoostExternalModel<T> createXGBoostModel(OutputFactory<T> factory, Map<String, Integer> featureMapping, Map<T, Integer> outputMapping, XGBoostOutputConverter<T> outputFunc, Path path) Creates anXGBoostExternalModelfrom the supplied model on disk.static <T extends Output<T>>
XGBoostExternalModel<T> createXGBoostModel(OutputFactory<T> factory, Map<String, Integer> featureMapping, Map<T, Integer> outputMapping, XGBoostOutputConverter<T> outputFunc, ml.dmlc.xgboost4j.java.Booster model, URL provenanceLocation) Deprecated.As the URL argument must always be valid.static <T extends Output<T>>
XGBoostExternalModel<T> createXGBoostModel(OutputFactory<T> factory, Map<String, Integer> featureMapping, Map<T, Integer> outputMapping, XGBoostOutputConverter<T> outputFunc, ml.dmlc.xgboost4j.java.Booster model, Map<String, com.oracle.labs.mlrg.olcut.provenance.Provenance> instanceProvenance) Creates anXGBoostExternalModelfrom the supplied in-memory XGBoostBooster.static XGBoostExternalModel<?> deserializeFromProto(int version, String className, com.google.protobuf.Any message) Deserialization factory.protected float[][]externalPrediction(ml.dmlc.xgboost4j.java.DMatrix input) Creates objects to report feature importance metrics for XGBoost.getTopFeatures(int n) org.tribuo.protos.core.ModelProtoMethods inherited from class org.tribuo.interop.ExternalModel
createFeatureMap, createOutputInfo, getBatchSize, getExcuse, innerPredict, predict, setBatchSize, validateFeatureMappingMethods inherited from class org.tribuo.Model
castModel, copy, createDataCarrier, deserialize, deserializeFromFile, deserializeFromStream, generatesProbabilities, getExcuses, getFeatureIDMap, getName, getOutputIDInfo, getProvenance, predict, predict, serializeToFile, serializeToStream, setName, toString, validate
-
Field Details
-
CURRENT_VERSION
-
model
Transient as we rely upon the native serialisation mechanism to bytes rather than Java serializing the Booster.
-
-
Method Details
-
deserializeFromProto
public static XGBoostExternalModel<?> deserializeFromProto(int version, String className, com.google.protobuf.Any message) throws com.google.protobuf.InvalidProtocolBufferException, ml.dmlc.xgboost4j.java.XGBoostError, IOException Deserialization factory.- Parameters:
version- The serialized object version.className- The class name.message- The serialized data.- Returns:
- The deserialized object.
- Throws:
com.google.protobuf.InvalidProtocolBufferException- If the protobuf could not be parsed from themessage.ml.dmlc.xgboost4j.java.XGBoostError- If the XGBoost byte array failed to parse.IOException- If the XGBoost byte array failed to parse.
-
convertFeatures
- Specified by:
convertFeaturesin classExternalModel<T extends Output<T>, ml.dmlc.xgboost4j.java.DMatrix, float[][]>
-
convertFeaturesList
- Specified by:
convertFeaturesListin classExternalModel<T extends Output<T>, ml.dmlc.xgboost4j.java.DMatrix, float[][]>
-
externalPrediction
- Specified by:
externalPredictionin classExternalModel<T extends Output<T>, ml.dmlc.xgboost4j.java.DMatrix, float[][]>
-
convertOutput
- Specified by:
convertOutputin classExternalModel<T extends Output<T>, ml.dmlc.xgboost4j.java.DMatrix, float[][]>
-
convertOutput
protected List<Prediction<T>> convertOutput(float[][] output, int[] numValidFeatures, List<Example<T>> examples) - Specified by:
convertOutputin classExternalModel<T extends Output<T>, ml.dmlc.xgboost4j.java.DMatrix, float[][]>
-
getFeatureImportance
Creates objects to report feature importance metrics for XGBoost. See the documentation ofXGBoostFeatureImportancefor more information on what those metrics mean. Typically this list will contain a single instance for the entire model. For multidimensional regression the list will have one entry per dimension, in dimension order.- Returns:
- The feature importance object(s).
-
getTopFeatures
-
serialize
-
copy
-
createXGBoostModel
public static <T extends Output<T>> XGBoostExternalModel<T> createXGBoostModel(OutputFactory<T> factory, Map<String, Integer> featureMapping, Map<T, Integer> outputMapping, XGBoostOutputConverter<T> outputFunc, String path) Creates anXGBoostExternalModelfrom the supplied model on disk.- Type Parameters:
T- The type of the output.- Parameters:
factory- The output factory to use.featureMapping- The feature mapping between Tribuo names and XGBoost integer ids.outputMapping- The output mapping between Tribuo outputs and XGBoost integer ids.outputFunc- The XGBoostOutputConverter function for the output type.path- The path to the model on disk.- Returns:
- An XGBoostExternalModel ready to score new inputs.
-
createXGBoostModel
public static <T extends Output<T>> XGBoostExternalModel<T> createXGBoostModel(OutputFactory<T> factory, Map<String, Integer> featureMapping, Map<T, Integer> outputMapping, XGBoostOutputConverter<T> outputFunc, Path path) Creates anXGBoostExternalModelfrom the supplied model on disk.- Type Parameters:
T- The type of the output.- Parameters:
factory- The output factory to use.featureMapping- The feature mapping between Tribuo names and XGBoost integer ids.outputMapping- The output mapping between Tribuo outputs and XGBoost integer ids.outputFunc- The XGBoostOutputConverter function for the output type.path- The path to the model on disk.- Returns:
- An XGBoostExternalModel ready to score new inputs.
-
createXGBoostModel
@Deprecated public static <T extends Output<T>> XGBoostExternalModel<T> createXGBoostModel(OutputFactory<T> factory, Map<String, Integer> featureMapping, Map<T, Integer> outputMapping, XGBoostOutputConverter<T> outputFunc, ml.dmlc.xgboost4j.java.Booster model, URL provenanceLocation) Deprecated.As the URL argument must always be valid. To wrap an in-memory booster usecreateXGBoostModel(OutputFactory, Map, Map, XGBoostOutputConverter, Booster, Map).Creates anXGBoostExternalModelfrom the supplied model.Note: the provenance system requires that the URL point to a valid local file and will throw an exception if it is not. However it doesn't check that the file is where the Booster was created from.
- Type Parameters:
T- The type of the output.- Parameters:
factory- The output factory to use.featureMapping- The feature mapping between Tribuo names and XGBoost integer ids.outputMapping- The output mapping between Tribuo outputs and XGBoost integer ids.outputFunc- The XGBoostOutputConverter function for the output type.model- The XGBoost model to wrap.provenanceLocation- The location where the model was loaded from.- Returns:
- An XGBoostExternalModel ready to score new inputs.
-
createXGBoostModel
public static <T extends Output<T>> XGBoostExternalModel<T> createXGBoostModel(OutputFactory<T> factory, Map<String, Integer> featureMapping, Map<T, Integer> outputMapping, XGBoostOutputConverter<T> outputFunc, ml.dmlc.xgboost4j.java.Booster model, Map<String, com.oracle.labs.mlrg.olcut.provenance.Provenance> instanceProvenance) Creates anXGBoostExternalModelfrom the supplied in-memory XGBoostBooster.- Type Parameters:
T- The type of the output.- Parameters:
factory- The output factory to use.featureMapping- The feature mapping between Tribuo names and XGBoost integer ids.outputMapping- The output mapping between Tribuo outputs and XGBoost integer ids.outputFunc- The XGBoostOutputConverter function for the output type.model- The XGBoost model to wrap.instanceProvenance- Provenance for this model.- Returns:
- An XGBoostExternalModel ready to score new inputs.
-