commonMain.org.jetbrains.letsPlot.scale.Manual.kt Maven / Gradle / Ivy
The newest version!
/*
* Copyright (c) 2021. JetBrains s.r.o.
* Use of this source code is governed by the MIT license that can be found in the LICENSE file.
*/
package org.jetbrains.letsPlot.scale
import org.jetbrains.letsPlot.core.spec.Option
import org.jetbrains.letsPlot.core.plot.base.Aes
import org.jetbrains.letsPlot.intern.Options
import org.jetbrains.letsPlot.intern.Scale
/**
* Creates your own discrete scale for the specified aesthetics.
*
* @param aesthetic Aesthetic or a list of aesthetics that this scale works with.
* @param values List of Strings (encoding colors) or color values.
* A set of aesthetic values to map data values to.
* Values will be matched with the limits of the scale (if specified).
* @param name The name of the scale - used as the axis label or the legend title.
* If null, the default, the name of the scale is taken from the first mapping used for that aesthetic.
* @param breaks A list of data values specifying the positions of ticks,
* or a dictionary which maps the tick labels to the breaks values.
* @param labels A list of labels on ticks, or a dictionary which maps the breaks values to the tick labels.
* @param lablim The maximum label length (in characters) before trimming is applied.
* @param limits Continuous scale: a numeric vector of length two providing limits of the scale.
* Discrete scale: a vector specifying the data range for the scale and the default order of their display in guides.
* @param naValue An aesthetic value which is used when data in not available.
* @param format Specifies the format pattern for labels on the scale.
* @param guide Guide to use for this scale.
* It can either be a string ("colorbar", "legend") or a call to a guide function (`guideColorbar()`, `guideLegend()`)
* specifying additional arguments.
* "none" will hide the guide.
*
* Format patterns in the `format` parameter can be just a number format (like "d") or
* a string template where number format is surrounded by curly braces: "{d} cylinders".
* Note: the "$" must be escaped as "\$".
* For more info see: [formats.html](https://lets-plot.org/kotlin/formats.html)
*
* Examples:
* - ".2f" -> "12.45"
* - "Score: {.2f}" -> "Score: 12.45"
* - "Score: {}" -> "Score: 12.454789"
*
*/
fun scaleManual(
aesthetic: Any,
values: Any,
name: String? = null,
breaks: Any? = null,
labels: Any? = null,
lablim: Int? = null,
limits: List? = null,
naValue: Any? = null,
format: String? = null,
guide: Any? = null
): Scale {
var newBreaks = breaks
val newValues: List? = when (values) {
is Map<*, *> -> {
if (breaks == null && limits == null) {
newBreaks = values.keys.toList()
values.values
} else {
val baseOrderList = when (val base = limits ?: breaks) {
is Map<*, *> -> base.values
is List<*> -> base
else -> null
}
val newValues = baseOrderList?.mapNotNull { values[it] }
if (!newValues.isNullOrEmpty()) {
val noMatchValues = values.values.filter { it !in newValues }
newValues + noMatchValues
} else {
null
}
}
}
is List<*> -> values
else -> error("The scale 'values' parameter should be specified with a list or dictionary.")
}?.let { list ->
require(list.all { it != null }) { "'values' is non-nullable list, but was: $list" }
list.map { v -> v as Any }
}
return Scale(
aesthetic = aesthetic,
name = name,
breaks = newBreaks,
labels = labels,
lablim = lablim,
limits = limits,
naValue = naValue,
format = format,
guide = guide,
otherOptions = Options(
mapOf(
Option.Scale.OUTPUT_VALUES to newValues
)
)
)
}
/**
* Creates your own discrete scale for `color` aesthetic.
*
* ## Examples
*
* - [error_bars.ipynb](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/error_bars.ipynb)
*
* @param values List of Strings (encoding colors) or color values.
* A set of aesthetic values to map data values to.
* Values will be matched with the limits of the scale (if specified).
* @param name The name of the scale - used as the axis label or the legend title. If null, the default, the name of the scale
* is taken from the first mapping used for that aesthetic.
* @param breaks A list of data values specifying the positions of ticks,
* or a dictionary which maps the tick labels to the breaks values.
* @param labels A list of labels on ticks, or a dictionary which maps the breaks values to the tick labels.
* @param lablim The maximum label length (in characters) before trimming is applied.
* @param limits Continuous scale: a numeric vector of length two providing limits of the scale.
* Discrete scale: a vector specifying the data range for the scale. and the default order of their display in guides.
* @param naValue An aesthetic value which is used when data in not available.
* @param format Specifies the format pattern for labels on the scale.
* @param guide Guide to use for this scale.
* It can either be a string ("colorbar", "legend") or a call to a guide function (`guideColorbar()`, `guideLegend()`)
* specifying additional arguments.
* "none" will hide the guide.
*
* Format patterns in the `format` parameter can be just a number format (like "d") or
* a string template where number format is surrounded by curly braces: "{d} cylinders".
* Note: the "$" must be escaped as "\$".
* For more info see: [formats.html](https://lets-plot.org/kotlin/formats.html)
*
* Examples:
* - ".2f" -> "12.45"
* - "Score: {.2f}" -> "Score: 12.45"
* - "Score: {}" -> "Score: 12.454789"
*
*/
fun scaleColorManual(
values: Any,
name: String? = null,
breaks: Any? = null,
labels: Any? = null,
lablim: Int? = null,
limits: List? = null,
naValue: Any? = null,
format: String? = null,
guide: Any? = null
) = scaleManual(
aesthetic = Aes.COLOR,
values = values,
name = name,
breaks = breaks,
labels = labels,
lablim = lablim,
limits = limits,
naValue = naValue,
format = format,
guide = guide
)
/**
* Creates your own discrete scale for `fill` aesthetic.
*
* ## Examples
*
* - [error_bars.ipynb](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/error_bars.ipynb)
*
* @param values List of Strings (encoding colors) or color values.
* A set of aesthetic values to map data values to.
* Values will be matched with the limits of the scale (if specified).
* @param name The name of the scale - used as the axis label or the legend title.
* If null, the default, the name of the scale is taken from the first mapping used for that aesthetic.
* @param breaks A list of data values specifying the positions of ticks,
* or a dictionary which maps the tick labels to the breaks values.
* @param labels A list of labels on ticks, or a dictionary which maps the breaks values to the tick labels.
* @param lablim The maximum label length (in characters) before trimming is applied.
* @param limits Continuous scale: a numeric vector of length two providing limits of the scale.
* Discrete scale: a vector specifying the data range for the scale and the default order of their display in guides.
* @param naValue An aesthetic value which is used when data in not available.
* @param format Specifies the format pattern for labels on the scale.
* @param guide Guide to use for this scale.
* It can either be a string ("colorbar", "legend") or a call to a guide function (`guideColorbar()`, `guideLegend()`)
* specifying additional arguments.
* "none" will hide the guide.
*
* Format patterns in the `format` parameter can be just a number format (like "d") or
* a string template where number format is surrounded by curly braces: "{d} cylinders".
* Note: the "$" must be escaped as "\$".
* For more info see: [formats.html](https://lets-plot.org/kotlin/formats.html)
*
* Examples:
* - ".2f" -> "12.45"
* - "Score: {.2f}" -> "Score: 12.45"
* - "Score: {}" -> "Score: 12.454789"
*
*/
fun scaleFillManual(
values: Any,
name: String? = null,
breaks: Any? = null,
labels: Any? = null,
lablim: Int? = null,
limits: List? = null,
naValue: Any? = null,
format: String? = null,
guide: Any? = null
) = scaleManual(
aesthetic = Aes.FILL,
values = values,
name = name,
breaks = breaks,
labels = labels,
lablim = lablim,
limits = limits,
naValue = naValue,
format = format,
guide = guide
)
/**
* Creates your own discrete scale for `size` aesthetic.
*
* @param values A set of aesthetic values to map data values to.
* Values will be matched with the limits of the scale (if specified).
* @param name The name of the scale - used as the axis label or the legend title.
* If null, the default, the name of the scale is taken from the first mapping used for that aesthetic.
* @param breaks A list of data values specifying the positions of ticks,
* or a dictionary which maps the tick labels to the breaks values.
* @param labels A list of labels on ticks, or a dictionary which maps the breaks values to the tick labels.
* @param lablim The maximum label length (in characters) before trimming is applied.
* @param limits Continuous scale: a numeric vector of length two providing limits of the scale.
* Discrete scale: a vector specifying the data range for the scale and the default order of their display in guides.
* @param naValue An aesthetic value which is used when data in not available.
* @param format Specifies the format pattern for labels on the scale.
* @param guide Guide to use for this scale.
* It can either be a string ("colorbar", "legend") or a call to a guide function (`guideColorbar()`, `guideLegend()`)
* specifying additional arguments.
* "none" will hide the guide.
*
* Format patterns in the `format` parameter can be just a number format (like "d") or
* a string template where number format is surrounded by curly braces: "{d} cylinders".
* Note: the "$" must be escaped as "\$".
* For more info see: [formats.html](https://lets-plot.org/kotlin/formats.html)
*
* Examples:
* - ".2f" -> "12.45"
* - "Score: {.2f}" -> "Score: 12.45"
* - "Score: {}" -> "Score: 12.454789"
*
*/
fun scaleSizeManual(
values: Any,
name: String? = null,
breaks: Any? = null,
labels: Any? = null,
lablim: Int? = null,
limits: List? = null,
naValue: Number? = null,
format: String? = null,
guide: Any? = null
) = scaleManual(
aesthetic = Aes.SIZE,
values = values,
name = name,
breaks = breaks,
labels = labels,
lablim = lablim,
limits = limits,
naValue = naValue,
format = format,
guide = guide
)
/**
* Creates your own discrete scale for `shape` aesthetic.
*
* ## Examples
*
* - [scatter_plot.ipynb](https://nbviewer.org/github/JetBrains/lets-plot-docs/blob/master/source/kotlin_examples/cookbook/scatter_plot.ipynb)
*
* @param values A set of aesthetic values to map data values to.
* Values will be matched with the limits of the scale (if specified).
* @param name The name of the scale - used as the axis label or the legend title.
* If null, the default, the name of the scale is taken from the first mapping used for that aesthetic.
* @param breaks A list of data values specifying the positions of ticks,
* or a dictionary which maps the tick labels to the breaks values.
* @param labels A list of labels on ticks, or a dictionary which maps the breaks values to the tick labels.
* @param lablim The maximum label length (in characters) before trimming is applied.
* @param limits Continuous scale: a numeric vector of length two providing limits of the scale.
* Discrete scale: a vector specifying the data range for the scale and the default order of their display in guides.
* @param naValue An aesthetic value which is used when data in not available.
* @param format Specifies the format pattern for labels on the scale.
* @param guide Guide to use for this scale.
* It can either be a string ("colorbar", "legend") or a call to a guide function (`guideColorbar()`, `guideLegend()`)
* specifying additional arguments.
* "none" will hide the guide.
*
* Format patterns in the `format` parameter can be just a number format (like "d") or
* a string template where number format is surrounded by curly braces: "{d} cylinders".
* Note: the "$" must be escaped as "\$".
* For more info see: [formats.html](https://lets-plot.org/kotlin/formats.html)
*
* Examples:
* - ".2f" -> "12.45"
* - "Score: {.2f}" -> "Score: 12.45"
* - "Score: {}" -> "Score: 12.454789"
*
*/
fun scaleShapeManual(
values: Any,
name: String? = null,
breaks: Any? = null,
labels: Any? = null,
lablim: Int? = null,
limits: List? = null,
naValue: Any? = null,
format: String? = null,
guide: Any? = null
) = scaleManual(
aesthetic = Aes.SHAPE,
values = values,
name = name,
breaks = breaks,
labels = labels,
lablim = lablim,
limits = limits,
naValue = naValue,
format = format,
guide = guide
)
/**
* Creates your own discrete scale for `linetype` aesthetic.
*
* @param values A set of aesthetic values to map data values to.
* Values will be matched with the limits of the scale (if specified).
* @param name The name of the scale - used as the axis label or the legend title.
* If null, the default, the name of the scale is taken from the first mapping used for that aesthetic.
* @param breaks A list of data values specifying the positions of ticks,
* or a dictionary which maps the tick labels to the breaks values.
* @param labels A list of labels on ticks, or a dictionary which maps the breaks values to the tick labels.
* @param lablim The maximum label length (in characters) before trimming is applied.
* @param limits Continuous scale: a numeric vector of length two providing limits of the scale.
* Discrete scale: a vector specifying the data range for the scale and the default order of their display in guides.
* @param naValue An aesthetic value which is used when data in not available.
* @param format Specifies the format pattern for labels on the scale.
* @param guide Guide to use for this scale.
* It can either be a string ("colorbar", "legend") or a call to a guide function (`guideColorbar()`, `guideLegend()`)
* specifying additional arguments.
* "none" will hide the guide.
*
* Format patterns in the `format` parameter can be just a number format (like "d") or
* a string template where number format is surrounded by curly braces: "{d} cylinders".
* Note: the "$" must be escaped as "\$".
* For more info see: [formats.html](https://lets-plot.org/kotlin/formats.html)
*
* Examples:
* - ".2f" -> "12.45"
* - "Score: {.2f}" -> "Score: 12.45"
* - "Score: {}" -> "Score: 12.454789"
*
*/
@Suppress("SpellCheckingInspection")
fun scaleLinetypeManual(
values: Any,
name: String? = null,
breaks: Any? = null,
labels: Any? = null,
lablim: Int? = null,
limits: List? = null,
naValue: Any? = null,
format: String? = null,
guide: Any? = null
) = scaleManual(
aesthetic = Aes.LINETYPE,
values = values,
name = name,
breaks = breaks,
labels = labels,
lablim = lablim,
limits = limits,
naValue = naValue,
format = format,
guide = guide
)
/**
* Creates your own discrete scale for `alpha` aesthetic.
*
* @param values List of alpha values.
* A set of aesthetic values to map data values to.
* Values will be matched with the limits of the scale (if specified).
* @param name The name of the scale - used as the axis label or the legend title.
* If null, the default, the name of the scale is taken from the first mapping used for that aesthetic.
* @param breaks A list of data values specifying the positions of ticks,
* or a dictionary which maps the tick labels to the breaks values.
* @param labels A list of labels on ticks, or a dictionary which maps the breaks values to the tick labels.
* @param lablim The maximum label length (in characters) before trimming is applied.
* @param limits Continuous scale: a numeric vector of length two providing limits of the scale.
* Discrete scale: a vector specifying the data range for the scale and the default order of their display in guides.
* @param naValue An aesthetic value which is used when data in not available.
* @param format Specifies the format pattern for labels on the scale.
* @param guide Guide to use for this scale.
* It can either be a string ("colorbar", "legend") or a call to a guide function (`guideColorbar()`, `guideLegend()`)
* specifying additional arguments.
* "none" will hide the guide.
*
* Format patterns in the `format` parameter can be just a number format (like "d") or
* a string template where number format is surrounded by curly braces: "{d} cylinders".
* Note: the "$" must be escaped as "\$".
* For more info see: [formats.html](https://lets-plot.org/kotlin/formats.html)
*
* Examples:
* - ".2f" -> "12.45"
* - "Score: {.2f}" -> "Score: 12.45"
* - "Score: {}" -> "Score: 12.454789"
*
*/
fun scaleAlphaManual(
values: Any,
name: String? = null,
breaks: Any? = null,
labels: Any? = null,
lablim: Int? = null,
limits: List? = null,
naValue: Number? = null,
format: String? = null,
guide: Any? = null
) = scaleManual(
aesthetic = Aes.ALPHA,
values = values,
name = name,
breaks = breaks,
labels = labels,
lablim = lablim,
limits = limits,
naValue = naValue,
format = format,
guide = guide
)