com.feedzai.fos.api.Scorer Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of fos-api Show documentation
There is a newer version: 1.0.10
/*
 * $#
 * FOS API
 *  
 * Copyright (C) 2013 Feedzai SA
 *  
 * This software is licensed under the Apache License, Version 2.0 (the "Apache License") or the GNU
 * Lesser General Public License version 3 (the "GPL License"). You may choose either license to govern
 * your use of this software only upon the condition that you accept all of the terms of either the Apache
 * License or the LGPL License.
 * 
 * You may obtain a copy of the Apache License and the LGPL License at:
 * 
 * http://www.apache.org/licenses/LICENSE-2.0.txt
 * http://www.gnu.org/licenses/lgpl-3.0.txt
 * 
 * Unless required by applicable law or agreed to in writing, software distributed under the Apache License
 * or the LGPL License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
 * either express or implied. See the Apache License and the LGPL License for the specific language governing
 * permissions and limitations under the Apache License and the LGPL License.
 * #$
 */
package com.feedzai.fos.api;

import com.feedzai.fos.common.validation.NotNull;
import com.google.common.collect.ImmutableList;

import java.util.List;
import java.util.UUID;

/**
 * This class represents a scorer that is capable of scoring instances against a set of models.
 * 
 * Each scorer can hold multiple models and MUST support multi-threaded usage.
 *
 * @author Marco Jorge ([email protected])
 */
public interface Scorer  {
    /**
     * Score the scorable against the given modelIds.
     * 
 The score must be between 0 and 1.
     * 
 The resulting scores are returned by the same order as the modelIds (modelsIds(pos) » return(pos)).
     *
     * @param modelIds the list of models to score
     * @param scorable the instance data to score
     * @return a list of scores double[] where each list position contains the score for each classifier
     * @throws FOSException when scoring was not possible
     */
    @NotNull
    default List score(List modelIds, Object[] scorable) throws FOSException {
        ImmutableList.Builder resultsBuilder = ImmutableList.builder();

        for (UUID modelId : modelIds) {
            resultsBuilder.add(score(modelId, scorable));
        }

        return resultsBuilder.build();
    }

    /**
     * Score all scorables against the given modelId.
     * 
 The score must be between 0 and 1.
     * 
 The resulting scores are returned in the same order as the scorables (scorables(pos) » return(pos)).
     *
     * @param modelId   the id of the model
     * @param scorables an array of instances to score
     * @return a list of scores double[] where each list position contains the score for each scorable.
     * @throws FOSException when scoring was not possible
     */
    @NotNull
    default List score(UUID modelId, List scorables) throws FOSException {
        ImmutableList.Builder resultsBuilder = ImmutableList.builder();

        for (Object[] scorable : scorables) {
            resultsBuilder.add(score(modelId, scorable));
        }

        return resultsBuilder.build();
    }

    /**
     * Score a single scorable against the given modelId.
     *
     *  The score must be between 0 and 1.
     *
     * @param modelId   the id of the model
     * @param scorable  the instance to score
     * @return the scores
     * @throws FOSException when scoring was not possible
     */
    @NotNull
    double[] score(UUID modelId, Object[] scorable) throws FOSException;

    /**
     * Frees any resources allocated to this scorer.
     *
     * @throws FOSException when closing resources was not possible
     */
    void close() throws FOSException;
}