code: def make_reading_comprehension_instance(
      question_tokens,
      passage_tokens,
      token_indexers,
      passage_text,
      token_spans=None,
      answer_texts=None,
      additional_metadata=None,
  ):
      """
      Converts a question, a passage, and an optional answer (or answers) to an ``Instance`` for use
      in a reading comprehension model.
  
      Creates an ``Instance`` with at least these fields: ``question`` and ``passage``, both
      ``TextFields``; and ``metadata``, a ``MetadataField``.  Additionally, if both ``answer_texts``
      and ``char_span_starts`` are given, the ``Instance`` has ``span_start`` and ``span_end``
      fields, which are both ``IndexFields``.
  
      Parameters
      ----------
      question_tokens : ``List[Token]``
          An already-tokenized question.
      passage_tokens : ``List[Token]``
          An already-tokenized passage that contains the answer to the given question.
      token_indexers : ``Dict[str, TokenIndexer]``
          Determines how the question and passage ``TextFields`` will be converted into tensors that
          get input to a model.  See :class:`TokenIndexer`.
      passage_text : ``str``
          The original passage text.  We need this so that we can recover the actual span from the
          original passage that the model predicts as the answer to the question.  This is used in
          official evaluation scripts.
      token_spans : ``List[Tuple[int, int]]``, optional
          Indices into ``passage_tokens`` to use as the answer to the question for training.  This is
          a list because there might be several possible correct answer spans in the passage.
          Currently, we just select the most frequent span in this list (i.e., SQuAD has multiple
          annotations on the dev set; this will select the span that the most annotators gave as
          correct).
      answer_texts : ``List[str]``, optional
          All valid answer strings for the given question.  In SQuAD, e.g., the training set has
          exactly one answer per question, but the dev and test sets have several.  TriviaQA has many
          possible answers, which are the aliases for the known correct entity.  This is put into the
          metadata for use with official evaluation scripts, but not used anywhere else.
      additional_metadata : ``Dict[str, Any]``, optional
          The constructed ``metadata`` field will by default contain ``original_passage``,
          ``token_offsets``, ``question_tokens``, ``passage_tokens``, and ``answer_texts`` keys.  If
          you want any other metadata to be associated with each instance, you can pass that in here.
          This dictionary will get added to the ``metadata`` dictionary we already construct.
      """
      additional_metadata = additional_metadata or {}
      fields = {}
      passage_offsets = [
          (token.idx, token.idx + len(token.text))
          for token in passage_tokens
      ]
  
      # This is separate so we can reference it later with a known type.
      passage_field = TextField(passage_tokens, token_indexers)
      fields["passage"] = passage_field
      fields["question"] = TextField(question_tokens, token_indexers)
      metadata = {
          "original_passage": passage_text,
          "token_offsets": passage_offsets,
          "question_tokens": [token.text for token in question_tokens],
          "passage_tokens": [token.text for token in passage_tokens],
      }
      if answer_texts:
          metadata["answer_texts"] = answer_texts
  
      if token_spans:
          # There may be multiple answer annotations, so we pick the one that occurs the most.  This
          # only matters on the SQuAD dev set, and it means our computed metrics ("start_acc",
          # "end_acc", and "span_acc") aren't quite the same as the official metrics, which look at
          # all of the annotations.  This is why we have a separate official SQuAD metric calculation
          # (the "em" and "f1" metrics use the official script).
          candidate_answers = Counter()
          for span_start, span_end in token_spans:
              candidate_answers[(span_start, span_end)] += 1
          span_start, span_end = candidate_answers.most_common(1)[0][0]
  
          fields["span_start"] = IndexField(span_start, passage_field)
          fields["span_end"] = IndexField(span_end, passage_field)
  
      metadata.update(additional_metadata)
      fields["metadata"] = MetadataField(metadata)
      return Instance(fields)
  
file_path: magnitude/pymagnitude/third_party/allennlp/data/dataset_readers/reading_comprehension/util.py
imports: from __future__ import absolute_import
  from collections import Counter, defaultdict
  import logging
  import string
  from allennlp.data.fields import Field, TextField, IndexField, MetadataField
  from allennlp.data.instance import Instance
  from allennlp.data.token_indexers import TokenIndexer
  from allennlp.data.tokenizers import Token
label_desc: Use image node_id 4 for calling a global function with example usage: make_reading_comprehension_instance(question_tokens, passage_tokens, token_indexers, passage_text, token_spans, answer_texts, additional_metadata) and returns: Instance