spark-nlp 2.6.3rc1__py2.py3-none-any.whl → 6.2.1__py2.py3-none-any.whl

sparknlp/annotation.py

@@ -1,32 +1,120 @@
+#  Copyright 2017-2022 John Snow Labs
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+"""Contains the Annotation data format
+"""
+
 from pyspark.sql.types import *
 
 
 class Annotation:
+    """Represents the output of Spark NLP Annotators and their details.
+
+    Parameters
+    ----------
+    annotator_type : str
+        The type of the output of the annotator. Possible values are ``DOCUMENT,
+        TOKEN, WORDPIECE, WORD_EMBEDDINGS, SENTENCE_EMBEDDINGS, CATEGORY, DATE,
+        ENTITY, SENTIMENT, POS, CHUNK, NAMED_ENTITY, NEGEX, DEPENDENCY,
+        LABELED_DEPENDENCY, LANGUAGE, KEYWORD, DUMMY``.
+    begin : int
+        The index of the first character under this annotation.
+    end : int
+        The index of the last character under this annotation.
+    result : str
+        The resulting string of the annotation.
+    metadata : dict
+        Associated metadata for this annotation
+    embeddings : list
+        Embeddings vector where applicable
+    """
 
-    def __init__(self, annotator_type, begin, end, result, metadata, embeddings):
-        self.annotator_type = annotator_type
+    def __init__(self, annotatorType, begin, end, result, metadata, embeddings):
+        self.annotatorType = annotatorType
         self.begin = begin
         self.end = end
         self.result = result
         self.metadata = metadata
         self.embeddings = embeddings
 
+    def copy(self, result):
+        """Creates new Annotation with a different result, containing all
+        settings of this Annotation.
+
+        Parameters
+        ----------
+        result : str
+            The result of the annotation that should be copied.
+
+        Returns
+        -------
+        Annotation
+            Newly created Annotation
+        """
+        return Annotation(self.annotatorType, self.begin, self.end, result, self.metadata, self.embeddings)
+
     def __str__(self):
-        return "Annotation(%s, %i, %i, %s, %s)" % (
-            self.annotator_type,
+        return "Annotation(%s, %i, %i, %s, %s, %s)" % (
+            self.annotatorType,
             self.begin,
             self.end,
             self.result,
-            str(self.metadata)
+            str(self.metadata),
+            str(self.embeddings)
         )
 
     def __repr__(self):
         return self.__str__()
 
+    def __eq__(self, other):
+        same_annotator_type = self.annotatorType == other.annotatorType
+        same_result = self.result == other.result
+        same_begin = self.begin == other.begin
+        same_end = self.end == other.end
+        same_metadata = dict(self.metadata) == other.metadata
+        same_embeddings = self.embeddings == other.embeddings
+
+        same_annotation = \
+            same_annotator_type and same_result and same_begin and same_end and same_metadata and same_embeddings
+
+        return same_annotation
+
     @staticmethod
     def dataType():
+        """Returns a Spark `StructType`, that represents the schema of the
+        Annotation.
+
+        The Schema looks like::
+
+            struct (containsNull = True)
+            |-- annotatorType: string (nullable = False)
+            |-- begin: integer (nullable = False)
+            |-- end: integer (nullable = False)
+            |-- result: string (nullable = False)
+            |-- metadata: map (nullable = False)
+            |    |-- key: string
+            |    |-- value: string (valueContainsNull = True)
+            |-- embeddings: array (nullable = False)
+            |    |-- element: float (containsNull = False)
+
+        Returns
+        -------
+        :class:`pyspark.sql.types.StructType`
+            Spark Schema of the Annotation
+        """
         return StructType([
-            StructField('annotator_type', StringType(), False),
+            StructField('annotatorType', StringType(), False),
             StructField('begin', IntegerType(), False),
             StructField('end', IntegerType(), False),
             StructField('result', StringType(), False),
@@ -36,4 +124,47 @@ class Annotation:
 
     @staticmethod
     def arrayType():
+        """Returns a Spark `ArrayType`, that contains the `dataType` of the
+        annotation.
+
+        Returns
+        -------
+        :class:`pyspark.sql.types.ArrayType`
+            ArrayType with the Annotation data type embedded.
+        """
         return ArrayType(Annotation.dataType())
+
+    @staticmethod
+    def fromRow(row):
+        """Creates a Annotation from a Spark `Row`.
+
+        Parameters
+        ----------
+        row : :class:`pyspark.sql.Row`
+            Spark row containing columns for ``annotatorType, begin, end,
+            result, metadata, embeddings``.
+
+        Returns
+        -------
+        Annotation
+            The new Annotation.
+        """
+        return Annotation(row.annotatorType, row.begin, row.end, row.result, row.metadata, row.embeddings)
+
+    @staticmethod
+    def toRow(annotation):
+        """Transforms an Annotation to a Spark `Row`.
+
+        Parameters
+        ----------
+        annotation : Annotation
+            The Annotation to be transformed.
+
+        Returns
+        -------
+        :class:`pyspark.sql.Row`
+            The new Row.
+        """
+        from pyspark.sql import Row
+        return Row(annotation.annotatorType, annotation.begin, annotation.end, annotation.result, annotation.metadata,
+                   annotation.embeddings)

sparknlp/annotation_audio.py

@@ -0,0 +1,61 @@
+#  Copyright 2017-2022 John Snow Labs
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+"""Contains the AnnotationAudio data format
+"""
+
+
+class AnnotationAudio:
+    """Represents the output of Spark NLP Annotators for audio output and their details.
+
+    Parameters
+    ----------
+    annotator_type : str
+        The type of the output of the annotator. Possible values are ``AUDIO``.
+    result : list(floats)
+        Audio data in floats - already loaded/processed audio files
+    metadata : dict
+        Associated metadata for this annotation
+    """
+
+    def __init__(self, annotatorType, result, metadata):
+        self.annotatorType = annotatorType
+        self.result = result
+        self.metadata = metadata
+
+    def copy(self, result):
+        """Creates new AnnotationAudio with a different result, containing all
+        settings of this Annotation.
+
+        Parameters
+        ----------
+        result : list(bytes)
+            The result of the annotation that should be copied.
+
+        Returns
+        -------
+        AnnotationAudio
+            Newly created AnnotationAudio
+        """
+        return AnnotationAudio(self.annotatorType, result, self.metadata)
+
+    def __str__(self):
+        return "AnnotationAudio(%s, %s, %s)" % (
+            self.annotatorType,
+            str(self.result),
+            str(self.metadata)
+        )
+
+    def __repr__(self):
+        return self.__str__()

sparknlp/annotation_image.py

@@ -0,0 +1,82 @@
+#  Copyright 2017-2022 John Snow Labs
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+"""Contains the AnnotationImage data format
+"""
+
+
+class AnnotationImage:
+    """Represents the output of Spark NLP Annotators for image output and their details.
+
+    Parameters
+    ----------
+    annotator_type : str
+        The type of the output of the annotator. Possible values are ``IMAGE``.
+    origin: str
+        * Represents the source URI of the image
+    height : int
+        Image height in pixels
+    width : int
+        Image width in pixels
+    nChannels: int
+        Number of color channels
+    mode: int
+        OpenCV type
+    result : list(bytes)
+        Image data in bytes
+    metadata : dict
+        Associated metadata for this annotation
+    """
+
+    def __init__(self, annotatorType, origin, height, width, nChannels, mode, result, metadata):
+        self.annotatorType = annotatorType
+        self.origin = origin
+        self.height = height
+        self.width = width
+        self.nChannels = nChannels
+        self.mode = mode
+        self.result = result
+        self.metadata = metadata
+
+    def copy(self, result):
+        """Creates new AnnotationImage with a different result, containing all
+        settings of this Annotation.
+
+        Parameters
+        ----------
+        result : list(bytes)
+            The result of the annotation that should be copied.
+
+        Returns
+        -------
+        AnnotationImage
+            Newly created AnnotationImage
+        """
+        return AnnotationImage(self.annotatorType, self.origin, self.height, self.width,
+                               self.nChannels, self.mode, result, self.metadata)
+
+    def __str__(self):
+        return "AnnotationImage(%s, %s, %i, %i, %i, %i, %s, %s)" % (
+            self.annotatorType,
+            self.origin,
+            self.height,
+            self.width,
+            self.nChannels,
+            self.mode,
+            str(self.result),
+            str(self.metadata)
+        )
+
+    def __repr__(self):
+        return self.__str__()

sparknlp/annotator/__init__.py

@@ -0,0 +1,93 @@
+#  Copyright 2017-2022 John Snow Labs
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+"""Module containing all available Annotators of Spark NLP and their base
+classes.
+"""
+# New Annotators need to be imported here
+from sparknlp.annotator.classifier_dl import *
+from sparknlp.annotator.embeddings import *
+from sparknlp.annotator.er import *
+from sparknlp.annotator.keyword_extraction import *
+from sparknlp.annotator.ld_dl import *
+from sparknlp.annotator.matcher import *
+from sparknlp.annotator.ner import *
+from sparknlp.annotator.dependency import *
+from sparknlp.annotator.pos import *
+from sparknlp.annotator.sentence import *
+from sparknlp.annotator.sentiment import *
+from sparknlp.annotator.seq2seq import *
+from sparknlp.annotator.spell_check import *
+from sparknlp.annotator.token import *
+from sparknlp.annotator.ws import *
+from sparknlp.annotator.chunker import *
+from sparknlp.annotator.document_normalizer import *
+from sparknlp.annotator.graph_extraction import *
+from sparknlp.annotator.lemmatizer import *
+from sparknlp.annotator.n_gram_generator import *
+from sparknlp.annotator.normalizer import *
+from sparknlp.annotator.stemmer import *
+from sparknlp.annotator.stop_words_cleaner import *
+from sparknlp.annotator.coref import *
+from sparknlp.annotator.tf_ner_dl_graph_builder import *
+from sparknlp.annotator.cv import *
+from sparknlp.annotator.audio import *
+from sparknlp.annotator.chunk2_doc import *
+from sparknlp.annotator.date2_chunk import *
+from sparknlp.annotator.openai import *
+from sparknlp.annotator.token2_chunk import *
+from sparknlp.annotator.document_character_text_splitter import *
+from sparknlp.annotator.document_token_splitter import *
+
+if sys.version_info[0] == 2:
+    raise ImportError(
+        "Spark NLP only supports Python 3.6 and above. "
+        "Please use Python 3.6 or above that is compatible with both Spark NLP and PySpark"
+    )
+else:
+    __import__("com.johnsnowlabs.nlp")
+
+annotators = sys.modules[__name__]
+pos = sys.modules[__name__]
+pos.perceptron = sys.modules[__name__]
+ner = sys.modules[__name__]
+ner.crf = sys.modules[__name__]
+ner.dl = sys.modules[__name__]
+regex = sys.modules[__name__]
+sbd = sys.modules[__name__]
+sbd.pragmatic = sys.modules[__name__]
+sda = sys.modules[__name__]
+sda.pragmatic = sys.modules[__name__]
+sda.vivekn = sys.modules[__name__]
+spell = sys.modules[__name__]
+spell.norvig = sys.modules[__name__]
+spell.symmetric = sys.modules[__name__]
+spell.context = sys.modules[__name__]
+parser = sys.modules[__name__]
+parser.dep = sys.modules[__name__]
+parser.typdep = sys.modules[__name__]
+embeddings = sys.modules[__name__]
+classifier = sys.modules[__name__]
+classifier.dl = sys.modules[__name__]
+ld = sys.modules[__name__]
+ld.dl = sys.modules[__name__]
+keyword = sys.modules[__name__]
+keyword.yake = sys.modules[__name__]
+sentence_detector_dl = sys.modules[__name__]
+seq2seq = sys.modules[__name__]
+ws = sys.modules[__name__]
+er = sys.modules[__name__]
+coref = sys.modules[__name__]
+cv = sys.modules[__name__]
+audio = sys.modules[__name__]

sparknlp/annotator/audio/__init__.py

@@ -0,0 +1,16 @@
+#  Copyright 2017-2022 John Snow Labs
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+from sparknlp.annotator.audio.wav2vec2_for_ctc import *
+from sparknlp.annotator.audio.hubert_for_ctc import *
+from sparknlp.annotator.audio.whisper_for_ctc import *

sparknlp/annotator/audio/hubert_for_ctc.py

@@ -0,0 +1,188 @@
+#  Copyright 2017-2022 John Snow Labs
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+"""Contains classes concerning HubertForCTC."""
+
+from sparknlp.common import *
+
+
+class HubertForCTC(AnnotatorModel,
+                   HasBatchedAnnotateAudio,
+                   HasAudioFeatureProperties,
+                   HasEngine):
+    """Hubert Model with a language modeling head on top for Connectionist Temporal
+    Classification (CTC). Hubert was proposed in HuBERT: Self-Supervised Speech
+    Representation Learning by Masked Prediction of Hidden Units by Wei-Ning Hsu,
+    Benjamin Bolte, Yao-Hung Hubert Tsai, Kushal Lakhotia, Ruslan Salakhutdinov,
+    Abdelrahman Mohamed.
+
+    The annotator takes audio files and transcribes it as text. The audio needs to be
+    provided pre-processed an array of floats.
+
+    Note that this annotator is currently not supported on Apple Silicon processors such
+    as the M1. This is due to the processor not supporting instructions for XLA.
+
+    Pretrained models can be loaded with ``pretrained`` of the companion object:
+
+    >>> speechToText = HubertForCTC.pretrained() \\
+    ...     .setInputCols(["audio_assembler"]) \\
+    ...     .setOutputCol("text")
+
+
+    The default model is ``"asr_hubert_large_ls960"``, if no name is provided.
+
+    For available pretrained models please see the
+    `Models Hub <https://sparknlp.org/models>`__.
+
+    To see which models are compatible and how to import them see
+    https://github.com/JohnSnowLabs/spark-nlp/discussions/5669 and to see more extended
+    examples, see
+    `HubertForCTCTestSpec <https://github.com/JohnSnowLabs/spark-nlp/blob/master/src/test/scala/com/johnsnowlabs/nlp/annotators/audio/HubertForCTCTestSpec.scala>`__.
+
+    **Paper Abstract:**
+
+    *Self-supervised approaches for speech representation learning are challenged by
+    three unique problems: (1) there are multiple sound units in each input utterance,
+    (2) there is no lexicon of input sound units during the pre-training phase, and (3)
+    sound units have variable lengths with no explicit segmentation. To deal with these
+    three problems, we propose the Hidden-Unit BERT (HuBERT) approach for
+    self-supervised speech representation learning, which utilizes an offline clustering
+    step to provide aligned target labels for a BERT-like prediction loss. A key
+    ingredient of our approach is applying the prediction loss over the masked regions
+    only, which forces the model to learn a combined acoustic and language model over
+    the continuous inputs. HuBERT relies primarily on the consistency of the
+    unsupervised clustering step rather than the intrinsic quality of the assigned
+    cluster labels. Starting with a simple k-means teacher of 100 clusters, and using
+    two iterations of clustering, the HuBERT model either matches or improves upon the
+    state-of-the-art wav2vec 2.0 performance on the Librispeech (960h) and Libri-light
+    (60,000h) benchmarks with 10min, 1h, 10h, 100h, and 960h fine-tuning subsets. Using
+    a 1B parameter model, HuBERT shows up to 19% and 13% relative WER reduction on the
+    more challenging dev-other and test-other evaluation subsets.*
+
+    References
+    ----------
+
+    `HuBERT: Self-Supervised Speech Representation Learning by Masked Prediction of Hidden Units
+    <https://arxiv.org/abs/2106.07447>`__
+
+    ====================== ======================
+    Input Annotation types Output Annotation type
+    ====================== ======================
+    ``AUDIO``              ``DOCUMENT``
+    ====================== ======================
+
+    Parameters
+    ----------
+
+    batchSize
+        Size of each batch, by default 4
+
+    Examples
+    --------
+    >>> import sparknlp
+    >>> from sparknlp.base import *
+    >>> from sparknlp.annotator import *
+    >>> from pyspark.ml import Pipeline
+    >>> audioAssembler = AudioAssembler() \\
+    ...     .setInputCol("audio_content") \\
+    ...     .setOutputCol("audio_assembler")
+    >>> speechToText = HubertForCTC \\
+    ...     .pretrained() \\
+    ...     .setInputCols(["audio_assembler"]) \\
+    ...     .setOutputCol("text")
+    >>> pipeline = Pipeline().setStages([audioAssembler, speechToText])
+    >>> processedAudioFloats = spark.createDataFrame([[rawFloats]]).toDF("audio_content")
+    >>> result = pipeline.fit(processedAudioFloats).transform(processedAudioFloats)
+    >>> result.select("text.result").show(truncate = False)
+    +------------------------------------------------------------------------------------------+
+    |result                                                                                    |
+    +------------------------------------------------------------------------------------------+
+    |[MISTER QUILTER IS THE APOSTLE OF THE MIDLE CLASES AND WE ARE GLAD TO WELCOME HIS GOSPEL ]|
+    +------------------------------------------------------------------------------------------+
+    """
+    name = "HubertForCTC"
+
+    inputAnnotatorTypes = [AnnotatorType.AUDIO]
+
+    outputAnnotatorType = AnnotatorType.DOCUMENT
+
+    configProtoBytes = Param(Params._dummy(),
+                             "configProtoBytes",
+                             "ConfigProto from tensorflow, serialized into byte array. Get with "
+                             "config_proto.SerializeToString()",
+                             TypeConverters.toListInt)
+
+    def setConfigProtoBytes(self, b):
+        """Sets configProto from tensorflow, serialized into byte array.
+
+        Parameters
+        ----------
+        b : List[int]
+            ConfigProto from tensorflow, serialized into byte array
+        """
+        return self._set(configProtoBytes=b)
+
+    @keyword_only
+    def __init__(self, classname="com.johnsnowlabs.nlp.annotators.audio.HubertForCTC",
+                 java_model=None):
+        super(HubertForCTC, self).__init__(
+            classname=classname,
+            java_model=java_model
+        )
+        self._setDefault(
+            batchSize=4
+        )
+
+    @staticmethod
+    def loadSavedModel(folder, spark_session):
+        """Loads a locally saved model.
+
+        Parameters
+        ----------
+        folder : str
+            Folder of the saved model
+        spark_session : pyspark.sql.SparkSession
+            The current SparkSession
+
+        Returns
+        -------
+        HubertForCTC
+            The restored model
+        """
+        from sparknlp.internal import _HubertForCTC
+        jModel = _HubertForCTC(folder, spark_session._jsparkSession)._java_obj
+        return HubertForCTC(java_model=jModel)
+
+    @staticmethod
+    def pretrained(name="asr_hubert_large_ls960", lang="en", remote_loc=None):
+        """Downloads and loads a pretrained model.
+
+        Parameters
+        ----------
+        name : str, optional
+            Name of the pretrained model, by default
+            "asr_hubert_large_ls960"
+        lang : str, optional
+            Language of the pretrained model, by default "en"
+        remote_loc : str, optional
+            Optional remote address of the resource, by default None. Will use
+            Spark NLPs repositories otherwise.
+
+        Returns
+        -------
+        HubertForCTC
+            The restored model
+        """
+        from sparknlp.pretrained import ResourceDownloader
+        return ResourceDownloader.downloadModel(HubertForCTC, name, lang, remote_loc)