org.lenskit.knn.item.model.ItemItemBuildContext Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of lenskit-knn Show documentation
There is a newer version: 3.0-T5
/*
 * LensKit, an open source recommender systems toolkit.
 * Copyright 2010-2014 LensKit Contributors.  See CONTRIBUTORS.md.
 * Work on LensKit has been funded by the National Science Foundation under
 * grants IIS 05-34939, 08-08692, 08-12148, and 10-17697.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
 * details.
 *
 * You should have received a copy of the GNU General Public License along with
 * this program; if not, write to the Free Software Foundation, Inc., 51
 * Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
package org.lenskit.knn.item.model;

import com.google.common.base.Preconditions;
import it.unimi.dsi.fastutil.longs.Long2ObjectMap;
import it.unimi.dsi.fastutil.longs.LongIterator;
import it.unimi.dsi.fastutil.longs.LongSortedSet;
import it.unimi.dsi.fastutil.longs.LongSortedSets;
import org.grouplens.grapht.annotation.DefaultProvider;
import org.lenskit.inject.Shareable;
import org.grouplens.lenskit.transform.normalize.VectorNormalizer;
import org.grouplens.lenskit.vectors.SparseVector;
import org.lenskit.inject.Transient;
import org.lenskit.util.keys.SortedKeyIndex;

import javax.annotation.Nonnull;
import java.io.Serializable;
import java.util.Iterator;

/**
 * Encapsulation of data needed during an item-item model build.  This class
 * provides access to item vectors and the item universe for use in  building
 * up the model in the accumulator.
 *
 * This is shareable to make it more usable in the evaluator.  Typical built models
 * will not include it, and any dependencies on it should be {@link Transient}.
 *
 * @author GroupLens Research
 * @see ItemItemModelBuilder
 */
@DefaultProvider(ItemItemBuildContextProvider.class)
@Shareable
public class ItemItemBuildContext implements Serializable {
    private static final long serialVersionUID = 1L;

    @Nonnull
    private
    SortedKeyIndex items;
    @Nonnull
    private
    SparseVector[] itemVectors;

    @Nonnull
    private Long2ObjectMap userItems;

    /**
     * Set up a new item build context.
     *
     * @param universe The set of items for the model.
     * @param vectors  Map of item IDs to item rating vectors.
     * @param userItems Map of user IDs to candidate items
     */
    ItemItemBuildContext(@Nonnull SortedKeyIndex universe,
                         @Nonnull SparseVector[] vectors,
                         @Nonnull Long2ObjectMap userItems) {
        this.userItems = userItems;
        items = universe;
        itemVectors = vectors;
    }

    /**
     * Get the set of items.
     *
     * @return The set of all items to build a model over.
     */
    @Nonnull
    public LongSortedSet getItems() {
        return items.keySet();
    }

    /**
     * Get the rating vector for an item. Rating vectors contain normalized ratings,
     * using the applicable {@link VectorNormalizer} on the user rating vectors.
     *
     * @param item The item to query.
     * @return The rating vector for {@code item}.
     * @throws IllegalArgumentException if {@code item} is not a valid item.
     */
    @Nonnull
    public SparseVector itemVector(long item) {
        int idx = items.tryGetIndex(item);
        Preconditions.checkArgument(idx >= 0, "unknown item");
        return itemVectors[idx];
    }

    /**
     * Get the items rated by a particular user.
     * 
     * @param user The user to query for.
     * @return The items rated by {@code user}.
     */
    @Nonnull
    public LongSortedSet getUserItems(long user) {
        LongSortedSet items = userItems.get(user);
        if (items == null) {
            items = LongSortedSets.EMPTY_SET;
        }
        return items;
    }

    /**
     * Provides an Iterable over ItemVecPairs
     *
     * @return An Iterable over ItemVecPairs, objects
     *         pairing item ids and their corresponding vectors.
     * @deprecated This will go away in LensKit 3.0.
     */
    @Deprecated
    public Iterable getItemPairs() {
        return new Iterable() {
            @Override
            public Iterator iterator() {
                return getItemPairIterator();
            }
        };
    }

    /**
     * Returns an Iterator over all item vector pairs.
     *
     * @return An Iterator over ItemVecPairs, an object
     *         offering public access to the item ids and their
     *         corresponding vectors.
     * @deprecated This will go away in LensKit 3.0.
     */
    @Deprecated
    public Iterator getItemPairIterator() {
        return new FastIteratorImpl(items.keySet(), items.keySet());
    }

    /**
     * An Iterator implementation iterating over all ItemVecPairs from
     * the parameter LongSortedSets of item ids.
     */
    private final class FastIteratorImpl implements Iterator {
        private ItemVecPair itemVecPair;
        private LongIterator iter1;
        private LongSortedSet list2;
        private LongIterator iter2;

        public FastIteratorImpl(LongSortedSet list1, LongSortedSet list2) {
            itemVecPair = new ItemVecPair();
            iter1 = list1.iterator();
            if (iter1.hasNext()) {
                itemVecPair.setItem1(iter1.nextLong());
            }
            this.list2 = list2;
            iter2 = list2.iterator();
        }

        @Override
        public boolean hasNext() {
            return iter1.hasNext() || iter2.hasNext();
        }

        @Override
        public ItemVecPair next() {
            if (!iter2.hasNext()) {
                itemVecPair.setItem1(iter1.nextLong());
                iter2 = list2.iterator();
            }
            itemVecPair.setItem2(iter2.nextLong());
            itemVecPair.lastInRow = !iter2.hasNext();
            return itemVecPair;
        }

        @Override
        public void remove() {
            throw new UnsupportedOperationException();
        }
    }

    /**
     * A pair of item ids and their corresponding item
     * vectors, avoiding (un)boxing the ids.
     */
    public final class ItemVecPair {
        public long itemId1;
        public long itemId2;
        public SparseVector vec1;
        public SparseVector vec2;
        public boolean lastInRow;

        public void setItem1(long itemId1) {
            this.itemId1 = itemId1;
            vec1 = itemVector(itemId1);
        }

        public void setItem2(long itemId2) {
            this.itemId2 = itemId2;
            vec2 = itemVector(itemId2);
        }
    }
}