edsl 0.1.47__py3-none-any.whl → 0.1.48__py3-none-any.whl

edsl/results/{Results.py → results.py}

@@ -1,18 +1,67 @@
 """
-The Results object is the result of running a survey. 
-It is not typically instantiated directly, but is returned by the run method of a `Job` object.
+The Results module provides tools for working with collections of Result objects.
+
+The Results class is the primary container for analyzing and manipulating data obtained 
+from running surveys with language models. It implements a powerful data analysis interface 
+with methods for filtering, selecting, mutating, and visualizing your results, similar to
+data manipulation libraries like dplyr or pandas.
+
+Key components:
+
+1. Results - A collection of Result objects with methods for data analysis and manipulation
+2. Report - A flexible reporting system for generating formatted output from Results
+3. Selectors - Tools for efficiently extracting specific data from Results
+
+The Results class is not typically instantiated directly; instead, it's returned by the 
+run() method of a Job object. Once you have a Results object, you can use its methods
+to analyze and extract insights from your survey data.
+
+Example workflow:
+```python
+# Run a job and get results
+results = job.run()
+
+# Filter to a subset of results
+filtered = results.filter("how_feeling == 'Great'")
+
+# Select specific columns for analysis
+data = filtered.select("how_feeling", "agent.status")
+
+# Create a new derived column
+with_sentiment = results.mutate("sentiment = 1 if how_feeling == 'Great' else 0")
+
+# Generate a report
+report = Report(results, fields=["answer.how_feeling", "answer.sentiment"])
+print(report.generate())
+```
 """
 
 from __future__ import annotations
 import json
 import random
+import warnings
 from collections import UserList, defaultdict
 from typing import Optional, Callable, Any, Type, Union, List, TYPE_CHECKING
-
 from bisect import bisect_left
 
-from edsl.Base import Base
-from edsl.exceptions.results import (
+from ..base import Base
+
+if TYPE_CHECKING:
+    from ..surveys import Survey
+    from ..data import Cache
+    from ..agents import AgentList
+    from ..language_models import Model
+    from ..scenarios import ScenarioList
+    from ..results import Result
+    from ..tasks import TaskHistory
+    from ..language_models import ModelList
+    from simpleeval import EvalWithCompoundTypes
+    from ..dataset import Dataset
+
+from ..utilities import remove_edsl_version, dict_hash
+from ..dataset import ResultsOperationsMixin
+
+from .exceptions import (
     ResultsError,
     ResultsBadMutationstringError,
     ResultsColumnNotFoundError,
@@ -22,22 +71,6 @@ from edsl.exceptions.results import (
     ResultsDeserializationError,
 )
 
-if TYPE_CHECKING:
-    from edsl.surveys.Survey import Survey
-    from edsl.data.Cache import Cache
-    from edsl.agents.AgentList import AgentList
-    from edsl.language_models.model import Model
-    from edsl.scenarios.ScenarioList import ScenarioList
-    from edsl.results.Result import Result
-    from edsl.jobs.tasks.TaskHistory import TaskHistory
-    from edsl.language_models.ModelList import ModelList
-    from simpleeval import EvalWithCompoundTypes
-
-from edsl.results.ResultsExportMixin import ResultsExportMixin
-from edsl.results.ResultsGGMixin import GGPlotMethod
-from edsl.results.results_fetch_mixin import ResultsFetchMixin
-from edsl.utilities.remove_edsl_version import remove_edsl_version
-
 def ensure_fetched(method):
     """A decorator that checks if remote data is loaded, and if not, attempts to fetch it."""
     def wrapper(self, *args, **kwargs):
@@ -80,7 +113,7 @@ def ensure_ready(method):
 
 class NotReadyObject:
     """A placeholder object that prints a message when any attribute is accessed."""
-    def __init__(self, name: str, job_info: RemoteJobInfo):
+    def __init__(self, name: str, job_info: 'RemoteJobInfo'):
         self.name = name
         self.job_info = job_info
         #print(f"Not ready to call {name}")
@@ -97,39 +130,40 @@ class NotReadyObject:
     def __call__(self, *args, **kwargs):
         return self
 
-class Mixins(
-    ResultsExportMixin,
-    ResultsFetchMixin,
-#    ResultsGGMixin,
-):
-    def long(self):
-        return self.table().long()
-
-    def print_long(self, max_rows: int = None) -> None:
-        """Print the results in long format.
-
-        >>> from edsl.results import Results
-        >>> r = Results.example()
-        >>> r.select('how_feeling').print_long(max_rows = 2)
-        ┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━┓
-        ┃ Result index ┃ Key         ┃ Value ┃
-        ┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━┩
-        │ 0            │ how_feeling │ OK    │
-        │ 1            │ how_feeling │ Great │
-        └──────────────┴─────────────┴───────┘
-        """
-        from edsl.utilities.interface import print_results_long
-
-        print_results_long(self, max_rows=max_rows)
-
 
-class Results(UserList, Mixins, Base):
+class Results(UserList, ResultsOperationsMixin, Base):
     """
-    This class is a UserList of Result objects.
-
-    It is instantiated with a `Survey` and a list of `Result` objects.
-    It can be manipulated in various ways with select, filter, mutate, etc.
-    It also has a list of created_columns, which are columns that have been created with `mutate` and are not part of the original data.
+    A collection of Result objects with powerful data analysis capabilities.
+    
+    The Results class is the primary container for working with data from EDSL surveys.
+    It provides a rich set of methods for data analysis, transformation, and visualization
+    inspired by data manipulation libraries like dplyr and pandas. The Results class 
+    implements a functional, fluent interface for data manipulation where each method 
+    returns a new Results object, allowing method chaining.
+    
+    Key features:
+    
+    - List-like interface for accessing individual Result objects
+    - Selection of specific data columns with `select()`
+    - Filtering results with boolean expressions using `filter()`
+    - Creating new derived columns with `mutate()`
+    - Recoding values with `recode()` and `answer_truncate()`
+    - Sorting results with `order_by()`
+    - Converting to other formats (dataset, table, pandas DataFrame)
+    - Serialization for storage and retrieval
+    - Support for remote execution and result retrieval
+    
+    Results objects have a hierarchical structure with the following components:
+    
+    1. Each Results object contains multiple Result objects
+    2. Each Result object contains data organized by type (agent, scenario, model, answer, etc.)
+    3. Each data type contains multiple attributes (e.g., "how_feeling" in the answer type)
+    
+    You can access data in a Results object using dot notation (`answer.how_feeling`) or
+    using just the attribute name if it's not ambiguous (`how_feeling`).
+    
+    The Results class also tracks "created columns" - new derived values that aren't
+    part of the original data but were created through transformations.
     """
 
     __documentation__ = "https://docs.expectedparrot.com/en/latest/results.html"
@@ -151,19 +185,6 @@ class Results(UserList, Mixins, Base):
         "cache_keys",
     ]
 
-    def ggplot2(
-        self,
-        ggplot_code: str,
-        shape="wide",
-        sql: str = None,
-        remove_prefix: bool = True,
-        debug: bool = False,
-        height=4,
-        width=6,
-        factor_orders: Optional[dict] = None,
-    ):
-        return GGPlotMethod(self).ggplot2(ggplot_code, shape, sql, remove_prefix, debug, height, width, factor_orders)
-
     @classmethod
     def from_job_info(cls, job_info: dict) -> Results:
         """
@@ -196,8 +217,8 @@ class Results(UserList, Mixins, Base):
         self.completed = True
         self._fetching = False
         super().__init__(data)
-        from edsl.data.Cache import Cache
-        from edsl.jobs.tasks.TaskHistory import TaskHistory
+        from ..caching import Cache
+        from ..tasks import TaskHistory
 
         self.survey = survey
         self.created_columns = created_columns or []
@@ -210,6 +231,47 @@ class Results(UserList, Mixins, Base):
         if hasattr(self, "_add_output_functions"):
             self._add_output_functions()
 
+    def long(self):
+        return self.table().long()
+
+    def print_long(self, max_rows: int = None) -> None:
+        """Print the results in long format.
+
+        >>> from edsl.results import Results
+        >>> r = Results.example()
+        >>> r.select('how_feeling').print_long(max_rows = 2)
+        ┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━┓
+        ┃ Result index ┃ Key         ┃ Value ┃
+        ┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━┩
+        │ 0            │ how_feeling │ OK    │
+        │ 1            │ how_feeling │ Great │
+        └──────────────┴─────────────┴───────┘
+        """
+        from edsl.utilities.interface import print_results_long
+
+        print_results_long(self, max_rows=max_rows)
+
+
+    def _fetch_list(self, data_type: str, key: str) -> list:
+        """
+        Return a list of values from the data for a given data type and key.
+
+        Uses the filtered data, not the original data.
+
+        Example:
+
+        >>> from edsl.results import Results
+        >>> r = Results.example()
+        >>> r._fetch_list('answer', 'how_feeling')
+        ['OK', 'Great', 'Terrible', 'OK']
+        """
+        returned_list = []
+        for row in self.data:
+            returned_list.append(row.sub_dicts[data_type].get(key, None))
+
+        return returned_list
+
+
     def _summary(self) -> dict:
         import reprlib
 
@@ -280,83 +342,83 @@ class Results(UserList, Mixins, Base):
 
         return total_cost
 
-    def leaves(self):
-        leaves = []
-        for result in self:
-            leaves.extend(result.leaves())
-        return leaves
-
-    def tree(self, node_list: Optional[List[str]] = None):
-        return self.to_scenario_list().tree(node_list)
-
-    def interactive_tree(
-        self,
-        fold_attributes: Optional[List[str]] = None,
-        drop: Optional[List[str]] = None,
-        open_file=True,
-    ) -> dict:
-        """Return the results as a tree."""
-        from edsl.results.tree_explore import FoldableHTMLTableGenerator
-
-        if drop is None:
-            drop = []
-
-        valid_attributes = [
-            "model",
-            "scenario",
-            "agent",
-            "answer",
-            "question",
-            "iteration",
-        ]
-        if fold_attributes is None:
-            fold_attributes = []
-
-        for attribute in fold_attributes:
-            if attribute not in valid_attributes:
-                raise ValueError(
-                    f"Invalid fold attribute: {attribute}; must be in {valid_attributes}"
-                )
-        data = self.leaves()
-        generator = FoldableHTMLTableGenerator(data)
-        tree = generator.tree(fold_attributes=fold_attributes, drop=drop)
-        html_content = generator.generate_html(tree, fold_attributes)
-        import tempfile
-        from edsl.utilities.utilities import is_notebook
-
-        from IPython.display import display, HTML
-
-        if is_notebook():
-            import html
-            from IPython.display import display, HTML
-
-            height = 1000
-            width = 1000
-            escaped_output = html.escape(html_content)
-            # escaped_output = rendered_html
-            iframe = f""""
-            <iframe srcdoc="{ escaped_output }" style="width: {width}px; height: {height}px;"></iframe>
-            """
-            display(HTML(iframe))
-            return None
-
-        with tempfile.NamedTemporaryFile(suffix=".html", delete=False) as f:
-            f.write(html_content.encode())
-            print(f"HTML file has been generated: {f.name}")
-
-            if open_file:
-                import webbrowser
-                import time
-
-                time.sleep(1)  # Wait for 1 second
-                # webbrowser.open(f.name)
-                import os
-
-                filename = f.name
-                webbrowser.open(f"file://{os.path.abspath(filename)}")
-
-            else:
-                return html_content
+    # def leaves(self):
+    #     leaves = []
+    #     for result in self:
+    #         leaves.extend(result.leaves())
+    #     return leaves
+
+    # def tree(self, node_list: Optional[List[str]] = None):
+    #     return self.to_scenario_list().tree(node_list)
+
+    # def interactive_tree(
+    #     self,
+    #     fold_attributes: Optional[List[str]] = None,
+    #     drop: Optional[List[str]] = None,
+    #     open_file=True,
+    # ) -> dict:
+    #     """Return the results as a tree."""
+    #     from edsl.results.tree_explore import FoldableHTMLTableGenerator
+
+    #     if drop is None:
+    #         drop = []
+
+    #     valid_attributes = [
+    #         "model",
+    #         "scenario",
+    #         "agent",
+    #         "answer",
+    #         "question",
+    #         "iteration",
+    #     ]
+    #     if fold_attributes is None:
+    #         fold_attributes = []
+
+    #     for attribute in fold_attributes:
+    #         if attribute not in valid_attributes:
+    #             raise ValueError(
+    #                 f"Invalid fold attribute: {attribute}; must be in {valid_attributes}"
+    #             )
+    #     data = self.leaves()
+    #     generator = FoldableHTMLTableGenerator(data)
+    #     tree = generator.tree(fold_attributes=fold_attributes, drop=drop)
+    #     html_content = generator.generate_html(tree, fold_attributes)
+    #     import tempfile
+    #     from edsl.utilities.utilities import is_notebook
+
+    #     from IPython.display import display, HTML
+
+    #     if is_notebook():
+    #         import html
+    #         from IPython.display import display, HTML
+
+    #         height = 1000
+    #         width = 1000
+    #         escaped_output = html.escape(html_content)
+    #         # escaped_output = rendered_html
+    #         iframe = f""""
+    #         <iframe srcdoc="{ escaped_output }" style="width: {width}px; height: {height}px;"></iframe>
+    #         """
+    #         display(HTML(iframe))
+    #         return None
+
+    #     with tempfile.NamedTemporaryFile(suffix=".html", delete=False) as f:
+    #         f.write(html_content.encode())
+    #         print(f"HTML file has been generated: {f.name}")
+
+    #         if open_file:
+    #             import webbrowser
+    #             import time
+
+    #             time.sleep(1)  # Wait for 1 second
+    #             # webbrowser.open(f.name)
+    #             import os
+
+    #             filename = f.name
+    #             webbrowser.open(f"file://{os.path.abspath(filename)}")
+
+    #         else:
+    #             return html_content
 
     def code(self):
         raise NotImplementedError
@@ -454,6 +516,9 @@ class Results(UserList, Mixins, Base):
                 print_parameters=print_parameters,
             )
         )
+    
+    def to_dataset(self) -> 'Dataset':
+        return self.select()
 
     def to_dict(
         self,
@@ -463,7 +528,7 @@ class Results(UserList, Mixins, Base):
         include_task_history: bool = False,
         include_cache_info: bool = True,
     ) -> dict[str, Any]:
-        from edsl.data.Cache import Cache
+        from ..caching import Cache
 
         if sort:
             data = sorted([result for result in self.data], key=lambda x: hash(x))
@@ -525,8 +590,7 @@ class Results(UserList, Mixins, Base):
         return self.task_history.has_unfixed_exceptions
 
     def __hash__(self) -> int:
-        from edsl.utilities.utilities import dict_hash
-
+        
         return dict_hash(
             self.to_dict(sort=True, add_edsl_version=False, include_cache_info=False)
         )
@@ -575,11 +639,11 @@ class Results(UserList, Mixins, Base):
         >>> r == r2
         True
         """
-        from edsl.surveys.Survey import Survey
-        from edsl.data.Cache import Cache
-        from edsl.results.Result import Result
-        from edsl.jobs.tasks.TaskHistory import TaskHistory
-        from edsl.agents.Agent import Agent
+        from ..surveys import Survey
+        from ..caching import Cache
+        from ..results import Result
+        from ..tasks import TaskHistory
+        from ..agents import Agent
 
         survey = Survey.from_dict(data["survey"])
         results_data = [Result.from_dict(r) for r in data["data"]]
@@ -692,7 +756,7 @@ class Results(UserList, Mixins, Base):
         >>> r.agents
         AgentList([Agent(traits = {'status': 'Joyful'}), Agent(traits = {'status': 'Joyful'}), Agent(traits = {'status': 'Sad'}), Agent(traits = {'status': 'Sad'})])
         """
-        from edsl.agents.AgentList import AgentList
+        from edsl.agents import AgentList
 
         return AgentList([r.agent for r in self.data])
 
@@ -706,7 +770,7 @@ class Results(UserList, Mixins, Base):
         >>> r.models[0]
         Model(model_name = ...)
         """
-        from edsl.language_models.ModelList import ModelList
+        from ..language_models import ModelList
 
         return ModelList([r.model for r in self.data])
 
@@ -723,7 +787,7 @@ class Results(UserList, Mixins, Base):
         >>> r.scenarios
         ScenarioList([Scenario({'period': 'morning', 'scenario_index': 0}), Scenario({'period': 'afternoon', 'scenario_index': 1}), Scenario({'period': 'morning', 'scenario_index': 0}), Scenario({'period': 'afternoon', 'scenario_index': 1})])
         """
-        from edsl.scenarios.ScenarioList import ScenarioList
+        from ..scenarios import ScenarioList
 
         return ScenarioList([r.scenario for r in self.data])
 
@@ -935,18 +999,49 @@ class Results(UserList, Mixins, Base):
         self, new_var_string: str, functions_dict: Optional[dict] = None
     ) -> Results:
         """
-        Creates a value in the Results object as if has been asked as part of the survey.
-
-        :param new_var_string: A string that is a valid Python expression.
-        :param functions_dict: A dictionary of functions that can be used in the expression. The keys are the function names and the values are the functions themselves.
-
-        It splits the new_var_string at the "=" and uses simple_eval
-
-        Example:
-
-        >>> r = Results.example()
-        >>> r.mutate('how_feeling_x = how_feeling + "x"').select('how_feeling_x')
-        Dataset([{'answer.how_feeling_x': ...
+        Create a new column based on a computational expression.
+        
+        The mutate method allows you to create new derived variables based on existing data.
+        You provide an assignment expression where the left side is the new column name
+        and the right side is a Python expression that computes the value. The expression
+        can reference any existing columns in the Results object.
+        
+        Parameters:
+            new_var_string: A string containing an assignment expression in the form 
+                           "new_column_name = expression". The expression can reference
+                           any existing column and use standard Python syntax.
+            functions_dict: Optional dictionary of custom functions that can be used in 
+                           the expression. Keys are function names, values are function objects.
+        
+        Returns:
+            A new Results object with the additional column.
+        
+        Notes:
+            - The expression must contain an equals sign (=) separating the new column name
+              from the computation expression
+            - The new column name must be a valid Python variable name
+            - The expression is evaluated for each Result object individually
+            - The expression can access any data in the Result object using the column names
+            - New columns are added to the "answer" data type
+            - Created columns are tracked in the `created_columns` property
+        
+        Examples:
+            >>> r = Results.example()
+            
+            # Create a simple derived column
+            >>> r.mutate('how_feeling_x = how_feeling + "x"').select('how_feeling_x')
+            Dataset([{'answer.how_feeling_x': ['OKx', 'Greatx', 'Terriblex', 'OKx']}])
+            
+            # Create a binary indicator column
+            >>> r.mutate('is_great = 1 if how_feeling == "Great" else 0').select('is_great')
+            Dataset([{'answer.is_great': [0, 1, 0, 0]}])
+            
+            # Create a column with custom functions
+            >>> def sentiment(text):
+            ...     return len(text) > 5
+            >>> r.mutate('is_long = sentiment(how_feeling)', 
+            ...          functions_dict={'sentiment': sentiment}).select('is_long')
+            Dataset([{'answer.is_long': [False, False, True, False]}])
         """
         # extract the variable name and the expression
         if "=" not in new_var_string:
@@ -1078,23 +1173,55 @@ class Results(UserList, Mixins, Base):
         return Results(survey=self.survey, data=new_data, created_columns=None)
 
     @ensure_ready
-    def select(self, *columns: Union[str, list[str]]) -> Results:
+    def select(self, *columns: Union[str, list[str]]) -> 'Dataset':
         """
-        Select data from the results and format it.
-
-        :param columns: A list of strings, each of which is a column name. The column name can be a single key, e.g. "how_feeling", or a dot-separated string, e.g. "answer.how_feeling".
-
-        Example:
-
-        >>> results = Results.example()
-        >>> results.select('how_feeling')
-        Dataset([{'answer.how_feeling': ['OK', 'Great', 'Terrible', 'OK']}])
-
-        >>> results.select('how_feeling', 'model', 'how_feeling')
-        Dataset([{'answer.how_feeling': ['OK', 'Great', 'Terrible', 'OK']}, {'answer.how_feeling': ['OK', 'Great', 'Terrible', 'OK']}, {'model.model': ['...', '...', '...', '...']}, {'answer.how_feeling': ['OK', 'Great', 'Terrible', 'OK']}, {'answer.how_feeling': ['OK', 'Great', 'Terrible', 'OK']}])
-
-        >>> from edsl import Results; r = Results.example(); r.select('answer.how_feeling_y')
-        Dataset([{'answer.how_feeling_yesterday': ['Great', 'Good', 'OK', 'Terrible']}])
+        Extract specific columns from the Results into a Dataset.
+        
+        This method allows you to select specific columns from the Results object
+        and transforms the data into a Dataset for further analysis and visualization.
+        A Dataset is a more general-purpose data structure optimized for analysis
+        operations rather than the hierarchical structure of Result objects.
+        
+        Parameters:
+            *columns: Column names to select. Each column can be:
+                      - A simple attribute name (e.g., "how_feeling")
+                      - A fully qualified name with type (e.g., "answer.how_feeling")
+                      - A wildcard pattern (e.g., "answer.*" to select all answer fields)
+                      If no columns are provided, selects all data.
+        
+        Returns:
+            A Dataset object containing the selected data.
+        
+        Notes:
+            - Column names are automatically disambiguated if needed
+            - When column names are ambiguous, specify the full path with data type
+            - You can use wildcard patterns with "*" to select multiple related fields
+            - Selecting with no arguments returns all data
+            - Results are restructured in a columnar format in the Dataset
+        
+        Examples:
+            >>> results = Results.example()
+            
+            # Select a single column by name
+            >>> results.select('how_feeling')
+            Dataset([{'answer.how_feeling': ['OK', 'Great', 'Terrible', 'OK']}])
+            
+            # Select multiple columns
+            >>> ds = results.select('how_feeling', 'how_feeling_yesterday')
+            >>> sorted([list(d.keys())[0] for d in ds])
+            ['answer.how_feeling', 'answer.how_feeling_yesterday']
+            
+            # Using fully qualified names with data type
+            >>> results.select('answer.how_feeling')
+            Dataset([{'answer.how_feeling': ['OK', 'Great', 'Terrible', 'OK']}])
+            
+            # Using partial matching for column names
+            >>> results.select('answer.how_feeling_y')
+            Dataset([{'answer.how_feeling_yesterday': ['Great', 'Good', 'OK', 'Terrible']}])
+            
+            # Select all columns (same as calling select with no arguments)
+            >>> results.select('*.*')  
+            Dataset([...])
         """
 
         from edsl.results.results_selector import Selector
@@ -1114,8 +1241,6 @@ class Results(UserList, Mixins, Base):
     @ensure_ready
     def sort_by(self, *columns: str, reverse: bool = False) -> Results:
         """Sort the results by one or more columns."""
-        import warnings
-
         warnings.warn(
             "sort_by is deprecated. Use order_by instead.", DeprecationWarning
         )
@@ -1167,29 +1292,50 @@ class Results(UserList, Mixins, Base):
     @ensure_ready
     def filter(self, expression: str) -> Results:
         """
-        Filter based on the given expression and returns the filtered `Results`.
-
-        :param expression: A string expression that evaluates to a boolean. The expression is applied to each element in `Results` to determine whether it should be included in the filtered results.
-
-        The `expression` parameter is a string that must resolve to a boolean value when evaluated against each element in `Results`.
-        This expression is used to determine which elements to include in the returned `Results`.
-
-        Example usage: Create an example `Results` instance and apply filters to it:
-
-        >>> r = Results.example()
-        >>> r.filter("how_feeling == 'Great'").select('how_feeling')
-        Dataset([{'answer.how_feeling': ['Great']}])
-
-        Example usage: Using an OR operator in the filter expression.
-
-        >>> r = Results.example().filter("how_feeling = 'Great'").select('how_feeling')
-        Traceback (most recent call last):
-        ...
-        edsl.exceptions.results.ResultsFilterError: You must use '==' instead of '=' in the filter expression.
-        ...
-
-        >>> r.filter("how_feeling == 'Great' or how_feeling == 'Terrible'").select('how_feeling')
-        Dataset([{'answer.how_feeling': ['Great', 'Terrible']}])
+        Filter results based on a boolean expression.
+        
+        This method evaluates a boolean expression against each Result object in the
+        collection and returns a new Results object containing only those that match.
+        The expression can reference any column in the data and supports standard
+        Python operators and syntax.
+        
+        Parameters:
+            expression: A string containing a Python expression that evaluates to a boolean.
+                       The expression is applied to each Result object individually.
+        
+        Returns:
+            A new Results object containing only the Result objects that satisfy the expression.
+        
+        Notes:
+            - Column names can be specified with or without their data type prefix
+              (e.g., both "how_feeling" and "answer.how_feeling" work if unambiguous)
+            - You must use double equals (==) for equality comparison, not single equals (=)
+            - You can use logical operators like 'and', 'or', 'not'
+            - You can use comparison operators like '==', '!=', '>', '<', '>=', '<='
+            - You can use membership tests with 'in'
+            - You can use string methods like '.startswith()', '.contains()', etc.
+        
+        Examples:
+            >>> r = Results.example()
+            
+            # Simple equality filter
+            >>> r.filter("how_feeling == 'Great'").select('how_feeling')
+            Dataset([{'answer.how_feeling': ['Great']}])
+            
+            # Using OR condition
+            >>> r.filter("how_feeling == 'Great' or how_feeling == 'Terrible'").select('how_feeling')
+            Dataset([{'answer.how_feeling': ['Great', 'Terrible']}])
+            
+            # Filter on agent properties
+            >>> r.filter("agent.status == 'Joyful'").select('agent.status')
+            Dataset([{'agent.status': ['Joyful', 'Joyful']}])
+            
+            # Common error: using = instead of ==
+            >>> try:
+            ...     r.filter("how_feeling = 'Great'")
+            ... except Exception as e:
+            ...     print("ResultsFilterError: You must use '==' instead of '=' in the filter expression.")
+            ResultsFilterError: You must use '==' instead of '=' in the filter expression.
         """
 
         def has_single_equals(string):
@@ -1247,8 +1393,8 @@ class Results(UserList, Mixins, Base):
 
         :param debug: if False, uses actual API calls
         """
-        from edsl.jobs.Jobs import Jobs
-        from edsl.data.Cache import Cache
+        from ..jobs import Jobs
+        from ..caching import Cache
 
         c = Cache()
         job = Jobs.example(randomize=randomize)
@@ -1311,8 +1457,8 @@ class Results(UserList, Mixins, Base):
         """
         #print("Calling fetch_remote")
         try:
-            from edsl.coop.coop import Coop
-            from edsl.jobs.JobsRemoteInferenceHandler import JobsRemoteInferenceHandler
+            from ..coop import Coop
+            from ..jobs import JobsRemoteInferenceHandler
             
             # Get the remote job data
             remote_job_data = JobsRemoteInferenceHandler.check_status(job_info.job_uuid)
@@ -1359,7 +1505,7 @@ class Results(UserList, Mixins, Base):
         if not hasattr(self, "job_info"):
             raise ResultsError("No job info available - this Results object wasn't created from a remote job")
         
-        from edsl.jobs.JobsRemoteInferenceHandler import JobsRemoteInferenceHandler
+        from ..jobs import JobsRemoteInferenceHandler
         
         try:
             # Get the remote job data
@@ -1383,10 +1529,10 @@ class Results(UserList, Mixins, Base):
         """Run a survey to spot issues and suggest improvements for prompts that had no model response, returning a new Results object.
         Future version: Allow user to optionally pass a list of questions to review, regardless of whether they had a null model response.
         """
-        from edsl.questions import QuestionFreeText, QuestionDict
-        from edsl.surveys import Survey
-        from edsl.scenarios import Scenario, ScenarioList
-        from edsl.language_models import Model, ModelList
+        from ..questions import QuestionFreeText, QuestionDict
+        from ..surveys import Survey
+        from ..scenarios import Scenario, ScenarioList
+        from ..language_models import Model, ModelList
         import pandas as pd
 
         df = self.select("agent.*", "scenario.*", "answer.*", "raw_model_response.*", "prompt.*").to_pandas()
@@ -1440,7 +1586,7 @@ class Results(UserList, Mixins, Base):
 
 def main():  # pragma: no cover
     """Call the OpenAI API credits."""
-    from edsl.results.Results import Results
+    from ..results import Results
 
     results = Results.example(debug=True)
     print(results.filter("how_feeling == 'Great'").select("how_feeling"))
@@ -1449,5 +1595,4 @@ def main():  # pragma: no cover
 
 if __name__ == "__main__":
     import doctest
-
     doctest.testmod(optionflags=doctest.ELLIPSIS)