DOC: Pandas Case_When

[MesumRaza]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/docs/dev/reference/api/pandas.Series.case_when.html

Documentation problem

The example provide is not intuitive.

Suggested fix for documentation

I found the example of pd.Series.case_when very non intuitive hence here is the updated example

Examples
--------
>>> # Real-world example: Updating product prices based on a dynamic pricing strategy
>>> current_prices = pd.Series([50, 75, 100, 120], name='current_prices')
>>> demand_forecast = pd.Series([100, 80, 50, 120], name='demand_forecast')

    >>> # Conditions for price adjustments based on demand forecast
    >>> conditions = [
    ...     (demand_forecast > 90, current_prices * 1.2),  # Increase by 20% for high demand
    ...     (demand_forecast < 60, current_prices * 0.8),  # Decrease by 20% for low demand
    ...     (current_prices > 100, current_prices * 0.95)   # Apply a 5% discount for high-priced items
    ... ]

    >>> # Applying the dynamic pricing strategy
    >>> updated_prices = current_prices.case_when(caselist=conditions)
    >>> updated_prices
    0     60.0
    1     75.0
    2     80.0
    3    114.0
    Name: current_prices, dtype: float64

[rhshadrach]

Thanks for the suggestion.

The example provide is not intuitive.

Can you expand on this?

[VladimirFokow]

I think the minimal example in the docs is good - because it is the simplest case, intended to demonstrate the mechanics as clearly as possible.

That said, for me another example - with the application of this method - would be also good to have. But perhaps even better to have - would be a reference to np.select - because I didn't get it at first, but essentially it's like np.select, right? - just for a Series (and in-place ?). Can there be a reference to np.select in "See also", or is linking to methods outside of pandas prohibited?

Some additional thoughts on improving that page:

• good: It gives an example where both a and b compete for the .gt(0), but bad: the order of dominance isn't described explicitly with words (as I understood, the higher replacement (closer to the start of the list) dominates in case of collisions). But since this isn't stated clearly, maybe there is some other logic of dominance..

• purpose of , name='c' isn't clear.. Is this required? If not, why not remove it to have less confusion

• returns this series edited in place, or a new series?

[mroeschke]

Seems like the example is OK so closing