parameters: (
          self,
          n: int | None = None,
          frac: float | None = None,
          replace: bool = False,
          weights: Sequence | Series | None = None,
          random_state=None,
      )
return_statement: return concat(samples, axis=self.axis)
docstring: Return a random sample of items from each group.
  
          You can use `random_state` for reproducibility.
  
          .. versionadded:: 1.1.0
  
          Parameters
          ----------
          n : int, optional
              Number of items to return for each group. Cannot be used with
              `frac` and must be no larger than the smallest group unless
              `replace` is True. Default is one if `frac` is None.
          frac : float, optional
              Fraction of items to return. Cannot be used with `n`.
          replace : bool, default False
              Allow or disallow sampling of the same row more than once.
          weights : list-like, optional
              Default None results in equal probability weighting.
              If passed a list-like then values must have the same length as
              the underlying DataFrame or Series object and will be used as
              sampling probabilities after normalization within each group.
              Values must be non-negative with at least one positive element
              within each group.
          random_state : int, array-like, BitGenerator, np.random.RandomState, optional
              If int, array-like, or BitGenerator (NumPy>=1.17), seed for
              random number generator
              If np.random.RandomState, use as numpy RandomState object.
  
          Returns
          -------
          Series or DataFrame
              A new object of same type as caller containing items randomly
              sampled within each group from the caller object.
  
          See Also
          --------
          DataFrame.sample: Generate random samples from a DataFrame object.
          numpy.random.choice: Generate a random sample from a given 1-D numpy
              array.
  
          Examples
          --------
          >>> df = pd.DataFrame(
          ...     {"a": ["red"] * 2 + ["blue"] * 2 + ["black"] * 2, "b": range(6)}
          ... )
          >>> df
                 a  b
          0    red  0
          1    red  1
          2   blue  2
          3   blue  3
          4  black  4
          5  black  5
  
          Select one row at random for each distinct value in column a. The
          `random_state` argument can be used to guarantee reproducibility:
  
          >>> df.groupby("a").sample(n=1, random_state=1)
                 a  b
          4  black  4
          2   blue  2
          1    red  1
  
          Set `frac` to sample fixed proportions rather than counts:
  
          >>> df.groupby("a")["b"].sample(frac=0.5, random_state=2)
          5    5
          2    2
          0    0
          Name: b, dtype: int64
  
          Control sample probabilities within groups by setting weights:
  
          >>> df.groupby("a").sample(
          ...     n=1,
          ...     weights=[1, 1, 1, 0, 0, 1],
          ...     random_state=1,
          ... )
                 a  b
          5  black  5
          2   blue  2
          0    red  0
docstring_summary: Return a random sample of items from each group.
docstring_tokens: Return a random sample of items from each group .
function: def sample(
          self,
          n: int | None = None,
          frac: float | None = None,
          replace: bool = False,
          weights: Sequence | Series | None = None,
          random_state=None,
      ):
          """
          Return a random sample of items from each group.
  
          You can use `random_state` for reproducibility.
  
          .. versionadded:: 1.1.0
  
          Parameters
          ----------
          n : int, optional
              Number of items to return for each group. Cannot be used with
              `frac` and must be no larger than the smallest group unless
              `replace` is True. Default is one if `frac` is None.
          frac : float, optional
              Fraction of items to return. Cannot be used with `n`.
          replace : bool, default False
              Allow or disallow sampling of the same row more than once.
          weights : list-like, optional
              Default None results in equal probability weighting.
              If passed a list-like then values must have the same length as
              the underlying DataFrame or Series object and will be used as
              sampling probabilities after normalization within each group.
              Values must be non-negative with at least one positive element
              within each group.
          random_state : int, array-like, BitGenerator, np.random.RandomState, optional
              If int, array-like, or BitGenerator (NumPy>=1.17), seed for
              random number generator
              If np.random.RandomState, use as numpy RandomState object.
  
          Returns
          -------
          Series or DataFrame
              A new object of same type as caller containing items randomly
              sampled within each group from the caller object.
  
          See Also
          --------
          DataFrame.sample: Generate random samples from a DataFrame object.
          numpy.random.choice: Generate a random sample from a given 1-D numpy
              array.
  
          Examples
          --------
          >>> df = pd.DataFrame(
          ...     {"a": ["red"] * 2 + ["blue"] * 2 + ["black"] * 2, "b": range(6)}
          ... )
          >>> df
                 a  b
          0    red  0
          1    red  1
          2   blue  2
          3   blue  3
          4  black  4
          5  black  5
  
          Select one row at random for each distinct value in column a. The
          `random_state` argument can be used to guarantee reproducibility:
  
          >>> df.groupby("a").sample(n=1, random_state=1)
                 a  b
          4  black  4
          2   blue  2
          1    red  1
  
          Set `frac` to sample fixed proportions rather than counts:
  
          >>> df.groupby("a")["b"].sample(frac=0.5, random_state=2)
          5    5
          2    2
          0    0
          Name: b, dtype: int64
  
          Control sample probabilities within groups by setting weights:
  
          >>> df.groupby("a").sample(
          ...     n=1,
          ...     weights=[1, 1, 1, 0, 0, 1],
          ...     random_state=1,
          ... )
                 a  b
          5  black  5
          2   blue  2
          0    red  0
          """
          from pandas.core.reshape.concat import concat
  
          if weights is not None:
              weights = Series(weights, index=self._selected_obj.index)
              ws = [weights.iloc[idx] for idx in self.indices.values()]
          else:
              ws = [None] * self.ngroups
  
          if random_state is not None:
              random_state = com.random_state(random_state)
  
          group_iterator = self.grouper.get_iterator(self._selected_obj, self.axis)
          samples = [
              obj.sample(
                  n=n, frac=frac, replace=replace, weights=w, random_state=random_state
              )
              for (_, obj), w in zip(group_iterator, ws)
          ]
  
          return concat(samples, axis=self.axis)
function_tokens: def sample ( self , n : int | None = None , frac : float | None = None , replace : bool = False , weights : Sequence | Series | None = None , random_state = None , ) : from pandas . core . reshape . concat import concat if weights is not None : weights = Series ( weights , index = self . _selected_obj . index ) ws = [ weights . iloc [ idx ] for idx in self . indices . values ( ) ] else : ws = [ None ] * self . ngroups if random_state is not None : random_state = com . random_state ( random_state ) group_iterator = self . grouper . get_iterator ( self . _selected_obj , self . axis ) samples = [ obj . sample ( n = n , frac = frac , replace = replace , weights = w , random_state = random_state ) for ( _ , obj ) , w in zip ( group_iterator , ws ) ] return concat ( samples , axis = self . axis )