Package ai.libs.jaicore.ml.dyadranking.algorithm

Class PLNetDyadRanker

java.lang.Object

ai.libs.jaicore.ml.dyadranking.algorithm.PLNetDyadRanker

All Implemented Interfaces:

IBatchLearner<IDyadRankingInstance,IDyadRankingInstance,DyadRankingDataset>, ICertaintyProvider<IDyadRankingInstance,IDyadRankingInstance,DyadRankingDataset>, IOnlineLearner<IDyadRankingInstance,IDyadRankingInstance,DyadRankingDataset>, IPredictiveModel<IDyadRankingInstance,IDyadRankingInstance,DyadRankingDataset>, IDyadRanker, IPLDyadRanker

public class PLNetDyadRanker
extends java.lang.Object
implements IPLDyadRanker, IOnlineLearner<IDyadRankingInstance,IDyadRankingInstance,DyadRankingDataset>, ICertaintyProvider<IDyadRankingInstance,IDyadRankingInstance,DyadRankingDataset>

A dyad ranker based on a Plackett-Luce network. All the provided algorithms are implementations of the PLModel introduced in [1]. [1] Schäfer, D., & Hüllermeier, E. (2018). Dyad ranking using Plackett--Luce models based on joint feature representations. Machine Learning, 107(5), 903–941. https://doi.org/10.1007/s10994-017-5694-9

Constructor Summary

Constructors

Constructor	Description
PLNetDyadRanker()	Constructs a new PLNetDyadRanker using the default IPLNetDyadRankerConfiguration.
PLNetDyadRanker(IPLNetDyadRankerConfiguration config)	Constructs a new PLNetDyadRanker using the given IPLNetDyadRankerConfiguration.

Method Summary

Modifier and Type	Method	Description
void	createNetworkFromDl4jConfigFile(java.io.File configFile)	Creates a simple feed-forward MultiLayerNetwork using the json representation of a MultiLayerConfiguration in the file .
double	getCertainty(IDyadRankingInstance queryInstance)	Returns the certainty for a given IInstance.
IPredictiveModelConfiguration	getConfiguration()	Returns the IPredictiveModelConfiguration of this model.
int	getEpoch()
double	getLogProbabilityOfTopKRanking(IDyadRankingInstance drInstance, int k)	Returns the log of the probablity of the top k of a given IDyadRankingInstance under the Plackett Luce model parametrized by the latent skill values predicted by the PLNet.
double	getLogProbabilityOfTopRanking(IDyadRankingInstance drInstance)	Returns the the log of the probablity of the top ranking for a given IDyadRankingInstance under the Plackett Luce model parametrized by the latent skill values predicted by the PLNet.
double	getLogProbabilityRanking(IDyadRankingInstance drInstance)	Computes the logarithmic probability for a particular ranking according to the log Placket-Luce model.
IDyadRankingInstance	getPairWithLeastCertainty(IDyadRankingInstance drInstance)	Returns the pair of Dyads for which the model is least certain.
org.deeplearning4j.nn.multilayer.MultiLayerNetwork	getPlNet()
double	getProbabilityOfTopKRanking(IDyadRankingInstance drInstance, int k)
double	getProbabilityOfTopRanking(IDyadRankingInstance drInstance)	Returns the probablity of the top ranking for a given IDyadRankingInstance under the Plackett Luce model parametrized by the latent skill values predicted by the PLNet.
double	getProbabilityRanking(IDyadRankingInstance drInstance)	Returns the probablity of a given IDyadRankingInstance under the Plackett Luce model parametrized by the latent skill values predicted by the PLNet.
double	getSkillForDyad(Dyad dyad)	Returns the latent skill value predicted by the PLNet for a given Dyad.
void	loadModelFromFile(java.lang.String filePath)	Restore a trained model from a given file path.
java.util.List<IDyadRankingInstance>	predict(DyadRankingDataset dataset)	Performs multiple predictions based on the IInstances contained in the given AILabeledAttributeArrayDatasets and returns the result.
IDyadRankingInstance	predict(IDyadRankingInstance instance)	Performs a prediction based on the given IInstance and returns the result.
void	saveModelToFile(java.lang.String filePath)	Save a trained model at a given file path.
void	setConfiguration(IPredictiveModelConfiguration configuration)	Sets the IPredictiveModelConfiguration of this model to the given one.
void	train(DyadRankingDataset dataset)	Trains this IBatchLearner using the given AILabeledAttributeArrayDataset.
void	train(DyadRankingDataset dataset, int maxEpochs, double earlyStoppingTrainRatio)
void	train(java.util.List<org.nd4j.linalg.api.ndarray.INDArray> dataset)
void	train(java.util.List<org.nd4j.linalg.api.ndarray.INDArray> dataset, int maxEpochs, double earlyStoppingTrainRatio)
void	update(IDyadRankingInstance instance)	Updates this PLNetDyadRanker based on the given IInstance, which needs to be an IDyadRankingInstance.
void	update(java.util.Set<IDyadRankingInstance> instances)	Updates this IOnlineLearner based on the given Set of IInstances.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PLNetDyadRanker

public PLNetDyadRanker()

Constructs a new PLNetDyadRanker using the default IPLNetDyadRankerConfiguration.

PLNetDyadRanker

public PLNetDyadRanker(IPLNetDyadRankerConfiguration config)

Constructs a new PLNetDyadRanker using the given IPLNetDyadRankerConfiguration.

Parameters:

config - Configuration for the PLNetDyadRanker.

Method Detail

train

public void train(DyadRankingDataset dataset)
           throws TrainingException

Description copied from interface: IBatchLearner

Trains this IBatchLearner using the given AILabeledAttributeArrayDataset.

Specified by:

train in interface IBatchLearner<IDyadRankingInstance,IDyadRankingInstance,DyadRankingDataset>

Parameters:

dataset - The AILabeledAttributeArrayDataset which should be used for the training.

Throws:

TrainingException - If something fails during the training process.

train

public void train(java.util.List<org.nd4j.linalg.api.ndarray.INDArray> dataset)

train

public void train(DyadRankingDataset dataset,
                  int maxEpochs,
                  double earlyStoppingTrainRatio)

train

public void train(java.util.List<org.nd4j.linalg.api.ndarray.INDArray> dataset,
                  int maxEpochs,
                  double earlyStoppingTrainRatio)

update

public void update(IDyadRankingInstance instance)
            throws TrainingException

Updates this PLNetDyadRanker based on the given IInstance, which needs to be an IDyadRankingInstance. The update procedure is based on algorithm 2 in [1].

Specified by:

update in interface IOnlineLearner<IDyadRankingInstance,IDyadRankingInstance,DyadRankingDataset>

Parameters:

instances - The IInstance the update should be based on. Needs to be a IDyadRankingInstance.

Throws:

TrainingException - If something fails during the update process.

update

public void update(java.util.Set<IDyadRankingInstance> instances)
            throws TrainingException

Description copied from interface: IOnlineLearner

Updates this IOnlineLearner based on the given Set of IInstances.

Specified by:

update in interface IOnlineLearner<IDyadRankingInstance,IDyadRankingInstance,DyadRankingDataset>

Parameters:

instances - The Set of IInstances the update should be based on.

Throws:

TrainingException - If something fails during the update process.

predict

public IDyadRankingInstance predict(IDyadRankingInstance instance)
                             throws PredictionException

Description copied from interface: IPredictiveModel

Performs a prediction based on the given IInstance and returns the result.

Specified by:

predict in interface IPredictiveModel<IDyadRankingInstance,IDyadRankingInstance,DyadRankingDataset>

Parameters:

instance - The IInstance for which a prediction should be made.

Returns:

The result of the prediction.

Throws:

PredictionException - If something fails during the prediction process.

predict

public java.util.List<IDyadRankingInstance> predict(DyadRankingDataset dataset)
                                             throws PredictionException

Description copied from interface: IPredictiveModel

Performs multiple predictions based on the IInstances contained in the given AILabeledAttributeArrayDatasets and returns the result.

Specified by:

predict in interface IPredictiveModel<IDyadRankingInstance,IDyadRankingInstance,DyadRankingDataset>

Parameters:

dataset - The AILabeledAttributeArrayDataset for which predictions should be made.

Returns:

The result of the predictions.

Throws:

PredictionException - If something fails during the prediction process.

setConfiguration

public void setConfiguration(IPredictiveModelConfiguration configuration)
                      throws ConfigurationException

Description copied from interface: IPredictiveModel

Sets the IPredictiveModelConfiguration of this model to the given one.

Specified by:

setConfiguration in interface IPredictiveModel<IDyadRankingInstance,IDyadRankingInstance,DyadRankingDataset>

Throws:

ConfigurationException - If something fails during the configuration process.

getConfiguration

public IPredictiveModelConfiguration getConfiguration()

Description copied from interface: IPredictiveModel

Returns the IPredictiveModelConfiguration of this model.

Specified by:

getConfiguration in interface IPredictiveModel<IDyadRankingInstance,IDyadRankingInstance,DyadRankingDataset>

Returns:

The IPredictiveModelConfiguration of this model.

createNetworkFromDl4jConfigFile

public void createNetworkFromDl4jConfigFile(java.io.File configFile)

Creates a simple feed-forward MultiLayerNetwork using the json representation of a MultiLayerConfiguration in the file .

Parameters:

configFile - File containing the json representation of the MultiLayerConfiguration

saveModelToFile

public void saveModelToFile(java.lang.String filePath)
                     throws java.io.IOException

Save a trained model at a given file path. Note that the produced file is a zip file and a ".zip" ending is added.

Parameters:

filePath - The file path to save to.

Throws:

java.io.IOException

loadModelFromFile

public void loadModelFromFile(java.lang.String filePath)
                       throws java.io.IOException

Restore a trained model from a given file path. Warning: does not check whether the loaded model is a valid PLNet or conforms to the configuration of the object.

Parameters:

filePath - The file to load from.

Throws:

java.io.IOException

getPlNet

public org.deeplearning4j.nn.multilayer.MultiLayerNetwork getPlNet()

getEpoch

public int getEpoch()

getCertainty

public double getCertainty(IDyadRankingInstance queryInstance)

Description copied from interface: ICertaintyProvider

Returns the certainty for a given IInstance.

Specified by:

getCertainty in interface ICertaintyProvider<IDyadRankingInstance,IDyadRankingInstance,DyadRankingDataset>

Parameters:

queryInstance - IInstance for which certainty shall be obtained.

Returns:

Certainty of the model for the given IInstance

getPairWithLeastCertainty

public IDyadRankingInstance getPairWithLeastCertainty(IDyadRankingInstance drInstance)

Returns the pair of Dyads for which the model is least certain.

Parameters:

drInstance - Ranking for which certainty should be assessed.

Returns:

The pair of Dyads for which the model is least certain.

getProbabilityOfTopRanking

public double getProbabilityOfTopRanking(IDyadRankingInstance drInstance)

Returns the probablity of the top ranking for a given IDyadRankingInstance under the Plackett Luce model parametrized by the latent skill values predicted by the PLNet. This may be useful as the probability of a particular ranking diminishes drastically with increasing length of the ranking.

Parameters:

drInstance - IDyadRankingInstance for which the probability is computed.

Returns:

Probablity of the top ranking for a given IDyadRankingInstance given the Plackett Luce model parametrized by the skill values predicted by the PLNet.

getProbabilityOfTopKRanking

public double getProbabilityOfTopKRanking(IDyadRankingInstance drInstance,
                                          int k)

getLogProbabilityOfTopRanking

public double getLogProbabilityOfTopRanking(IDyadRankingInstance drInstance)

Returns the the log of the probablity of the top ranking for a given IDyadRankingInstance under the Plackett Luce model parametrized by the latent skill values predicted by the PLNet. This may be useful as the probability of a particular ranking diminishes drastically with increasing length of the ranking.

Parameters:

drInstance - IDyadRankingInstance for which the probability is computed.

Returns:

Log of the probablity of the top ranking for a given IDyadRankingInstance given the Plackett Luce model parametrized by the skill values predicted by the PLNet.

getLogProbabilityOfTopKRanking

public double getLogProbabilityOfTopKRanking(IDyadRankingInstance drInstance,
                                             int k)

Returns the log of the probablity of the top k of a given IDyadRankingInstance under the Plackett Luce model parametrized by the latent skill values predicted by the PLNet. This may be useful as the probability of a particular ranking diminishes drastically with increasing length of the ranking.

Parameters:

drInstance - IDyadRankingInstance for which the probability is computed.

k - Number of top dyads to be considered.

Returns:

Log of the probablity of the top k of a the given IDyadRankingInstance given the Plackett Luce model parametrized by the skill values predicted by the PLNet.

getProbabilityRanking

public double getProbabilityRanking(IDyadRankingInstance drInstance)

Returns the probablity of a given IDyadRankingInstance under the Plackett Luce model parametrized by the latent skill values predicted by the PLNet.

Parameters:

drInstance - IDyadRankingInstance for which the probability is computed.

Returns:

Probability of the given IDyadRankingInstance given the Plackett Luce model parametrized by the skill values predicted by the PLNet.

getLogProbabilityRanking

public double getLogProbabilityRanking(IDyadRankingInstance drInstance)

Computes the logarithmic probability for a particular ranking according to the log Placket-Luce model.

Parameters:

drInstance -

Returns:

Logarithmic probability of the given ranking.

getSkillForDyad

public double getSkillForDyad(Dyad dyad)

Returns the latent skill value predicted by the PLNet for a given Dyad.

Parameters:

dyad - Dyad for which the skill is to be predicted.

Returns:

Skill of the given Dyad.