class_docstr: This ``SpanConstituencyParser`` simply encodes a sequence of text
  with a stacked ``Seq2SeqEncoder``, extracts span representations using a
  ``SpanExtractor``, and then predicts a label for each span in the sequence.
  These labels are non-terminal nodes in a constituency parse tree, which we then
  greedily reconstruct.
  
  Parameters
  ----------
  vocab : ``Vocabulary``, required
      A Vocabulary, required in order to compute sizes for input/output projections.
  text_field_embedder : ``TextFieldEmbedder``, required
      Used to embed the ``tokens`` ``TextField`` we get as input to the model.
  span_extractor : ``SpanExtractor``, required.
      The method used to extract the spans from the encoded sequence.
  encoder : ``Seq2SeqEncoder``, required.
      The encoder that we will use in between embedding tokens and
      generating span representations.
  feedforward : ``FeedForward``, required.
      The FeedForward layer that we will use in between the encoder and the linear
      projection to a distribution over span labels.
  pos_tag_embedding : ``Embedding``, optional.
      Used to embed the ``pos_tags`` ``SequenceLabelField`` we get as input to the model.
  initializer : ``InitializerApplicator``, optional (default=``InitializerApplicator()``)
      Used to initialize the model parameters.
  regularizer : ``RegularizerApplicator``, optional (default=``None``)
      If provided, will be used to calculate the regularization penalty during training.
  evalb_directory_path : ``str``, optional (default=``DEFAULT_EVALB_DIR``)
      The path to the directory containing the EVALB executable used to score
      bracketed parses. By default, will use the EVALB included with allennlp,
      which is located at allennlp/tools/EVALB . If ``None``, EVALB scoring
      is not used.
class_docstr_tok: ["This","``","SpanConstituencyParser","``","simply","encodes","a","sequence","of","text","with","a","stacked","``","Seq2SeqEncoder","``",",","extracts","span","representations","using","a","``","SpanExtractor","``",",","and","then","predicts","a","label","for","each","span","in","the","sequence",".","These","labels","are","non-terminal","nodes","in","a","constituency","parse","tree",",","which","we","then","greedily","reconstruct",".","Parameters","--","--","--","--","--","vocab",":","``","Vocabulary","``",",","required","A","Vocabulary",",","required","in","order","to","compute","sizes","for","input\/output","projections",".","text_field_embedder",":","``","TextFieldEmbedder","``",",","required","Used","to","embed","the","``","tokens","``","``","TextField","``","we","get","as","input","to","the","model",".","span_extractor",":","``","SpanExtractor","``",",","required",".","The","method","used","to","extract","the","spans","from","the","encoded","sequence",".","encoder",":","``","Seq2SeqEncoder","``",",","required",".","The","encoder","that","we","will","use","in","between","embedding","tokens","and","generating","span","representations",".","feedforward",":","``","FeedForward","``",",","required",".","The","FeedForward","layer","that","we","will","use","in","between","the","encoder","and","the","linear","projection","to","a","distribution","over","span","labels",".","pos_tag_embedding",":","``","Embedding","``",",","optional",".","Used","to","embed","the","``","pos_tags","``","``","SequenceLabelField","``","we","get","as","input","to","the","model",".","initializer",":","``","InitializerApplicator","``",",","optional","(","default=","``","InitializerApplicator","(",")","``",")","Used","to","initialize","the","model","parameters",".","regularizer",":","``","RegularizerApplicator","``",",","optional","(","default=","``","None","``",")","If","provided",",","will","be","used","to","calculate","the","regularization","penalty","during","training",".","evalb_directory_path",":","``","str","``",",","optional","(","default=","``","DEFAULT_EVALB_DIR","``",")","The","path","to","the","directory","containing","the","EVALB","executable","used","to","score","bracketed","parses",".","By","default",",","will","use","the","EVALB","included","with","allennlp",",","which","is","located","at","allennlp\/tools\/EVALB",".","If","``","None","``",",","EVALB","scoring","is","not","used","."]
docstr: Parameters
  ----------
  tokens : Dict[str, torch.LongTensor], required
      The output of ``TextField.as_array()``, which should typically be passed directly to a
      ``TextFieldEmbedder``. This output is a dictionary mapping keys to ``TokenIndexer``
      tensors.  At its most basic, using a ``SingleIdTokenIndexer`` this is: ``{"tokens":
      Tensor(batch_size, num_tokens)}``. This dictionary will have the same keys as were used
      for the ``TokenIndexers`` when you created the ``TextField`` representing your
      sequence.  The dictionary is designed to be passed directly to a ``TextFieldEmbedder``,
      which knows how to combine different word representations into a single vector per
      token in your input.
  spans : ``torch.LongTensor``, required.
      A tensor of shape ``(batch_size, num_spans, 2)`` representing the
      inclusive start and end indices of all possible spans in the sentence.
  metadata : List[Dict[str, Any]], required.
      A dictionary of metadata for each batch element which has keys:
          tokens : ``List[str]``, required.
              The original string tokens in the sentence.
          gold_tree : ``nltk.Tree``, optional (default = None)
              Gold NLTK trees for use in evaluation.
          pos_tags : ``List[str]``, optional.
              The POS tags for the sentence. These can be used in the
              model as embedded features, but they are passed here
              in addition for use in constructing the tree.
  pos_tags : ``torch.LongTensor``, optional (default = None)
      The output of a ``SequenceLabelField`` containing POS tags.
  span_labels : ``torch.LongTensor``, optional (default = None)
      A torch tensor representing the integer gold class labels for all possible
      spans, of shape ``(batch_size, num_spans)``.
  
  Returns
  -------
  An output dictionary consisting of:
  class_probabilities : ``torch.FloatTensor``
      A tensor of shape ``(batch_size, num_spans, span_label_vocab_size)``
      representing a distribution over the label classes per span.
  spans : ``torch.LongTensor``
      The original spans tensor.
  tokens : ``List[List[str]]``, required.
      A list of tokens in the sentence for each element in the batch.
  pos_tags : ``List[List[str]]``, required.
      A list of POS tags in the sentence for each element in the batch.
  num_spans : ``torch.LongTensor``, required.
      A tensor of shape (batch_size), representing the lengths of non-padded spans
      in ``enumerated_spans``.
  loss : ``torch.FloatTensor``, optional
      A scalar loss to be optimised.
docstr_tok: ["Parameters","--","--","--","--","--","tokens",":","Dict","[","str",",","torch.LongTensor","]",",","required","The","output","of","``","TextField.as_array","(",")","``",",","which","should","typically","be","passed","directly","to","a","``","TextFieldEmbedder","``",".","This","output","is","a","dictionary","mapping","keys","to","``","TokenIndexer","``","tensors",".","At","its","most","basic",",","using","a","``","SingleIdTokenIndexer","``","this","is",":","``","{","``","tokens","''",":","Tensor","(","batch_size",",","num_tokens",")","}","``",".","This","dictionary","will","have","the","same","keys","as","were","used","for","the","``","TokenIndexers","``","when","you","created","the","``","TextField","``","representing","your","sequence",".","The","dictionary","is","designed","to","be","passed","directly","to","a","``","TextFieldEmbedder","``",",","which","knows","how","to","combine","different","word","representations","into","a","single","vector","per","token","in","your","input",".","spans",":","``","torch.LongTensor","``",",","required",".","A","tensor","of","shape","``","(","batch_size",",","num_spans",",","2",")","``","representing","the","inclusive","start","and","end","indices","of","all","possible","spans","in","the","sentence",".","metadata",":","List","[","Dict","[","str",",","Any","]","]",",","required",".","A","dictionary","of","metadata","for","each","batch","element","which","has","keys",":","tokens",":","``","List","[","str","]","``",",","required",".","The","original","string","tokens","in","the","sentence",".","gold_tree",":","``","nltk.Tree","``",",","optional","(","default","=","None",")","Gold","NLTK","trees","for","use","in","evaluation",".","pos_tags",":","``","List","[","str","]","``",",","optional",".","The","POS","tags","for","the","sentence",".","These","can","be","used","in","the","model","as","embedded","features",",","but","they","are","passed","here","in","addition","for","use","in","constructing","the","tree",".","pos_tags",":","``","torch.LongTensor","``",",","optional","(","default","=","None",")","The","output","of","a","``","SequenceLabelField","``","containing","POS","tags",".","span_labels",":","``","torch.LongTensor","``",",","optional","(","default","=","None",")","A","torch","tensor","representing","the","integer","gold","class","labels","for","all","possible","spans",",","of","shape","``","(","batch_size",",","num_spans",")","``",".","Returns","--","--","--","-","An","output","dictionary","consisting","of",":","class_probabilities",":","``","torch.FloatTensor","``","A","tensor","of","shape","``","(","batch_size",",","num_spans",",","span_label_vocab_size",")","``","representing","a","distribution","over","the","label","classes","per","span",".","spans",":","``","torch.LongTensor","``","The","original","spans","tensor",".","tokens",":","``","List","[","List","[","str","]","]","``",",","required",".","A","list","of","tokens","in","the","sentence","for","each","element","in","the","batch",".","pos_tags",":","``","List","[","List","[","str","]","]","``",",","required",".","A","list","of","POS","tags","in","the","sentence","for","each","element","in","the","batch",".","num_spans",":","``","torch.LongTensor","``",",","required",".","A","tensor","of","shape","(","batch_size",")",",","representing","the","lengths","of","non-padded","spans","in","``","enumerated_spans","``",".","loss",":","``","torch.FloatTensor","``",",","optional","A","scalar","loss","to","be","optimised","."]
code: def forward(
      self,  # type: ignore
      tokens,
      spans,
      metadata,
      pos_tags=None,
      span_labels=None,
  ):
      # pylint: disable=arguments-differ
      """
      Parameters
      ----------
      tokens : Dict[str, torch.LongTensor], required
          The output of ``TextField.as_array()``, which should typically be passed directly to a
          ``TextFieldEmbedder``. This output is a dictionary mapping keys to ``TokenIndexer``
          tensors.  At its most basic, using a ``SingleIdTokenIndexer`` this is: ``{"tokens":
          Tensor(batch_size, num_tokens)}``. This dictionary will have the same keys as were used
          for the ``TokenIndexers`` when you created the ``TextField`` representing your
          sequence.  The dictionary is designed to be passed directly to a ``TextFieldEmbedder``,
          which knows how to combine different word representations into a single vector per
          token in your input.
      spans : ``torch.LongTensor``, required.
          A tensor of shape ``(batch_size, num_spans, 2)`` representing the
          inclusive start and end indices of all possible spans in the sentence.
      metadata : List[Dict[str, Any]], required.
          A dictionary of metadata for each batch element which has keys:
              tokens : ``List[str]``, required.
                  The original string tokens in the sentence.
              gold_tree : ``nltk.Tree``, optional (default = None)
                  Gold NLTK trees for use in evaluation.
              pos_tags : ``List[str]``, optional.
                  The POS tags for the sentence. These can be used in the
                  model as embedded features, but they are passed here
                  in addition for use in constructing the tree.
      pos_tags : ``torch.LongTensor``, optional (default = None)
          The output of a ``SequenceLabelField`` containing POS tags.
      span_labels : ``torch.LongTensor``, optional (default = None)
          A torch tensor representing the integer gold class labels for all possible
          spans, of shape ``(batch_size, num_spans)``.
  
      Returns
      -------
      An output dictionary consisting of:
      class_probabilities : ``torch.FloatTensor``
          A tensor of shape ``(batch_size, num_spans, span_label_vocab_size)``
          representing a distribution over the label classes per span.
      spans : ``torch.LongTensor``
          The original spans tensor.
      tokens : ``List[List[str]]``, required.
          A list of tokens in the sentence for each element in the batch.
      pos_tags : ``List[List[str]]``, required.
          A list of POS tags in the sentence for each element in the batch.
      num_spans : ``torch.LongTensor``, required.
          A tensor of shape (batch_size), representing the lengths of non-padded spans
          in ``enumerated_spans``.
      loss : ``torch.FloatTensor``, optional
          A scalar loss to be optimised.
      """
      embedded_text_input = self.text_field_embedder(tokens)
      if pos_tags is not None and self.pos_tag_embedding is not None:
          embedded_pos_tags = self.pos_tag_embedding(pos_tags)
          embedded_text_input = torch.cat(
              [embedded_text_input, embedded_pos_tags], -1
          )
      elif self.pos_tag_embedding is not None:
          raise ConfigurationError(
              "Model uses a POS embedding, but no POS tags were passed."
          )
  
      mask = get_text_field_mask(tokens)
      # Looking at the span start index is enough to know if
      # this is padding or not. Shape: (batch_size, num_spans)
      span_mask = (spans[:, :, 0] >= 0).squeeze(-1).long()
      if span_mask.dim() == 1:
          # This happens if you use batch_size 1 and encounter
          # a length 1 sentence in PTB, which do exist. -.-
          span_mask = span_mask.unsqueeze(-1)
      if span_labels is not None and span_labels.dim() == 1:
          span_labels = span_labels.unsqueeze(-1)
  
      num_spans = get_lengths_from_binary_sequence_mask(span_mask)
  
      encoded_text = self.encoder(embedded_text_input, mask)
  
      span_representations = self.span_extractor(
          encoded_text, spans, mask, span_mask
      )
  
      if self.feedforward_layer is not None:
          span_representations = self.feedforward_layer(
              span_representations
          )
  
      logits = self.tag_projection_layer(span_representations)
      class_probabilities = last_dim_softmax(
          logits, span_mask.unsqueeze(-1)
      )
  
      output_dict = {
          "class_probabilities": class_probabilities,
          "spans": spans,
          "tokens": [meta["tokens"] for meta in metadata],
          "pos_tags": [meta.get("pos_tags") for meta in metadata],
          "num_spans": num_spans,
      }
      if span_labels is not None:
          loss = sequence_cross_entropy_with_logits(
              logits, span_labels, span_mask
          )
          self.tag_accuracy(class_probabilities, span_labels, span_mask)
          output_dict["loss"] = loss
  
      # The evalb score is expensive to compute, so we only compute
      # it for the validation and test sets.
      batch_gold_trees = [meta.get("gold_tree") for meta in metadata]
      if (
          all(batch_gold_trees)
          and self._evalb_score is not None
          and not self.training
      ):
          gold_pos_tags = [
              list(izip(*tree.pos()))[1] for tree in batch_gold_trees
          ]
          predicted_trees = self.construct_trees(
              class_probabilities.cpu().data,
              spans.cpu().data,
              num_spans.data,
              output_dict["tokens"],
              gold_pos_tags,
          )
          self._evalb_score(predicted_trees, batch_gold_trees)
  
      return output_dict
  
imports: from __future__ import absolute_import
  import torch
  from torch.nn.modules.linear import Linear
  from nltk import Tree
  from allennlp.common.checks import check_dimensions_match
  from allennlp.data import Vocabulary
  from allennlp.modules import Seq2SeqEncoder, TimeDistributed, TextFieldEmbedder, FeedForward
  from allennlp.modules.token_embedders import Embedding
  from allennlp.modules.span_extractors.span_extractor import SpanExtractor
  from allennlp.models.model import Model
  from allennlp.nn import InitializerApplicator, RegularizerApplicator
  from allennlp.nn.util import get_text_field_mask, sequence_cross_entropy_with_logits
  from allennlp.nn.util import last_dim_softmax, get_lengths_from_binary_sequence_mask
  from allennlp.training.metrics import CategoricalAccuracy
  from allennlp.training.metrics import EvalbBracketingScorer, DEFAULT_EVALB_DIR
  from allennlp.common.checks import ConfigurationError
label_desc: Use image node_id 2 for calling the SpanConstituencyParser obj's underlying member method code with example usage: obj.forward(tokens, spans, metadata, pos_tags, span_labels) and returns: output_dict