001/*
002 * Copyright (c) 2015-2020, Oracle and/or its affiliates. All rights reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.tribuo;
018
019import com.oracle.labs.mlrg.olcut.util.Pair;
020
021import java.io.Serializable;
022import java.util.Set;
023
024/**
025 * Tracks relevant properties of the appropriate {@link Output} subclass.
026 * <p>
027 * Can generate a {@link ImmutableOutputInfo} which contains id numbers, and
028 * a {@link MutableOutputInfo} for repeated training with more data.
029 */
030public interface OutputInfo<T extends Output<T>> extends Serializable {
031
032    /**
033     * Returns a set of {@link Output} which represent the space of possible
034     * values the {@link Output} has taken.
035     * <p>
036     * For real values this set represents the number of dimensions observed.
037     *
038     * @return A Set of {@code T}.
039     */
040    public Set<T> getDomain();
041
042    /**
043     * Returns the number of possible values this OutputInfo knows about.
044     * <p>
045     * For real values this is the number of dimensions observed.
046     * @return An int representing the size of the domain.
047     */
048    public int size();
049
050    /**
051     * Returns the number of unknown {@link Output} instances (generated by {@link OutputFactory#getUnknownOutput()})
052     * that this OutputInfo has seen.
053     *
054     * @return The number of unknown outputs observed.
055     */
056    public int getUnknownCount();
057
058    /**
059     * Generates an {@link ImmutableOutputInfo} which has a copy of the data
060     * in this {@code OutputInfo}, but also has id values and is immutable.
061     * @return An immutable copy of this OutputInfo.
062     */
063    public ImmutableOutputInfo<T> generateImmutableOutputInfo();
064
065    /**
066     * Generates a mutable copy of this {@code OutputInfo}.
067     * @return A mutable copy of this OutputInfo.
068     */
069    public MutableOutputInfo<T> generateMutableOutputInfo();
070
071    /**
072     * Generates a copy of this OutputInfo, including it's mutability.
073     * @return A copy of the OutputInfo.
074     */
075    public OutputInfo<T> copy();
076
077    /**
078     * Generates a String form of this OutputInfo.
079     * <p>
080     * This String can contain newlines, tabs and other formatting.
081     * @return A formatted String representing this OutputInfo.
082     */
083    public String toReadableString();
084
085    /**
086     * An Iterable over the possible outputs and the number of times they were observed.
087     * <p>
088     * Provides similar functionality to an iterator over the entrySet of a Map, though this
089     * is a copy of the data and immutable.
090     *
091     * @return Lambda wrapping an iterator over Pairs.
092     */
093    public Iterable<Pair<String,Long>> outputCountsIterable();
094
095}