Package ai.libs.jaicore.ml.ranking.dyad.learner.algorithm

Class PLNetDyadRanker

  • All Implemented Interfaces:
    IDyadRanker, IPLDyadRanker, org.api4.java.ai.ml.core.learner.IFittable<org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance,​org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingDataset>, org.api4.java.ai.ml.core.learner.IFittablePredictor<org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance,​org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingDataset>, org.api4.java.ai.ml.core.learner.ILearnerConfigHandler, org.api4.java.ai.ml.core.learner.IPredictor<org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance,​org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingDataset>, org.api4.java.ai.ml.core.learner.IProbabilisticPredictor, org.api4.java.ai.ml.core.learner.ISupervisedLearner<org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance,​org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingDataset>, org.api4.java.ai.ml.ranking.learner.IRanker<org.api4.java.ai.ml.ranking.dyad.dataset.IDyad,​org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance,​org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingDataset>
    public class PLNetDyadRanker
extends ASupervisedLearner<org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance,​org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingDataset,​org.api4.java.ai.ml.ranking.IRanking<org.api4.java.ai.ml.ranking.dyad.dataset.IDyad>,​org.api4.java.ai.ml.ranking.IRankingPredictionBatch>
implements IPLDyadRanker, org.api4.java.ai.ml.core.learner.IProbabilisticPredictor
    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

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      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 .
      void fit​(DyadRankingDataset dataset, int maxEpochs, double earlyStoppingTrainRatio)  
      void fit​(java.util.List<org.nd4j.linalg.api.ndarray.INDArray> dataset)  
      void fit​(java.util.List<org.nd4j.linalg.api.ndarray.INDArray> dataset, int maxEpochs, double earlyStoppingTrainRatio)  
      void fit​(org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingDataset dTrain)  
      double getCertainty​(org.api4.java.ai.ml.core.dataset.supervised.ILabeledInstance testInstance, java.lang.Object label)  
      double getCertainty​(org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance queryInstance, org.api4.java.ai.ml.ranking.IRanking<org.api4.java.ai.ml.ranking.dyad.dataset.IDyad> sizeTwoRanking)  
      int getEpoch()  
      double getLogProbabilityOfTopKRanking​(org.api4.java.ai.ml.ranking.dyad.dataset.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​(org.api4.java.ai.ml.ranking.dyad.dataset.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​(org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance drInstance)
      Computes the logarithmic probability for a particular ranking according to the log Placket-Luce model.
      org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance getPairWithLeastCertainty​(org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance drInstance)
      Returns the pair of Dyads for which the model is least certain.
      org.deeplearning4j.nn.multilayer.MultiLayerNetwork getPlNet()  
      double getProbabilityOfTopKRanking​(org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance drInstance, int k)  
      double getProbabilityOfTopRanking​(org.api4.java.ai.ml.ranking.dyad.dataset.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​(org.api4.java.ai.ml.ranking.dyad.dataset.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​(org.api4.java.ai.ml.ranking.dyad.dataset.IDyad 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.
      org.api4.java.ai.ml.ranking.IRanking<org.api4.java.ai.ml.ranking.dyad.dataset.IDyad> predict​(org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance xTest)  
      org.api4.java.ai.ml.ranking.IRankingPredictionBatch predict​(org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance[] dTest)  
      void saveModelToFile​(java.lang.String filePath)
      Save a trained model at a given file path.
      void update​(java.util.Set<org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance> instances)  
      void update​(org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance instance)
      Updates this PLNetDyadRanker based on the given IInstance, which needs to be an IDyadRankingInstance.

      • Methods inherited from class java.lang.Object

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

      • Methods inherited from interface org.api4.java.ai.ml.core.learner.IFittablePredictor

        fitAndPredict, fitAndPredict, fitAndPredict

      • Methods inherited from interface org.api4.java.ai.ml.core.learner.ILearnerConfigHandler

        getConfig, setConfig

      • Methods inherited from interface org.api4.java.ai.ml.core.learner.IPredictor

        predict

    • Method Detail

      • update

        public void update​(org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance instance)
            throws org.api4.java.ai.ml.core.exception.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].
        Parameters:
        instances - The IInstance the update should be based on. Needs to be a IDyadRankingInstance.
        Throws:
        org.api4.java.ai.ml.core.exception.TrainingException - If something fails during the update process.

      • update

        public void update​(java.util.Set<org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance> instances)
            throws org.api4.java.ai.ml.core.exception.TrainingException
        Throws:
        org.api4.java.ai.ml.core.exception.TrainingException

      • 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()

      • getPairWithLeastCertainty

        public org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance getPairWithLeastCertainty​(org.api4.java.ai.ml.ranking.dyad.dataset.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​(org.api4.java.ai.ml.ranking.dyad.dataset.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​(org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance drInstance,
                                          int k)

      • getLogProbabilityOfTopRanking

        public double getLogProbabilityOfTopRanking​(org.api4.java.ai.ml.ranking.dyad.dataset.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​(org.api4.java.ai.ml.ranking.dyad.dataset.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​(org.api4.java.ai.ml.ranking.dyad.dataset.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​(org.api4.java.ai.ml.ranking.dyad.dataset.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​(org.api4.java.ai.ml.ranking.dyad.dataset.IDyad 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.

      • fit

        public void fit​(DyadRankingDataset dataset,
                int maxEpochs,
                double earlyStoppingTrainRatio)

      • fit

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

      • fit

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

      • fit

        public void fit​(org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingDataset dTrain)
         throws org.api4.java.ai.ml.core.exception.TrainingException,
                java.lang.InterruptedException
        Specified by:
        fit in interface org.api4.java.ai.ml.core.learner.IFittable<org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance,​org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingDataset>
        Throws:
        org.api4.java.ai.ml.core.exception.TrainingException
        java.lang.InterruptedException

      • predict

        public org.api4.java.ai.ml.ranking.IRanking<org.api4.java.ai.ml.ranking.dyad.dataset.IDyad> predict​(org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance xTest)
                                                                                             throws org.api4.java.ai.ml.core.exception.PredictionException,
                                                                                                    java.lang.InterruptedException
        Specified by:
        predict in interface org.api4.java.ai.ml.core.learner.IPredictor<org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance,​org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingDataset>
        Specified by:
        predict in interface org.api4.java.ai.ml.ranking.learner.IRanker<org.api4.java.ai.ml.ranking.dyad.dataset.IDyad,​org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance,​org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingDataset>
        Specified by:
        predict in class ASupervisedLearner<org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance,​org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingDataset,​org.api4.java.ai.ml.ranking.IRanking<org.api4.java.ai.ml.ranking.dyad.dataset.IDyad>,​org.api4.java.ai.ml.ranking.IRankingPredictionBatch>
        Throws:
        org.api4.java.ai.ml.core.exception.PredictionException
        java.lang.InterruptedException

      • getCertainty

        public double getCertainty​(org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance queryInstance,
                           org.api4.java.ai.ml.ranking.IRanking<org.api4.java.ai.ml.ranking.dyad.dataset.IDyad> sizeTwoRanking)

      • getCertainty

        public double getCertainty​(org.api4.java.ai.ml.core.dataset.supervised.ILabeledInstance testInstance,
                           java.lang.Object label)
                    throws org.api4.java.ai.ml.core.exception.PredictionException,
                           java.lang.InterruptedException
        Specified by:
        getCertainty in interface org.api4.java.ai.ml.core.learner.IProbabilisticPredictor
        Throws:
        org.api4.java.ai.ml.core.exception.PredictionException
        java.lang.InterruptedException

      • predict

        public org.api4.java.ai.ml.ranking.IRankingPredictionBatch predict​(org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance[] dTest)
                                                            throws org.api4.java.ai.ml.core.exception.PredictionException,
                                                                   java.lang.InterruptedException
        Specified by:
        predict in interface org.api4.java.ai.ml.core.learner.IPredictor<org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance,​org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingDataset>
        Specified by:
        predict in class ASupervisedLearner<org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingInstance,​org.api4.java.ai.ml.ranking.dyad.dataset.IDyadRankingDataset,​org.api4.java.ai.ml.ranking.IRanking<org.api4.java.ai.ml.ranking.dyad.dataset.IDyad>,​org.api4.java.ai.ml.ranking.IRankingPredictionBatch>
        Throws:
        org.api4.java.ai.ml.core.exception.PredictionException
        java.lang.InterruptedException