Compute the TF-IDF scores for each word in each document. The collection
    of documents must be in bag-of-words format.

    .. math::
        \mbox{TF-IDF}(w, d) = tf(w, d) * log(N / f(w))

    where :math:`tf(w, d)` is the number of times word :math:`w` appeared in
    document :math:`d`, :math:`f(w)` is the number of documents word :math:`w`
    appeared in, :math:`N` is the number of documents, and we use the
    natural logarithm.

    Parameters
    ----------
    text : SArray[str | dict | list]
        Input text data. 

    Returns
    -------
    out : SArray[dict]
        The same document corpus where each score has been replaced by the
        TF-IDF transformation.

    See Also
    --------
    count_words, count_ngrams, tokenize,

    References
    ----------
    - `Wikipedia - TF-IDF <https://en.wikipedia.org/wiki/TFIDF>`_

    Examples
    --------
    .. sourcecode:: python

        >>> import turicreate

        >>> docs = turicreate.SArray('https://static.turi.com/datasets/nips-text')
        >>> docs_tfidf = turicreate.text_analytics.tf_idf(docs)

def tf_idf(text):
    """
    Compute the TF-IDF scores for each word in each document. The collection
    of documents must be in bag-of-words format.

    .. math::
        \mbox{TF-IDF}(w, d) = tf(w, d) * log(N / f(w))

    where :math:`tf(w, d)` is the number of times word :math:`w` appeared in
    document :math:`d`, :math:`f(w)` is the number of documents word :math:`w`
    appeared in, :math:`N` is the number of documents, and we use the
    natural logarithm.

    Parameters
    ----------
    text : SArray[str | dict | list]
        Input text data. 

    Returns
    -------
    out : SArray[dict]
        The same document corpus where each score has been replaced by the
        TF-IDF transformation.

    See Also
    --------
    count_words, count_ngrams, tokenize,

    References
    ----------
    - `Wikipedia - TF-IDF <https://en.wikipedia.org/wiki/TFIDF>`_

    Examples
    --------
    .. sourcecode:: python

        >>> import turicreate

        >>> docs = turicreate.SArray('https://static.turi.com/datasets/nips-text')
        >>> docs_tfidf = turicreate.text_analytics.tf_idf(docs)
    """
    _raise_error_if_not_sarray(text, "text")

    if len(text) == 0:
        return _turicreate.SArray()

    dataset = _turicreate.SFrame({'docs': text})
    scores = _feature_engineering.TFIDF('docs').fit_transform(dataset)

    return scores['docs']