code: def filter_on(
      df: pd.DataFrame,
      criteria: str,
      complement: bool = False,
  ) -> pd.DataFrame:
      """Return a dataframe filtered on a particular criteria.
  
      This method does not mutate the original DataFrame.
  
      This is super-sugary syntax that wraps the pandas `.query()` API, enabling
      users to use strings to quickly specify filters for filtering their
      dataframe. The intent is that `filter_on` as a verb better matches the
      intent of a pandas user than the verb `query`.
  
      This is intended to be the method-chaining equivalent of the following:
  
      ```python
      df = df[df["score"] < 3]
      ```
  
      !!!note
  
          This function will be deprecated in a 1.x release.
          Please use `pd.DataFrame.query` instead.
  
  
      Examples:
          Filter students who failed an exam (scored less than 50).
  
          >>> import pandas as pd
          >>> import janitor
          >>> df = pd.DataFrame({
          ...     "student_id": ["S1", "S2", "S3"],
          ...     "score": [40, 60, 85],
          ... })
          >>> df
            student_id  score
          0         S1     40
          1         S2     60
          2         S3     85
          >>> df.filter_on("score < 50", complement=False)
            student_id  score
          0         S1     40
  
      Credit to Brant Peterson for the name.
  
      Args:
          df: A pandas DataFrame.
          criteria: A filtering criteria that returns an array or Series of
              booleans, on which pandas can filter on.
          complement: Whether to return the complement of the filter or not.
              If set to True, then the rows for which the criteria is False are
              retained instead.
  
      Returns:
          A filtered pandas DataFrame.
      """
  
      warnings.warn(
          "This function will be deprecated in a 1.x release. "
          "Kindly use `pd.DataFrame.query` instead.",
          DeprecationWarning,
          stacklevel=find_stack_level(),
      )
  
      if complement:
          return df.query(f"not ({criteria})")
      return df.query(criteria)
  
file_path: pyjanitor/janitor/functions/filter.py
imports: import datetime
  import warnings
  from functools import reduce
  from typing import Any, Dict, Hashable, Iterable, List, Optional
  import numpy
  import pandas
  import pandas_flavor
  from janitor.utils import deprecated_alias, find_stack_level, refactored_function
label_desc: Use image node_id 2 for calling a global function with example usage: filter_on(df, criteria, complement) and returns: df, df