ENH: add a gradient map to background gradient
State: closed

closes #22727
closes #28901
- [x] tests added / passed
- [x] Ensure all linting tests pass, see [here](https://pandas.pydata.org/pandas-docs/dev/development/contributing.html#code-standards) for how to run them
- [x] whatsnew entry

A very minor extension to the code and adding one argument gives the function a lot more scope:

![Screen Shot 2021-02-20 at 14 04 14](https://user-images.githubusercontent.com/24256554/108596326-a0779180-7384-11eb-97f5-60ea0a23bda1.png)



Labels:
name: Enhancement
name: Styler
description: conditional formatting using DataFrame.style

Comments:
> conceptually i guess is ok, but this function is getting now a lot of arguments, If gmap _does_ not interact with the other arguments, then i thin a separate function would be better here.

For working with color gradients it is quite common to have a gradient map as an input, for example if you have text, or non-quantitative data. I think a second function would repeat a lot of code and a lot of documentation, since you would still want, `low` `high` `vmin` `vmax` and `text_threshold`.

Edit: I was also, later, going to propose a `text_gradient` as well as `background_gradient` (which colors text instead of cell background). Then I don't think you want 4 methods instead of 2, each with a `gmap` arg. 
I'm interested in this feature (I've struggled with stylers having to apply to the data in the df, not some transform of it). I'm not convinced by the name `gmap`. It doesn't map anything, it replaces; and `g` does not need mentioning.

I think what you mean by the parameter is "surrogate data to use as the gradient function"; indeed, the underlying data is forgotten when a gmap is used. I'd most likely call this parameter `values`, but generally think it could do with some thought.

I also note that a future iteration might allow `gmap` (or whatever) to be a callable, enabling application to more generic dataframes.
> I'm interested in this feature (I've struggled with stylers having to apply to the data in the df, not some transform of it). I'm not convinced by the name `gmap`. It doesn't map anything, it replaces; and `g` does not need mentioning.

I understand it to be the map used to render the `cmap` (color map), as opposed to using the data as the map. I naturally used `gmap` because gradient map appears in other visual editor software [photoshop](https://enviragallery.com/guide-to-gradient-maps-in-photoshop/#:~:text=Gradient%20maps%20are%20a%20Photoshop,the%20end%20replaces%20your%20highlights.) or [Maya](https://vimeo.com/67556624), the `g` was to better distinguish from `c`. Sometimes in other software what is called the `cmap` here can be called the gradient map otherwise! The function is called `background_gradient` so having a gradient map also seemed natural.

That said, I'm not tied to it. If @jreback agrees (or anyone else) I will happily change the name, to a new suggestion.

> I also note that a future iteration might allow gmap (or whatever) to be a callable, enabling application to more generic dataframes.

I agree with you on this. I hadn't thought of this or of a use case yet, and it would just complicate the PR so best to leave out initially I think.
@jreback pinging have merged master. this is greenish - test failure of ipython directive is unrelated.
@jreback finally got full green on this, and have merged all the recent typing changes in. hopefully we can finalise this and then the refactor
thanks @attack68 very nice!