class_docstr: An ordered collection of :class:`spacy.tokens.Doc`, all of the same language
  and sharing the same :class:`spacy.language.Language` processing pipeline
  and vocabulary, with data held *in-memory*.
  
  Initialize from a ``Language`` name or instance and (optionally) one or a stream
  of texts or (text, metadata) pairs:
  
  .. code-block:: pycon
  
      >>> ds = textacy.datasets.CapitolWords()
      >>> records = ds.records(limit=50)
      >>> corpus = textacy.Corpus("en_core_web_sm", data=records)
      >>> print(corpus)
      Corpus(50 docs, 32175 tokens)
  
  Add or remove documents, with automatic updating of corpus statistics:
  
  .. code-block:: pycon
  
      >>> texts = ds.texts(congress=114, limit=25)
      >>> corpus.add(texts)
      >>> corpus.add("If Burton were a member of Congress, here's what he'd say.")
      >>> print(corpus)
      Corpus(76 docs, 55906 tokens)
      >>> corpus.remove(lambda doc: doc._.meta.get("speaker_name") == "Rick Santorum")
      >>> print(corpus)
      Corpus(61 docs, 48567 tokens)
  
  Get subsets of documents matching your particular use case:
  
  .. code-block:: pycon
  
      >>> match_func = lambda doc: doc._.meta.get("speaker_name") == "Bernie Sanders"
      >>> for doc in corpus.get(match_func, limit=3):
      ...     print(doc._.preview)
      Doc(159 tokens: "Mr. Speaker, 480,000 Federal employees are work...")
      Doc(336 tokens: "Mr. Speaker, I thank the gentleman for yielding...")
      Doc(177 tokens: "Mr. Speaker, if we want to understand why in th...")
  
  Get or remove documents by indexing, too:
  
  .. code-block:: pycon
  
      >>> corpus[0]._.preview
      'Doc(159 tokens: "Mr. Speaker, 480,000 Federal employees are work...")'
      >>> [doc._.preview for doc in corpus[:3]]
      ['Doc(159 tokens: "Mr. Speaker, 480,000 Federal employees are work...")',
       'Doc(219 tokens: "Mr. Speaker, a relationship, to work and surviv...")',
       'Doc(336 tokens: "Mr. Speaker, I thank the gentleman for yielding...")']
      >>> del corpus[:5]
      >>> print(corpus)
      Corpus(56 docs, 41573 tokens)
  
  Compute basic corpus statistics:
  
  .. code-block:: pycon
  
      >>> corpus.n_docs, corpus.n_sents, corpus.n_tokens
      (56, 1771, 41573)
      >>> word_counts = corpus.word_counts(by="lemma_")
      >>> sorted(word_counts.items(), key=lambda x: x[1], reverse=True)[:5]
      [('-PRON-', 2553), ('people', 215), ('year', 148), ('Mr.', 139), ('$', 137)]
      >>> word_doc_counts = corpus.word_doc_counts(by="lemma_", weighting="freq")
      >>> sorted(word_doc_counts.items(), key=lambda x: x[1], reverse=True)[:5]
      [('-PRON-', 0.9821428571428571),
       ('Mr.', 0.7678571428571429),
       ('President', 0.5),
       ('people', 0.48214285714285715),
       ('need', 0.44642857142857145)]
  
  Save corpus data to and load from disk:
  
  .. code-block:: pycon
  
      >>> corpus.save("./cw_sample.bin.gz")
      >>> corpus = textacy.Corpus.load("en_core_web_sm", "./cw_sample.bin.gz")
      >>> print(corpus)
      Corpus(56 docs, 41573 tokens)
  
  Args:
      lang:
          Language with which spaCy processes (or processed) all documents
          added to the corpus, whether as ``data`` now or later.
  
          Pass the name of a spacy language pipeline (e.g. "en_core_web_sm"),
          or an already-instantiated :class:`spacy.language.Language` object.
  
          A given / detected language string is then used to instantiate
          a corresponding ``Language`` with all default components enabled.
      data: One or a stream of texts, records, or :class:`spacy.tokens.Doc` s
          to be added to the corpus.
  
          .. seealso:: :meth:`Corpus.add()`
  
  Attributes:
      lang
      spacy_lang
      docs
      n_docs
      n_sents
      n_tokens
class_docstr_tok: ["An","ordered","collection","of",":","class",":","`","spacy.tokens.Doc","`",",","all","of","the","same","language","and","sharing","the","same",":","class",":","`","spacy.language.Language","`","processing","pipeline","and","vocabulary",",","with","data","held","*","in-memory","*",".","Initialize","from","a","``","Language","``","name","or","instance","and","(","optionally",")","one","or","a","stream","of","texts","or","(","text",",","metadata",")","pairs",":","..","code-block",":",":","pycon",">",">",">","ds","=","textacy.datasets.CapitolWords","(",")",">",">",">","records","=","ds.records","(","limit=50",")",">",">",">","corpus","=","textacy.Corpus","(","``","en_core_web_sm","''",",","data=records",")",">",">",">","print","(","corpus",")","Corpus","(","50","docs",",","32175","tokens",")","Add","or","remove","documents",",","with","automatic","updating","of","corpus","statistics",":","..","code-block",":",":","pycon",">",">",">","texts","=","ds.texts","(","congress=114",",","limit=25",")",">",">",">","corpus.add","(","texts",")",">",">",">","corpus.add","(","``","If","Burton","were","a","member","of","Congress",",","here","'s","what","he","'d","say",".","''",")",">",">",">","print","(","corpus",")","Corpus","(","76","docs",",","55906","tokens",")",">",">",">","corpus.remove","(","lambda","doc",":","doc._.meta.get","(","``","speaker_name","''",")","==","``","Rick","Santorum","''",")",">",">",">","print","(","corpus",")","Corpus","(","61","docs",",","48567","tokens",")","Get","subsets","of","documents","matching","your","particular","use","case",":","..","code-block",":",":","pycon",">",">",">","match_func","=","lambda","doc",":","doc._.meta.get","(","``","speaker_name","''",")","==","``","Bernie","Sanders","''",">",">",">","for","doc","in","corpus.get","(","match_func",",","limit=3",")",":","...","print","(","doc._.preview",")","Doc","(","159","tokens",":","``","Mr.","Speaker",",","480,000","Federal","employees","are","work","...","''",")","Doc","(","336","tokens",":","``","Mr.","Speaker",",","I","thank","the","gentleman","for","yielding","...","''",")","Doc","(","177","tokens",":","``","Mr.","Speaker",",","if","we","want","to","understand","why","in","th","...","''",")","Get","or","remove","documents","by","indexing",",","too",":","..","code-block",":",":","pycon",">",">",">","corpus","[","0","]","._.preview","'Doc","(","159","tokens",":","``","Mr.","Speaker",",","480,000","Federal","employees","are","work","...","''",")","'",">",">",">","[","doc._.preview","for","doc","in","corpus","[",":3","]","]","[","'Doc","(","159","tokens",":","``","Mr.","Speaker",",","480,000","Federal","employees","are","work","...","''",")","'",",","'Doc","(","219","tokens",":","``","Mr.","Speaker",",","a","relationship",",","to","work","and","surviv","...","''",")","'",",","'Doc","(","336","tokens",":","``","Mr.","Speaker",",","I","thank","the","gentleman","for","yielding","...","''",")","'","]",">",">",">","del","corpus","[",":5","]",">",">",">","print","(","corpus",")","Corpus","(","56","docs",",","41573","tokens",")","Compute","basic","corpus","statistics",":","..","code-block",":",":","pycon",">",">",">","corpus.n_docs",",","corpus.n_sents",",","corpus.n_tokens","(","56",",","1771",",","41573",")",">",">",">","word_counts","=","corpus.word_counts","(","by=","''","lemma_","''",")",">",">",">","sorted","(","word_counts.items","(",")",",","key=lambda","x",":","x","[","1","]",",","reverse=True",")","[",":5","]","[","(","'-PRON-","'",",","2553",")",",","(","'people","'",",","215",")",",","(","'year","'",",","148",")",",","(","'Mr",".","'",",","139",")",",","(","'","$","'",",","137",")","]",">",">",">","word_doc_counts","=","corpus.word_doc_counts","(","by=","''","lemma_","''",",","weighting=","''","freq","''",")",">",">",">","sorted","(","word_doc_counts.items","(",")",",","key=lambda","x",":","x","[","1","]",",","reverse=True",")","[",":5","]","[","(","'-PRON-","'",",","0.9821428571428571",")",",","(","'Mr",".","'",",","0.7678571428571429",")",",","(","'President","'",",","0.5",")",",","(","'people","'",",","0.48214285714285715",")",",","(","'need","'",",","0.44642857142857145",")","]","Save","corpus","data","to","and","load","from","disk",":","..","code-block",":",":","pycon",">",">",">","corpus.save","(","``",".\/cw_sample.bin.gz","''",")",">",">",">","corpus","=","textacy.Corpus.load","(","``","en_core_web_sm","''",",","``",".\/cw_sample.bin.gz","''",")",">",">",">","print","(","corpus",")","Corpus","(","56","docs",",","41573","tokens",")","Args",":","lang",":","Language","with","which","spaCy","processes","(","or","processed",")","all","documents","added","to","the","corpus",",","whether","as","``","data","``","now","or","later",".","Pass","the","name","of","a","spacy","language","pipeline","(","e.g",".","``","en_core_web_sm","''",")",",","or","an","already-instantiated",":","class",":","`","spacy.language.Language","`","object",".","A","given","\/","detected","language","string","is","then","used","to","instantiate","a","corresponding","``","Language","``","with","all","default","components","enabled",".","data",":","One","or","a","stream","of","texts",",","records",",","or",":","class",":","`","spacy.tokens.Doc","`","s","to","be","added","to","the","corpus",".","..","seealso",":",":",":","meth",":","`","Corpus.add","(",")","`","Attributes",":","lang","spacy_lang","docs","n_docs","n_sents","n_tokens"]
docstr: Map the set of unique words in :class:`Corpus` to their *document* counts
  as absolute, relative, or inverse frequencies of occurence.
  
  Args:
      by: Attribute by which spaCy ``Token`` s are grouped before counting,
          as given by ``getattr(token, by)``.
          If "lemma", tokens are grouped by their base form w/o inflections;
          if "lower", by the lowercase form of the token text;
          if "norm", by the normalized form of the token text;
          if "orth", by the token text exactly as it appears in documents.
          To output keys as strings, append an underscore to any of these options;
          for example, "lemma_" groups tokens by their lemmas as strings.
      weighting: Type of weighting to assign to unique words given by ``by``.
          If "count", weights are the absolute number of occurrences (i.e. counts);
          if "freq", weights are counts normalized by the total token count,
          giving their relative frequency of occurrence;
          if "idf", weights are the log of the inverse relative frequencies, i.e.
          ``log(n_docs / word_doc_count)`` or, if ``smooth_idf`` is True,
          ``log(1 + (n_docs / word_doc_count))``.
      smooth_idf: If True, add 1 to all word doc counts when
          calculating "idf" weighting, equivalent to adding a single
          document to the corpus containing every unique word.
  
  Returns:
      Mapping of a unique word id or string (depending on the value of ``by``)
      to the number of documents in which it appears,
      weighted as absolute, relative, or inverse frequency of occurrence
      (depending on the value of ``weighting``).
  
  See Also:
      :func:`textacy.vsm.get_doc_freqs() <textacy.vsm.matrix_utils.get_doc_freqs>`
code: def word_doc_counts(
      self,
      *,
      by: Literal[
          "lemma",
          "lower",
          "norm",
          "orth",
          "lemma_",
          "lower_",
          "norm_",
          "orth_",
      ] = "lemma",
      weighting: Literal["count", "freq", "idf"] = "count",
      smooth_idf: bool = True,
      **kwargs,
  ) -> dict[int, int | float] | dict[str, int | float]:
      """
      Map the set of unique words in :class:`Corpus` to their *document* counts
      as absolute, relative, or inverse frequencies of occurence.
  
      Args:
          by: Attribute by which spaCy ``Token`` s are grouped before counting,
              as given by ``getattr(token, by)``.
              If "lemma", tokens are grouped by their base form w/o inflections;
              if "lower", by the lowercase form of the token text;
              if "norm", by the normalized form of the token text;
              if "orth", by the token text exactly as it appears in documents.
              To output keys as strings, append an underscore to any of these options;
              for example, "lemma_" groups tokens by their lemmas as strings.
          weighting: Type of weighting to assign to unique words given by ``by``.
              If "count", weights are the absolute number of occurrences (i.e. counts);
              if "freq", weights are counts normalized by the total token count,
              giving their relative frequency of occurrence;
              if "idf", weights are the log of the inverse relative frequencies, i.e.
              ``log(n_docs / word_doc_count)`` or, if ``smooth_idf`` is True,
              ``log(1 + (n_docs / word_doc_count))``.
          smooth_idf: If True, add 1 to all word doc counts when
              calculating "idf" weighting, equivalent to adding a single
              document to the corpus containing every unique word.
  
      Returns:
          Mapping of a unique word id or string (depending on the value of ``by``)
          to the number of documents in which it appears,
          weighted as absolute, relative, or inverse frequency of occurrence
          (depending on the value of ``weighting``).
  
      See Also:
          :func:`textacy.vsm.get_doc_freqs() <textacy.vsm.matrix_utils.get_doc_freqs>`
      """
      word_doc_counts_: Union[
          Counter[Any], dict[Any, Union[int, float]]
      ]
      word_doc_counts_ = collections.Counter()
      for doc in self.docs:
          word_doc_counts_.update(
              extract.to_bag_of_words(
                  doc, by=by, weighting="binary", **kwargs
              )
          )
      if weighting == "count":
          word_doc_counts_ = dict(word_doc_counts_)
      elif weighting == "freq":
          n_docs = self.n_docs
          word_doc_counts_ = {
              word: count / n_docs
              for word, count in word_doc_counts_.items()
          }
      elif weighting == "idf":
          n_docs = self.n_docs
          if smooth_idf is True:
              word_doc_counts_ = {
                  word: math.log1p(n_docs / count)
                  for word, count in word_doc_counts_.items()
              }
          else:
              word_doc_counts_ = {
                  word: math.log(n_docs / count)
                  for word, count in word_doc_counts_.items()
              }
      else:
          raise ValueError(
              errors.value_invalid_msg(
                  "weighting", weighting, {"count", "freq", "idf"}
              )
          )
      return word_doc_counts_
  
imports: from __future__ import annotations
  import collections
  import collections.abc
  import itertools
  import logging
  import math
  from typing import Any, Callable, Counter, Iterable, Literal, Optional, Union
  import numpy
  import spacy
  import spacy.attrs
  from cytoolz import itertoolz
  from spacy.language import Language
  from spacy.tokens import Doc
  from .None import errors, extract
  from .None import io
  from .None import spacier, types, utils
label_desc: Use image node_id 23 for calling the Corpus obj's underlying member method code with example usage: obj.word_doc_counts() and returns: word_doc_counts_