class_docstr: Base class for objects underlying *plot functions.
class_docstr_tok: ["Base","class","for","objects","underlying","*","plot","functions","."]
docstr: Generator for getting subsets of data defined by semantic variables.
  
  Also injects "col" and "row" into grouping semantics.
  
  Parameters
  ----------
  grouping_vars : string or list of strings
      Semantic variables that define the subsets of data.
  reverse : bool
      If True, reverse the order of iteration.
  from_comp_data : bool
      If True, use self.comp_data rather than self.plot_data
  by_facet : bool
      If True, add faceting variables to the set of grouping variables.
  allow_empty : bool
      If True, yield an empty dataframe when no observations exist for
      combinations of grouping variables.
  dropna : bool
      If True, remove rows with missing data.
  
  Yields
  ------
  sub_vars : dict
      Keys are semantic names, values are the level of that semantic.
  sub_data : :class:`pandas.DataFrame`
      Subset of ``plot_data`` for this combination of semantic values.
docstr_tok: ["Generator","for","getting","subsets","of","data","defined","by","semantic","variables",".","Also","injects","``","col","''","and","``","row","''","into","grouping","semantics",".","Parameters","--","--","--","--","--","grouping_vars",":","string","or","list","of","strings","Semantic","variables","that","define","the","subsets","of","data",".","reverse",":","bool","If","True",",","reverse","the","order","of","iteration",".","from_comp_data",":","bool","If","True",",","use","self.comp_data","rather","than","self.plot_data","by_facet",":","bool","If","True",",","add","faceting","variables","to","the","set","of","grouping","variables",".","allow_empty",":","bool","If","True",",","yield","an","empty","dataframe","when","no","observations","exist","for","combinations","of","grouping","variables",".","dropna",":","bool","If","True",",","remove","rows","with","missing","data",".","Yields","--","--","--","sub_vars",":","dict","Keys","are","semantic","names",",","values","are","the","level","of","that","semantic",".","sub_data",":",":","class",":","`","pandas.DataFrame","`","Subset","of","``","plot_data","``","for","this","combination","of","semantic","values","."]
code: def iter_data(
      self,
      grouping_vars=None,
      *,
      reverse=False,
      from_comp_data=False,
      by_facet=True,
      allow_empty=False,
      dropna=True,
  ):
      """Generator for getting subsets of data defined by semantic variables.
  
      Also injects "col" and "row" into grouping semantics.
  
      Parameters
      ----------
      grouping_vars : string or list of strings
          Semantic variables that define the subsets of data.
      reverse : bool
          If True, reverse the order of iteration.
      from_comp_data : bool
          If True, use self.comp_data rather than self.plot_data
      by_facet : bool
          If True, add faceting variables to the set of grouping variables.
      allow_empty : bool
          If True, yield an empty dataframe when no observations exist for
          combinations of grouping variables.
      dropna : bool
          If True, remove rows with missing data.
  
      Yields
      ------
      sub_vars : dict
          Keys are semantic names, values are the level of that semantic.
      sub_data : :class:`pandas.DataFrame`
          Subset of ``plot_data`` for this combination of semantic values.
  
      """
      # TODO should this default to using all (non x/y?) semantics?
      # or define grouping vars somewhere?
      if grouping_vars is None:
          grouping_vars = []
      elif isinstance(grouping_vars, str):
          grouping_vars = [grouping_vars]
      elif isinstance(grouping_vars, tuple):
          grouping_vars = list(grouping_vars)
  
      # Always insert faceting variables
      if by_facet:
          facet_vars = {"col", "row"}
          grouping_vars.extend(
              facet_vars & set(self.variables) - set(grouping_vars)
          )
  
      # Reduce to the semantics used in this plot
      grouping_vars = [
          var for var in grouping_vars if var in self.variables
      ]
  
      if from_comp_data:
          data = self.comp_data
      else:
          data = self.plot_data
  
      if dropna:
          data = data.dropna()
  
      levels = self.var_levels.copy()
      if from_comp_data:
          for axis in {"x", "y"} & set(grouping_vars):
              converter = self.converters[axis].iloc[0]
              if self.var_types[axis] == "categorical":
                  if self._var_ordered[axis]:
                      # If the axis is ordered, then the axes in a possible
                      # facet grid are by definition "shared", or there is a
                      # single axis with a unique cat -> idx mapping.
                      # So we can just take the first converter object.
                      levels[axis] = converter.convert_units(
                          levels[axis]
                      )
                  else:
                      # Otherwise, the mappings may not be unique, but we can
                      # use the unique set of index values in comp_data.
                      levels[axis] = np.sort(data[axis].unique())
              else:
                  transform = converter.get_transform().transform
                  levels[axis] = transform(
                      converter.convert_units(levels[axis])
                  )
  
      if grouping_vars:
          grouped_data = data.groupby(
              grouping_vars,
              sort=False,
              as_index=False,
              observed=False,
          )
  
          grouping_keys = []
          for var in grouping_vars:
              key = levels.get(var)
              grouping_keys.append([] if key is None else key)
  
          iter_keys = itertools.product(*grouping_keys)
          if reverse:
              iter_keys = reversed(list(iter_keys))
  
          for key in iter_keys:
              # Pandas fails with singleton tuple inputs
              pd_key = key[0] if len(key) == 1 else key
  
              try:
                  data_subset = grouped_data.get_group(pd_key)
              except KeyError:
                  # XXX we are adding this to allow backwards compatibility
                  # with the empty artists that old categorical plots would
                  # add (before 0.12), which we may decide to break, in which
                  # case this option could be removed
                  data_subset = data.loc[[]]
  
              if data_subset.empty and not allow_empty:
                  continue
  
              sub_vars = dict(zip(grouping_vars, key))
  
              yield sub_vars, data_subset.copy()
  
      else:
          yield {}, data.copy()
  
imports: from __future__ import annotations
  import warnings
  import itertools
  from copy import copy
  from collections import UserString
  from collections.abc import Iterable, Sequence, Mapping
  from numbers import Number
  from datetime import datetime
  import numpy
  import pandas
  import matplotlib
  from seaborn._core.data import PlotData
  from seaborn.palettes import QUAL_PALETTES, color_palette
  from seaborn.utils import _check_argument, _version_predates, desaturate, locator_to_legend_entries, get_color_cycle, remove_na
label_desc: Use image node_id 9 for calling the VectorPlotter obj's underlying member method code with example usage: obj.iter_data(grouping_vars) without return types