Add fluent interface pattern as teaching example

No se nombra ningún archivo de destino ni ejercicio existente. Empieza por localizar la sección del curso donde se enseñan ejemplos de diseño de API o de plotting y, después, revisa su formato y las lecciones adyacentes. Se considera terminado cuando se añada una sección didáctica o un ejercicio que presente los patrones enumerados y las compensaciones entre su descubribilidad, seguridad de tipos, componibilidad, compatibilidad y curva de aprendizaje.

Add a section or exercise covering API design patterns for simplifying functions with many parameters.

Good reference example: https://github.com/DHI/modelskill/discussions/492 — the scatter() function has grown a long signature:

def scatter(
    x: np.ndarray,
    y: np.ndarray,
    *,
    bins: int | float = 120,
    quantiles: int | Sequence[float] | None = None,
    fit_to_quantiles: bool = False,
    show_points: bool | int | float | None = None,
    show_hist: Optional[bool] = None,
    show_density: Optional[bool] = None,
    norm: Optional[colors.Normalize] = None,
    backend: Literal["matplotlib", "plotly"] = "matplotlib",
    figsize: Tuple[float, float] = (8, 8),
    xlim: Optional[Tuple[float, float]] = None,
    ylim: Optional[Tuple[float, float]] = None,
    reg_method: str | bool = "ols",
    title: str = "",
    xlabel: str = "",
    ylabel: str = "",
    skill_table: Optional[str | Sequence[str] | Mapping[str, str] | bool] = False,
    skill_scores: Mapping[str, float] | None = None,
    skill_score_unit: Optional[str] = "",
    ax: Optional[Axes] = None,
    **kwargs,
) -> Axes:

Alternative patterns to simplify

1. Fluent interface (method chaining)

Each component gets its own method. Easy to add/remove parts.

(Comparer(x, y)
 .plot()
 .scatter(alpha=0.5)
 .qq([0.05, 0.5, 0.75, 0.95])
# .reg_line(equation=True)
 .skill_table(("n", "bias"))
).show()

2. Configuration objects (dataclasses)

Group related parameters into typed config objects.

@dataclass
class ScatterStyle:
    bins: int = 120
    show_points: bool = True
    show_density: bool = False
    norm: colors.Normalize | None = None

@dataclass
class Layout:
    figsize: tuple[float, float] = (8, 8)
    xlim: tuple[float, float] | None = None
    ylim: tuple[float, float] | None = None
    title: str = ""
    xlabel: str = ""
    ylabel: str = ""

scatter(x, y, style=ScatterStyle(bins=50), layout=Layout(title="My plot"))

3. Presets / named styles

Offer common configurations as named presets, with overrides.

scatter(x, y, preset="minimal")              # just points + 1:1 line
scatter(x, y, preset="full")                 # density + qq + regression + skill table
scatter(x, y, preset="presentation")         # large fonts, clean layout
scatter(x, y, preset="minimal", title="Hm0") # preset + override

4. Composition of small functions

Instead of one function that does everything, provide building blocks that work with a standard Axes.

fig, ax = plt.subplots()
plot_scatter(ax, x, y, show_density=True)
plot_qq(ax, x, y, quantiles=[0.25, 0.5, 0.75])
plot_reg_line(ax, x, y)
add_skill_table(ax, x, y, metrics=["bias", "rmse"])

Each pattern has trade-offs worth discussing: discoverability, type safety, composability, backwards compatibility, learning curve.

Relevant topics: method chaining, Self return type, builder pattern, dataclasses as config, API design trade-offs.