Comprehensive explicit docs on response for statistics endpoints

[mmnoo]

Hello,

It would be useful to have some detailed docs on what kind of response to expect from the statistics endpoints. For example what determines the property name 'b1' in the property path in this example? properties.statistics.b1 ?

Another value I have had to make assumptions about, but would prefer explicit definitions for is the properties.statistics.b1.percentile_<n> property. What does its value represent specifically? Im a programmer with strengths outside of statistics. Explicit definitions are helpful since someone like me might be prone to misunderstand similar but different concepts and miss data science nuances.

Thank you! 🙏

[vincentsarago]

Dear @mmnoo, We are always looking for improvement in our documentation but documenting all model is a tedious task I personally didn't had time to do.

. For example what determines the property name 'b1' in the property path in this example? properties.statistics.b1 ?

The name b1 mean band number 1 and comes from the default band name notation in rio-tiler https://github.com/cogeotiff/rio-tiler/blob/main/rio_tiler/reader.py#L268 https://github.com/cogeotiff/rio-tiler/blob/main/rio_tiler/models.py#L341-L344

Another value I have had to make assumptions about, but would prefer explicit definitions for is the properties.statistics.b1.percentile_ property

A user can ask for multiple percentile values but it default to percentile 2 and 98 which is why when no user input there will be 2 percentile_2 and percentile_98 entry for each band statistics.

rio-tiler docs: https://cogeotiff.github.io/rio-tiler/models/#bandstatistics / https://github.com/cogeotiff/rio-tiler/blob/main/rio_tiler/utils.py#L35-L84

We could add an example response in the OpenAPI (https://fastapi.tiangolo.com/advanced/additional-responses/#combining-information)

Hope it helps, and I'll be more than happy to review any contribution 🙏