Add the drop parameter to facetWrap()

Author: MKoroteev-HORIS

docs/examples/jupyter-notebooks/f-4.11.1/facet_wrap_empty_panels.ipynb

@@ -0,0 +1,132 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "b64186c9-ae08-4eae-8ea8-d1ae43bc8b95",
+   "metadata": {},
+   "source": [
+    "# Handling of Empty Panels in `facetWrap()`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0ce1758f-9bdb-4213-b22e-8376d39681d6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%useLatestDescriptors\n",
+    "%use lets-plot\n",
+    "%use dataframe"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "32276694-1825-447a-ad40-b6fd30abc47f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "LetsPlot.getInfo()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2c595e38-65ec-40d3-a16b-927879998360",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import org.jetbrains.kotlinx.dataframe.api.*\n",
+    "\n",
+    "val df = DataFrame.readCSV(\"https://raw.githubusercontent.com/JetBrains/lets-plot-docs/master/data/mpg2.csv\")\n",
+    "val data = df.toMap() "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "49e00fb9-1a05-4366-ad23-c6973a942ac1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "val p = letsPlot(data) {\n",
+    "    x = \"engine horsepower\"\n",
+    "    y = \"miles per gallon\"\n",
+    "    color = asDiscrete(\"origin of car\", order = -1)\n",
+    "} + geomPoint() +\n",
+    "    themeGrey() +\n",
+    "    ggtitle(\"Efficiency vs Engine Horsepower\")\n",
+    "\n",
+    "p"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "467498b5-95ac-4cce-9ce0-9024af0120b2",
+   "metadata": {},
+   "source": [
+    "### Empty Facet Panels are Dropped by Default\n",
+    "\n",
+    "For example, there are no 3-cylinder engine cars originated in the US. Accordingly, this facet panel is dropped."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ebda0228-9500-4e48-ba05-64f98b645218",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "p + facetWrap(\n",
+    "    listOf(\"origin of car\", \"number of cylinders\"),\n",
+    "    order = listOf(-1, 1),\n",
+    "    ncol = 3\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "28a91a2c-38dd-4f75-b9aa-2d7daa624070",
+   "metadata": {},
+   "source": [
+    "### Using the `drop` Parameter to Control Empty Panels\n",
+    "\n",
+    "Use `drop=false` to show all factor levels regardless of whether they occur in the data."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "adfcc480-582e-41b9-b6d9-1f2c2c687a0b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "p + facetWrap(\n",
+    "    listOf(\"origin of car\", \"number of cylinders\"),\n",
+    "    order = listOf(-1, 1),\n",
+    "    ncol = 5,\n",
+    "    drop = false\n",
+    ")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Kotlin [conda env:lpk-master]",
+   "language": "kotlin",
+   "name": "conda-env-lpk-master-kotlin"
+  },
+  "language_info": {
+   "codemirror_mode": "text/x-kotlin",
+   "file_extension": ".kt",
+   "mimetype": "text/x-kotlin",
+   "name": "kotlin",
+   "nbconvert_exporter": "",
+   "pygments_lexer": "kotlin",
+   "version": "1.9.23"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/facet/facet_wrap.kt

@@ -33,6 +33,8 @@ import org.jetbrains.letsPlot.intern.filterNonNullValues
  *  The `order` values are positionally matched to variables in `facets`.
  * @param format Specifies the format pattern for displaying faceting values.
  *  The `format` values are positionally matched to variables in `facets`.
+ * @param drop Specifies whether to drop unused factor levels (the default behavior)
+ *  or to show all factor levels regardless of whether they occur in the data.
  * @param dir Direction: either "h" for horizontal, the default, or "v", for vertical.
  * @param labWidth Specifies the maximum label length (in characters) before a line break is applied.
  *  The `labWidth` values are positionally matched to variables in `facets`.
@@ -55,6 +57,7 @@ fun facetWrap(
     scales: String? = null,
     order: Any? = 1,
     format: Any? = null,
+    drop: Boolean = true,
     dir: String = "h",
     labWidth: Any? = null
 ): OptionsMap {
@@ -68,6 +71,7 @@ fun facetWrap(
             Option.Facet.SCALES to scales,
             Option.Facet.FACETS_ORDER to order,
             Option.Facet.FACETS_FORMAT to format,
+            Option.Facet.DROP_UNUSED_LEVELS to drop,
             Option.Facet.FACETS_FILL_DIR to dir,
             Option.Facet.FACETS_LABWIDTH to labWidth
         ).filterNonNullValues()