001/* 002 * Copyright (c) 2015, 2022, Oracle and/or its affiliates. All rights reserved. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package org.tribuo.common.xgboost; 018 019import org.tribuo.Example; 020import org.tribuo.ImmutableOutputInfo; 021import org.tribuo.Output; 022import org.tribuo.Prediction; 023 024import java.io.Serializable; 025import java.util.List; 026import org.tribuo.common.xgboost.protos.XGBoostOutputConverterProto; 027import org.tribuo.protos.ProtoSerializable; 028 029/** 030 * Converts the output of XGBoost into the appropriate prediction type. 031 */ 032public interface XGBoostOutputConverter<T extends Output<T>> extends 033 ProtoSerializable<XGBoostOutputConverterProto>, Serializable { 034 035 /** 036 * Does this converter produce probabilities? 037 * @return True if it produces probabilities. 038 */ 039 public boolean generatesProbabilities(); 040 041 /** 042 * Converts a list of float arrays from XGBoost Boosters into a Tribuo {@link Prediction}. 043 * @param info The output info. 044 * @param probabilities The XGBoost output. 045 * @param numValidFeatures The number of valid features used in the prediction. 046 * @param example The example this prediction was generated from. 047 * @return The prediction object. 048 */ 049 public Prediction<T> convertOutput(ImmutableOutputInfo<T> info, List<float[]> probabilities, int numValidFeatures, Example<T> example); 050 051 /** 052 * Converts a list of float arrays from XGBoost Boosters into a Tribuo {@link Prediction}. 053 * @param info The output info. 054 * @param probabilities The XGBoost output, list dimension is across models, first array dimension is across examples, second array dimension is across outputs. 055 * @param numValidFeatures The number of valid features used in each prediction. 056 * @param examples The examples these predictions were generated from. 057 * @return The prediction object. 058 */ 059 public List<Prediction<T>> convertBatchOutput(ImmutableOutputInfo<T> info, List<float[][]> probabilities, int[] numValidFeatures, Example<T>[] examples); 060 061 /** 062 * Gets the type witness for the output this converter uses. 063 * <p> 064 * The default implementation throws {@link UnsupportedOperationException} for compatibility 065 * with subclasses which don't support protobuf serialization. 066 * @return The class of the output. 067 */ 068 default public Class<T> getTypeWitness() { 069 throw new UnsupportedOperationException("This class has not been updated to support protobuf serialization."); 070 } 071 072}