class_docstr: Transform one or more tokenized documents into a group-term matrix of
  shape (# groups, # unique terms), with tf-, tf-idf, or binary-weighted values.
  
  This is an extension of typical document-term matrix vectorization, where
  terms are grouped by the documents in which they co-occur. It allows for
  customized grouping, such as by a shared author or publication year, that
  may span multiple documents, without forcing users to merge those documents
  themselves.
  
  Stream a corpus with metadata from disk::
  
      >>> ds = textacy.datasets.CapitolWords()
      >>> records = ds.records(limit=1000)
      >>> corpus = textacy.Corpus("en_core_web_sm", data=records)
      >>> corpus
      Corpus(1000 docs, 538397 tokens)
  
  Tokenize and vectorize the first 600 documents of this corpus, where terms
  are grouped not by documents but by a categorical value in the docs' metadata::
  
      >>> tokenized_docs, groups = textacy.io.unzip(
      ...     ((term.lemma_ for term in textacy.extract.terms(doc, ngs=1, ents=True)),
      ...      doc._.meta["speaker_name"])
      ...     for doc in corpus[:600])
      >>> vectorizer = GroupVectorizer(
      ...     tf_type="linear", idf_type="smooth", norm="l2",
      ...     min_df=3, max_df=0.95)
      >>> grp_term_matrix = vectorizer.fit_transform(tokenized_docs, groups)
      >>> grp_term_matrix
      <5x1822 sparse matrix of type '<class 'numpy.float64'>'
              with 6139 stored elements in Compressed Sparse Row format>
  
  Tokenize and vectorize the remaining 400 documents of the corpus, using only
  the groups, terms, and weights learned in the previous step::
  
      >>> tokenized_docs, groups = textacy.io.unzip(
      ...     ((term.lemma_ for term in textacy.extract.terms(doc, ngs=1, ents=True)),
      ...      doc._.meta["speaker_name"])
      ...     for doc in corpus[600:])
      >>> grp_term_matrix = vectorizer.transform(tokenized_docs, groups)
      >>> grp_term_matrix
      <5x1822 sparse matrix of type '<class 'numpy.float64'>'
              with 4414 stored elements in Compressed Sparse Row format>
  
  Inspect the terms associated with columns and groups associated with rows;
  they're sorted alphabetically::
  
      >>> vectorizer.terms_list[:5]
      ['', '$ 1 million', '$ 160 million', '$ 5 billion', '$ 7 billion']
      >>> vectorizer.grps_list
      ['Bernie Sanders', 'John Kasich', 'Joseph Biden', 'Lindsey Graham', 'Rick Santorum']
  
  If known in advance, limit the terms and/or groups included in vectorized outputs
  to a particular set of values::
  
      >>> tokenized_docs, groups = textacy.io.unzip(
      ...     ((term.lemma_ for term in textacy.extract.terms(doc, ngs=1, ents=True)),
      ...      doc._.meta["speaker_name"])
      ...     for doc in corpus[:600])
      >>> vectorizer = GroupVectorizer(
      ...     tf_type="linear", idf_type="smooth", norm="l2",
      ...     min_df=3, max_df=0.95,
      ...     vocabulary_terms=["legislation", "federal government", "house", "constitutional"],
      ...     vocabulary_grps=["Bernie Sanders", "Lindsey Graham", "Rick Santorum"])
      >>> grp_term_matrix = vectorizer.fit_transform(tokenized_docs, groups)
      >>> grp_term_matrix
      <3x4 sparse matrix of type '<class 'numpy.float64'>'
              with 9 stored elements in Compressed Sparse Row format>
      >>> vectorizer.terms_list
      ['constitutional', 'federal government', 'house', 'legislation']
      >>> vectorizer.grps_list
      ['Bernie Sanders', 'Lindsey Graham', 'Rick Santorum']
  
  For a discussion of the various weighting schemes that can be applied, check
  out the :class:`Vectorizer` docstring.
  
  Args:
      tf_type: Type of term frequency (tf) to use for weights' local component:
  
          - "linear": tf (tfs are already linear, so left as-is)
          - "sqrt": tf => sqrt(tf)
          - "log": tf => log(tf) + 1
          - "binary": tf => 1
  
      idf_type: Type of inverse document frequency (idf) to use for weights'
          global component:
  
          - "standard": idf = log(n_docs / df) + 1.0
          - "smooth": idf = log(n_docs + 1 / df + 1) + 1.0, i.e. 1 is added
            to all document frequencies, as if a single document containing
            every unique term was added to the corpus.
          - "bm25": idf = log((n_docs - df + 0.5) / (df + 0.5)), which is
            a form commonly used in information retrieval that allows for
            very common terms to receive negative weights.
          - None: no global weighting is applied to local term weights.
  
      dl_type: Type of document-length scaling to use for weights'
          normalization component:
  
          - "linear": dl (dls are already linear, so left as-is)
          - "sqrt": dl => sqrt(dl)
          - "log": dl => log(dl)
          - None: no normalization is applied to local (+global?) weights
  
      norm: If "l1" or "l2", normalize weights by the L1 or L2 norms, respectively,
          of row-wise vectors; otherwise, don't.
      min_df: Minimum number of documents in which a term must appear for it to be
          included in the vocabulary and as a column in a transformed doc-term matrix.
          If float, value is the fractional proportion of the total number of docs,
          which must be in [0.0, 1.0]; if int, value is the absolute number.
      max_df: Maximum number of documents in which a term may appear for it to be
          included in the vocabulary and as a column in a transformed doc-term matrix.
          If float, value is the fractional proportion of the total number of docs,
          which must be in [0.0, 1.0]; if int, value is the absolute number.
      max_n_terms: If specified, only include terms whose document frequency is within
          the top ``max_n_terms``.
      vocabulary_terms: Mapping of unique term string to unique term id, or
          an iterable of term strings that gets converted into such a mapping.
          Note that, if specified, vectorized output will include *only* these terms.
      vocabulary_grps: Mapping of unique group string to unique group id, or
          an iterable of group strings that gets converted into such a mapping.
          Note that, if specified, vectorized output will include *only* these groups.
  
  Attributes:
      vocabulary_terms (dict[str, int]): Mapping of unique term string to unique
          term id, either provided on instantiation or generated by calling
          :meth:`GroupVectorizer.fit()` on a collection of tokenized documents.
      vocabulary_grps (dict[str, int]): Mapping of unique group string to unique
          group id, either provided on instantiation or generated by calling
          :meth:`GroupVectorizer.fit()` on a collection of tokenized documents.
  
  See Also:
      :class:`Vectorizer`
class_docstr_tok: ["Transform","one","or","more","tokenized","documents","into","a","group-term","matrix","of","shape","(","#","groups",",","#","unique","terms",")",",","with","tf-",",","tf-idf",",","or","binary-weighted","values",".","This","is","an","extension","of","typical","document-term","matrix","vectorization",",","where","terms","are","grouped","by","the","documents","in","which","they","co-occur",".","It","allows","for","customized","grouping",",","such","as","by","a","shared","author","or","publication","year",",","that","may","span","multiple","documents",",","without","forcing","users","to","merge","those","documents","themselves",".","Stream","a","corpus","with","metadata","from","disk",":",":",">",">",">","ds","=","textacy.datasets.CapitolWords","(",")",">",">",">","records","=","ds.records","(","limit=1000",")",">",">",">","corpus","=","textacy.Corpus","(","``","en_core_web_sm","''",",","data=records",")",">",">",">","corpus","Corpus","(","1000","docs",",","538397","tokens",")","Tokenize","and","vectorize","the","first","600","documents","of","this","corpus",",","where","terms","are","grouped","not","by","documents","but","by","a","categorical","value","in","the","docs","'","metadata",":",":",">",">",">","tokenized_docs",",","groups","=","textacy.io.unzip","(","...","(","(","term.lemma_","for","term","in","textacy.extract.terms","(","doc",",","ngs=1",",","ents=True",")",")",",","...","doc._.meta","[","``","speaker_name","''","]",")","...","for","doc","in","corpus","[",":600","]",")",">",">",">","vectorizer","=","GroupVectorizer","(","...","tf_type=","''","linear","''",",","idf_type=","''","smooth","''",",","norm=","''","l2","''",",","...","min_df=3",",","max_df=0.95",")",">",">",">","grp_term_matrix","=","vectorizer.fit_transform","(","tokenized_docs",",","groups",")",">",">",">","grp_term_matrix","<","5x1822","sparse","matrix","of","type","'","<","class","'numpy.float64","'",">","'","with","6139","stored","elements","in","Compressed","Sparse","Row","format",">","Tokenize","and","vectorize","the","remaining","400","documents","of","the","corpus",",","using","only","the","groups",",","terms",",","and","weights","learned","in","the","previous","step",":",":",">",">",">","tokenized_docs",",","groups","=","textacy.io.unzip","(","...","(","(","term.lemma_","for","term","in","textacy.extract.terms","(","doc",",","ngs=1",",","ents=True",")",")",",","...","doc._.meta","[","``","speaker_name","''","]",")","...","for","doc","in","corpus","[","600",":","]",")",">",">",">","grp_term_matrix","=","vectorizer.transform","(","tokenized_docs",",","groups",")",">",">",">","grp_term_matrix","<","5x1822","sparse","matrix","of","type","'","<","class","'numpy.float64","'",">","'","with","4414","stored","elements","in","Compressed","Sparse","Row","format",">","Inspect","the","terms","associated","with","columns","and","groups","associated","with","rows",";","they","'re","sorted","alphabetically",":",":",">",">",">","vectorizer.terms_list","[",":5","]","[","``",",","'","$","1","million","'",",","'","$","160","million","'",",","'","$","5","billion","'",",","'","$","7","billion","'","]",">",">",">","vectorizer.grps_list","[","'Bernie","Sanders","'",",","'John","Kasich","'",",","'Joseph","Biden","'",",","'Lindsey","Graham","'",",","'Rick","Santorum","'","]","If","known","in","advance",",","limit","the","terms","and\/or","groups","included","in","vectorized","outputs","to","a","particular","set","of","values",":",":",">",">",">","tokenized_docs",",","groups","=","textacy.io.unzip","(","...","(","(","term.lemma_","for","term","in","textacy.extract.terms","(","doc",",","ngs=1",",","ents=True",")",")",",","...","doc._.meta","[","``","speaker_name","''","]",")","...","for","doc","in","corpus","[",":600","]",")",">",">",">","vectorizer","=","GroupVectorizer","(","...","tf_type=","''","linear","''",",","idf_type=","''","smooth","''",",","norm=","''","l2","''",",","...","min_df=3",",","max_df=0.95",",","...","vocabulary_terms=","[","``","legislation","''",",","``","federal","government","''",",","``","house","''",",","``","constitutional","''","]",",","...","vocabulary_grps=","[","``","Bernie","Sanders","''",",","``","Lindsey","Graham","''",",","``","Rick","Santorum","''","]",")",">",">",">","grp_term_matrix","=","vectorizer.fit_transform","(","tokenized_docs",",","groups",")",">",">",">","grp_term_matrix","<","3x4","sparse","matrix","of","type","'","<","class","'numpy.float64","'",">","'","with","9","stored","elements","in","Compressed","Sparse","Row","format",">",">",">",">","vectorizer.terms_list","[","'constitutional","'",",","'federal","government","'",",","'house","'",",","'legislation","'","]",">",">",">","vectorizer.grps_list","[","'Bernie","Sanders","'",",","'Lindsey","Graham","'",",","'Rick","Santorum","'","]","For","a","discussion","of","the","various","weighting","schemes","that","can","be","applied",",","check","out","the",":","class",":","`","Vectorizer","`","docstring",".","Args",":","tf_type",":","Type","of","term","frequency","(","tf",")","to","use","for","weights","'","local","component",":","-","``","linear","''",":","tf","(","tfs","are","already","linear",",","so","left","as-is",")","-","``","sqrt","''",":","tf","=",">","sqrt","(","tf",")","-","``","log","''",":","tf","=",">","log","(","tf",")","+","1","-","``","binary","''",":","tf","=",">","1","idf_type",":","Type","of","inverse","document","frequency","(","idf",")","to","use","for","weights'","global","component",":","-","``","standard","''",":","idf","=","log","(","n_docs","\/","df",")","+","1.0","-","``","smooth","''",":","idf","=","log","(","n_docs","+","1","\/","df","+","1",")","+","1.0",",","i.e",".","1","is","added","to","all","document","frequencies",",","as","if","a","single","document","containing","every","unique","term","was","added","to","the","corpus",".","-","``","bm25","''",":","idf","=","log","(","(","n_docs","-","df","+","0.5",")","\/","(","df","+","0.5",")",")",",","which","is","a","form","commonly","used","in","information","retrieval","that","allows","for","very","common","terms","to","receive","negative","weights",".","-","None",":","no","global","weighting","is","applied","to","local","term","weights",".","dl_type",":","Type","of","document-length","scaling","to","use","for","weights'","normalization","component",":","-","``","linear","''",":","dl","(","dls","are","already","linear",",","so","left","as-is",")","-","``","sqrt","''",":","dl","=",">","sqrt","(","dl",")","-","``","log","''",":","dl","=",">","log","(","dl",")","-","None",":","no","normalization","is","applied","to","local","(","+global","?",")","weights","norm",":","If","``","l1","''","or","``","l2","''",",","normalize","weights","by","the","L1","or","L2","norms",",","respectively",",","of","row-wise","vectors",";","otherwise",",","do","n't",".","min_df",":","Minimum","number","of","documents","in","which","a","term","must","appear","for","it","to","be","included","in","the","vocabulary","and","as","a","column","in","a","transformed","doc-term","matrix",".","If","float",",","value","is","the","fractional","proportion","of","the","total","number","of","docs",",","which","must","be","in","[","0.0",",","1.0","]",";","if","int",",","value","is","the","absolute","number",".","max_df",":","Maximum","number","of","documents","in","which","a","term","may","appear","for","it","to","be","included","in","the","vocabulary","and","as","a","column","in","a","transformed","doc-term","matrix",".","If","float",",","value","is","the","fractional","proportion","of","the","total","number","of","docs",",","which","must","be","in","[","0.0",",","1.0","]",";","if","int",",","value","is","the","absolute","number",".","max_n_terms",":","If","specified",",","only","include","terms","whose","document","frequency","is","within","the","top","``","max_n_terms","``",".","vocabulary_terms",":","Mapping","of","unique","term","string","to","unique","term","id",",","or","an","iterable","of","term","strings","that","gets","converted","into","such","a","mapping",".","Note","that",",","if","specified",",","vectorized","output","will","include","*","only","*","these","terms",".","vocabulary_grps",":","Mapping","of","unique","group","string","to","unique","group","id",",","or","an","iterable","of","group","strings","that","gets","converted","into","such","a","mapping",".","Note","that",",","if","specified",",","vectorized","output","will","include","*","only","*","these","groups",".","Attributes",":","vocabulary_terms","(","dict","[","str",",","int","]",")",":","Mapping","of","unique","term","string","to","unique","term","id",",","either","provided","on","instantiation","or","generated","by","calling",":","meth",":","`","GroupVectorizer.fit","(",")","`","on","a","collection","of","tokenized","documents",".","vocabulary_grps","(","dict","[","str",",","int","]",")",":","Mapping","of","unique","group","string","to","unique","group","id",",","either","provided","on","instantiation","or","generated","by","calling",":","meth",":","`","GroupVectorizer.fit","(",")","`","on","a","collection","of","tokenized","documents",".","See","Also",":",":","class",":","`","Vectorizer","`"]
docstr: List of group strings in row order of vectorized outputs. For example,
  ``grps_list[0]`` gives the group assigned to the first row in an
  output group-term-matrix, ``grp_term_matrix[0, :]``.
docstr_tok: ["List","of","group","strings","in","row","order","of","vectorized","outputs",".","For","example",",","``","grps_list","[","0","]","``","gives","the","group","assigned","to","the","first","row","in","an","output","group-term-matrix",",","``","grp_term_matrix","[","0",",",":","]","``","."]
code: def grps_list(self) -> list[str]:
      """
      List of group strings in row order of vectorized outputs. For example,
      ``grps_list[0]`` gives the group assigned to the first row in an
      output group-term-matrix, ``grp_term_matrix[0, :]``.
      """
      self._check_vocabulary()
      return [
          grp_str
          for grp_str, _ in sorted(
              self.vocabulary_grps.items(), key=operator.itemgetter(1)
          )
      ]
  
imports: from __future__ import annotations
  import collections
  import collections.abc
  import operator
  from array import array
  from typing import DefaultDict, Iterable, Literal, Optional, Union
  import numpy
  import scipy.sparse
  from sklearn.preprocessing import normalize
  from ..None import errors
  from .matrix_utils import filter_terms_by_df, get_doc_lengths, get_inverse_doc_freqs
label_desc: Use image node_id 3 for calling the GroupVectorizer obj's underlying member method code with example usage: obj.grps_list() and returns: unknown