def __delitem__(self, index: int) -> None:
    """Allows deleting an item from 'values' if it's a list or ndarray."""
    if isinstance(self.values, list):
        del self.values[index]
    elif isinstance(self.values, np.ndarray):
        self.values = np.delete(self.values, index, axis=0)
    else:
        raise TypeError(f"Deletion by index not supported for type {type(self.values)}")

def __getitem__(self, key):
    """Allow dictionary-style access or integer indexing into values."""
    if isinstance(key, int):
        if isinstance(self.values, np.ndarray | list):
            return self.values[key]
        if isinstance(self.values, pl.DataFrame):
            return self.values[key]
        if isinstance(self.values, (np.float64 | UFloat)) and key == 0:
            return self.values
        raise IndexError(
            f"Index {key} out of range or type {type(self.values)} not directly indexable."
        )
    return self.to_dict()[key]

def __iter__(self) -> Iterator[Any]:
    """Allows iteration over the 'values' attribute."""
    if isinstance(self.values, np.ndarray | list):
        return iter(self.values)
    elif isinstance(self.values, pl.DataFrame):
        return iter(self.values.iter_rows())
    elif isinstance(self.values, np.float64 | UFloat):
        return iter([self.values])
    raise TypeError(f"Iteration not supported for type {type(self.values)}")

def __len__(self) -> int:
    if isinstance(self.values, np.ndarray | list):
        return len(self.values)
    elif isinstance(self.values, np.float64 | UFloat):
        return 1
    elif isinstance(self.values, pl.DataFrame):
        return self.values.height  # Number of rows
    return 0  # Default for unknown types

def __repr__(self) -> str:
    """Detailed representation of the measurement result.

    For backward compatibility with tests, this matches __str__ behavior.
    In typical libraries, repr would show construction details instead.
    """
    return self.__str__()

def __str__(self) -> str:
    """String representation of the measurement result.

    For backward compatibility with tests, returns a newline-separated list for arrays.
    For other types, uses a more descriptive representation.
    """
    if isinstance(self.values, UFloat):
        return f"{self.values} {self.units}"
    elif isinstance(self.values, np.float64):
        return f"{self.values} {self.units}"
    elif isinstance(self.values, pl.DataFrame):
        return str(self.values)
    elif isinstance(self.values, np.ndarray):
        # For numpy arrays, handle 1D arrays specially for backward compatibility
        if self.values.ndim == 1:
            return "\n".join([f"{val} {self.units}" for val in self.values])
        # For multi-dimensional arrays, provide a concise representation
        return (
            f"NumPy Array (shape: {self.values.shape}, dtype: {self.values.dtype}) {self.units}"
        )
    elif isinstance(self.values, list):
        # For lists, special handling for backward compatibility
        if all(isinstance(x, int | float) for x in self.values):
            return "\n".join([f"{val} {self.units}" for val in self.values])
        # For lists with mixed types or nested lists, show first few items if long
        if len(self.values) > 5:
            return f"List (first 5 of {len(self.values)}): {self.values[:5]}... {self.units}"
        return f"List: {self.values} {self.units}"

    # Fallback for other types
    return f"Values: {str(self.values)[:100]}... Type: {type(self.values)} {self.units}"

def add(self, value: Any) -> None:
    """Adds a new value to the collection. Behavior depends on self.values type."""
    if isinstance(self.values, np.ndarray):
        # This might be inefficient for frequent additions. Consider list then convert.
        self.values = np.append(self.values, value)
    elif isinstance(self.values, list):
        self.values.append(value)
    elif isinstance(self.values, np.float64):
        # Convert to list or ndarray if adding to a single float
        self.values = np.array([self.values, value])
        print("Warning: Added value to np.float64, converted 'values' to np.ndarray.")
    elif isinstance(self.values, UFloat):
        # If current value is UFloat, adding another value implies creating a list/array of UFloats
        self.values = [self.values, value]
        print(
            "Warning: Added value to UFloat, converted 'values' to a list. Consider using a list of UFloats initially."
        )
    elif isinstance(self.values, pl.DataFrame):
        # Appending to Polars DataFrame is complex; typically done by creating a new DF and vstacking.
        # This simple 'add' might not be suitable.
        raise NotImplementedError(
            "Direct 'add' to Polars DataFrame not supported. Use 'set_values' or manage DataFrame externally."
        )
    else:
        raise TypeError(f"Cannot 'add' to type {type(self.values)}")

def clear(self) -> None:
    """Clears all the MeasurementValues from the collection, resetting to an empty/default state."""
    if isinstance(self.values, np.ndarray):
        self.values = np.array([])
    elif isinstance(
        self.values, (np.float64 | UFloat)
    ):  # Reset UFloat to a default float or ufloat(0,0)
        self.values = np.float64(0.0)  # Or ufloat(0,0) if preferred default for UFloat
    elif isinstance(self.values, pl.DataFrame):
        self.values = pl.DataFrame()
    elif isinstance(self.values, list):
        self.values = []
    else:  # Fallback for unknown types, attempt to set to a default float64
        print(
            f"Warning: Clearing unknown type {type(self.values)}, setting to np.float64(0.0)."
        )
        self.values = np.float64(0.0)

def get(self, index: int) -> Any:
    """Gets the MeasurementValue at a specified index. Assumes indexable values."""
    if isinstance(self.values, np.ndarray | list):
        return self.values[index]
    elif isinstance(self.values, pl.DataFrame):
        # For DataFrame, 'get' by index might mean row.
        # This returns a new DataFrame with one row.
        return self.values[index]
    elif isinstance(self.values, (np.float64 | UFloat)) and index == 0:
        return self.values
    raise IndexError(
        f"Index {index} out of range or type {type(self.values)} not directly indexable by single int."
    )

def get_all(self) -> np.ndarray | pl.DataFrame | np.float64 | list[Any] | UFloat:
    """Returns all the MeasurementValues in the collection."""
    return self.values

def items(self):
    """Return items for dict-like behavior."""
    return self.to_dict().items()

def keys(self):
    """Return the keys for dict-like behavior."""
    return self.to_dict().keys()

def perform_fft(self) -> MeasurementResult:
    """Perform Fast Fourier Transform on the measurement data.

    Requires:
    - self.values to be a numpy array of time-domain data
    - self.sampling_rate to be set (in Hz)

    Returns:
        A new MeasurementResult containing the FFT data, with frequency in Hz
        and magnitude in the same units as the original data.
    """
    if self.sampling_rate is None:
        raise ValueError("Sampling rate must be set to perform FFT")

    if not isinstance(self.values, np.ndarray):
        raise TypeError(f"FFT requires numpy array, got {type(self.values)}")

    # Ensure we're working with a 1D array
    values = self.values.flatten() if self.values.ndim > 1 else self.values

    # Perform FFT
    fft_values = np.fft.rfft(values)
    fft_magnitude = np.abs(fft_values)

    # Create frequency axis
    freqs = np.fft.rfftfreq(len(values), 1 / self.sampling_rate)

    # Create result with frequency and magnitude
    result_df = pl.DataFrame({"frequency": freqs, "magnitude": fft_magnitude})

    return MeasurementResult(
        values=result_df,
        instrument=self.instrument,
        units=self.units,
        measurement_type="FFT",
        timestamp=time.time(),
        original_type=self.measurement_type,
        sampling_rate=self.sampling_rate,
    )

def plot(self, spec: PlotSpec | None = None, **kwargs):
    """
    Plot this measurement result.

    - If values is a Polars DataFrame, plots columns per PlotSpec.
    - If values is a 1D numpy array, uses plot_ndarray; honors sampling_rate and units.
    - If values is a scalar/list, attempts to plot as 1D series.

    Args:
        spec: Optional PlotSpec. If not provided, built from kwargs.
        **kwargs: Fields for PlotSpec.

    Returns:
        A matplotlib Figure object.
    """
    import numpy as np  # local import
    import polars as pl  # local import

    from ..plotting import PlotSpec  # noqa: E402
    from ..plotting import plot_dataframe  # noqa: E402
    from ..plotting import plot_ndarray  # noqa: E402

    pspec = spec or (PlotSpec(**kwargs) if kwargs else PlotSpec())

    if isinstance(self.values, pl.DataFrame):
        # If ylabel not provided and a single numeric y is chosen, prefer units
        if pspec.ylabel is None:
            try:
                # The helper will set y label to the series name by default; we can override
                pspec = PlotSpec(
                    kind=pspec.kind,
                    title=pspec.title or self.measurement_type,
                    x=pspec.x,
                    y=pspec.y,
                    xlabel=pspec.xlabel,
                    ylabel=self.units if self.units else pspec.ylabel,
                    legend=pspec.legend,
                    grid=pspec.grid,
                )
            except Exception:
                pass
        return plot_dataframe(self.values, pspec)

    # Convert scalar/list to numpy array for plotting
    arr: np.ndarray
    if isinstance(self.values, np.ndarray):
        arr = self.values
    elif isinstance(self.values, list):
        arr = np.asarray(self.values)
    else:
        arr = np.asarray([self.values])

    if arr.ndim != 1:
        raise ValueError("Only 1D arrays are supported for simple plotting in Phase 1.")

    title = pspec.title or self.measurement_type
    pspec = PlotSpec(
        kind=pspec.kind,
        title=title,
        x=pspec.x,
        y=pspec.y,
        xlabel=pspec.xlabel,
        ylabel=self.units or pspec.ylabel,
        legend=pspec.legend,
        grid=pspec.grid,
    )
    return plot_ndarray(arr, pspec, sampling_rate=self.sampling_rate, units=self.units)

def save(self, path: str) -> None:
    """Saves the measurement data to a file.

    If the data is a numpy array, it will be saved as a .npy file.
    If the data is a Polars DataFrame, it will be saved as a .parquet file.
    Other list-like data will be converted to numpy array and saved as .npy.
    np.float64 will be saved as a 0-D numpy array.
    UFloat objects will be saved as a two-element numpy array [nominal, std_dev] in a .npy file.
    """
    default_ext = ".npy"
    if isinstance(self.values, pl.DataFrame):
        default_ext = ".parquet"

    if not path.endswith((".npy", ".parquet")):
        path += default_ext
        print(f"Warning: File extension not specified. Saving as {path}")

    if isinstance(self.values, np.ndarray):
        np.save(path, self.values)
    elif isinstance(self.values, pl.DataFrame):
        if not path.endswith(".parquet"):
            print(
                f"Warning: Saving Polars DataFrame to non-parquet file '{path}'. Consider using .parquet for DataFrames."
            )
        self.values.write_parquet(path)
    elif isinstance(self.values, UFloat):
        if not path.endswith(".npy"):
            print(f"Warning: Saving UFloat to non-npy file '{path}'. Consider using .npy.")
        np.save(path, np.array([self.values.nominal_value, self.values.std_dev]))
    elif isinstance(self.values, list | np.float64):  # Convert list or float64 to ndarray
        if not path.endswith(".npy"):
            print(
                f"Warning: Saving {type(self.values).__name__} to non-npy file '{path}'. Consider using .npy."
            )
        np.save(path, np.array(self.values))
    else:
        raise TypeError(
            f"Unsupported data type for saving: {type(self.values)}. Can save np.ndarray, pl.DataFrame, list, np.float64, or UFloat."
        )
    print(f"Measurement saved to {path}")

def set_values(
    self, values: np.ndarray | pl.DataFrame | np.float64 | list[Any] | UFloat | float
) -> None:
    """Sets the MeasurementValues in the collection."""
    if isinstance(values, float) and not isinstance(values, np.floating):
        values = np.float64(values)
    self.values = cast(np.ndarray | pl.DataFrame | np.float64 | list[Any] | UFloat, values)

def to_dict(self) -> dict[str, Any]:
    """Convert MeasurementResult to a dict for DataFrame conversion.

    This allows MeasurementResult objects to be directly used in Experiment.add_trial.
    """
    if isinstance(self.values, pl.DataFrame):
        # If values is already a DataFrame, convert to dict representation
        result = {}
        for col in self.values.columns:
            result[col] = self.values[col].to_list()
        return result
    elif isinstance(self.values, np.ndarray | list):
        # Convert array or list to a dict with a 'values' key
        return {"values": self.values}
    elif isinstance(self.values, np.float64 | UFloat):
        # Convert scalar value to a dict with a 'value' key
        return {"value": self.values}
    else:
        # Default fallback
        return {"values": self.values}

def __iter__(self) -> Iterator[dict[str, Any]]:
    """Iterate over each trial (row) as a dictionary."""
    yield from self.data.to_dicts()

def __len__(self) -> int:
    """Return the number of trials."""
    return self.data.height

def __str__(self) -> str:
    """
    Return a string representation of the experiment.

    This includes a summary of the experiment details and prints the first 5 rows
    of the trial data (the head).
    """
    param_str = ", ".join(str(param) for param in self.parameters.values())
    head_data: pl.DataFrame | str
    if not self.data.is_empty():
        head_data = self.data.head(5)
    else:
        head_data = "No trial data available."

    return (
        f"Experiment: {self.name}\n"
        f"Description: {self.description}\n"
        f"Notes: {self.notes or 'No notes'}\n"
        f"Parameters: {param_str}\n"
        f"Trial Data (first 5 rows):\n{head_data}"
    )

def add_parameter(self, name: str, units: str, notes: str = "") -> None:
    """
    Add a new parameter to the experiment.

    Args:
        name (str): Name of the parameter.
        units (str): Units for the parameter.
        notes (str, optional): Additional notes.
    """
    self.parameters[name] = ExperimentParameter(name, units, notes)

def add_trial(
    self,
    measurement_result: pl.DataFrame | dict[str, Any] | list[Any] | MeasurementResult,
    **parameter_values: Any,
) -> None:
    """
    Add a new trial to the experiment.

    Accepts measurement data in various formats (list, dict, Polars DataFrame, or MeasurementResult)
    and converts it into a Polars DataFrame if needed. Additional parameter values
    are added as new columns.

    Args:
        measurement_result (Union[pl.DataFrame, Dict[str, Any], List[Any], MeasurementResult]): The measurement data.
        **parameter_values: Additional parameters to include with this trial.

    Raises:
        ValueError: If the conversion to a Polars DataFrame fails or if a
                    provided parameter is not defined.
    """
    trial_df: pl.DataFrame

    # Special handling for MeasurementResult objects
    if hasattr(measurement_result, "values") and hasattr(measurement_result, "to_dict"):
        # If it's a MeasurementResult, extract its values
        if isinstance(measurement_result.values, pl.DataFrame):
            trial_df = measurement_result.values
        else:
            # Convert to dict and then to DataFrame
            try:
                trial_df = pl.DataFrame(measurement_result.to_dict(), strict=False)
            except Exception as e:
                raise ValueError(
                    f"Failed to convert MeasurementResult to DataFrame: {e}"
                ) from e
    elif not isinstance(measurement_result, pl.DataFrame):
        try:
            trial_df = pl.DataFrame(measurement_result, strict=False)
        except Exception as e:
            raise ValueError(
                f"Failed to convert measurement_result to a Polars DataFrame: {e}"
            ) from e
    else:
        trial_df = measurement_result

    for param_name, value in parameter_values.items():
        if param_name not in self.parameters:
            raise ValueError(
                f"Parameter '{param_name}' is not defined in the experiment. Add it first using add_parameter()."
            )
        trial_df = trial_df.with_columns(pl.lit(value).alias(param_name))

    if self.data.is_empty():
        self.data = trial_df
    else:
        try:
            self.data = self.data.vstack(trial_df)
        except Exception as e:
            raise ValueError(
                f"Failed to stack new trial data. Check for schema compatibility. Error: {e}"
            ) from e

def list_trials(self) -> None:
    """Print the full trials DataFrame."""
    print(self.data)

def plot(self, spec: PlotSpec | None = None, **kwargs):
    """
    Plot the experiment's data using the lightweight plotting layer.

    Args:
        spec: Optional PlotSpec. If not provided, a PlotSpec is built from kwargs.
        **kwargs: Convenience fields for PlotSpec (e.g., kind, x, y, title, xlabel, ylabel, legend, grid).

    Returns:
        A matplotlib Figure object.
    """
    # Local import to keep plotting optional and to avoid import cycles at module import time
    from ..plotting import PlotSpec  # noqa: E402
    from ..plotting import plot_dataframe  # noqa: E402

    if self.data.is_empty():
        raise ValueError("Experiment has no data to plot.")

    spec_to_use = spec or (PlotSpec(**kwargs) if kwargs else PlotSpec())
    return plot_dataframe(self.data, spec_to_use)

def save_parquet(self, file_path: str) -> None:
    """
    Save the internal Polars DataFrame as a Parquet file.

    Args:
        file_path (str): The file path (including filename) where the Parquet file will be saved.
    """
    self.data.write_parquet(file_path)
    print(f"Data saved to Parquet file at: {file_path}")