/*
 * Created on Jul 14, 2007
 *
 * Copyright (c) 2007, the JUNG Project and the Regents of the University 
 * of California
 * All rights reserved.
 *
 * This software is open-source under the BSD license; see either
 * "license.txt" or
 * http://jung.sourceforge.net/license.txt for a description.
 */
package edu.uci.ics.jung.algorithms.scoring;

import org.apache.commons.collections15.Transformer;

import edu.uci.ics.jung.graph.Hypergraph;

/**
 * An abstract class for iterative random-walk-based vertex scoring algorithms 
 * that have a 
 * fixed probability, for each vertex, of 'jumping' to that vertex at each
 * step in the algorithm (rather than following a link out of that vertex).
 *
 * @param <V> the vertex type
 * @param <E> the edge type
 * @param <S> the score type
 */
public abstract class AbstractIterativeScorerWithPriors<V,E,S> extends
        AbstractIterativeScorer<V,E,S> implements VertexScorer<V,S>
{
    /**
     * The prior probability of each vertex being visited on a given 
     * 'jump' (non-link-following) step.
     */
    protected Transformer<V,? extends S> vertex_priors;

    /**
     * The probability of making a 'jump' at each step.
     */
    protected double alpha;

    /**
     * Creates an instance for the specified graph, edge weights, vertex
     * priors, and jump probability.
     * @param g the graph whose vertices are to be assigned scores
     * @param edge_weights the edge weights to use in the score assignment
     * @param vertex_priors the prior probabilities of each vertex being 'jumped' to
     * @param alpha the probability of making a 'jump' at each step
     */
    public AbstractIterativeScorerWithPriors(Hypergraph<V,E> g,
            Transformer<E,? extends Number> edge_weights, 
            Transformer<V,? extends S> vertex_priors, double alpha)
    {
        super(g, edge_weights);
        this.vertex_priors = vertex_priors;
        this.alpha = alpha;
        initialize();
    }

    /**
     * Creates an instance for the specified graph, vertex priors, and jump
     * probability, with edge weights specified by the subclass.
     * @param g the graph whose vertices are to be assigned scores
     * @param vertex_priors the prior probabilities of each vertex being 'jumped' to
     * @param alpha the probability of making a 'jump' at each step
     */
    public AbstractIterativeScorerWithPriors(Hypergraph<V,E> g, 
    		Transformer<V,? extends S> vertex_priors, double alpha)
    {
        super(g);
        this.vertex_priors = vertex_priors;
        this.alpha = alpha;
        initialize();
    }

    /**
     * Initializes the state of this instance.
     */
    @Override
    public void initialize()
    {
        super.initialize();
        // initialize output values to priors
        // (output and current are swapped before each step(), so current will
        // have priors when update()s start happening)
        for (V v : graph.getVertices())
            setOutputValue(v, getVertexPrior(v));
    }
    
    /**
     * Returns the prior probability for <code>v</code>.
     * @param v the vertex whose prior probability is being queried
     * @return the prior probability for <code>v</code>
     */
    protected S getVertexPrior(V v)
    {
        return vertex_priors.transform(v);
    }

    /**
     * Returns a Transformer which maps each vertex to its prior probability.
     * @return a Transformer which maps each vertex to its prior probability
     */
    public Transformer<V, ? extends S> getVertexPriors()
    {
        return vertex_priors;
    }

    /**
     * Returns the probability of making a 'jump' (non-link-following step).
     * @return the probability of making a 'jump' (non-link-following step)
     */
    public double getAlpha()
    {
        return alpha;
    }
}