notebooks/03_Formatting.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# Formatting Output\n",
        "\n",
        "This notebook gives examples of various ways to format raw Darwin Core Archive data using [DwC-A_dotnet](https://github.com/pjoiner/DwC-A_dotnet) and and [DwC-A_dotnet.Interactive](https://github.com/pjoiner/DwC-A_dotnet.Interactive).\n",
        "\n",
        "First, we install the relevant libraries from Nuget."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "#r \"nuget:DwC-A_dotnet,0.8.0\"\n",
        "#r \"nuget:DwC-A_dotnet.Interactive,0.1.11-Pre\""
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Open The Archive\n",
        "\n",
        "We open the archive using an `ArchiveReader` object as described in the Introduction notebook.  In this case we are using a dataset derived from a gbif query of butterflies of the family *Papilionidae*.  This archive contains occurrence and multimedia data which also includes images.\n",
        "\n",
        "For more information on this dataset see [https://doi.org/10.15468/dl.zwsssf](https://doi.org/10.15468/dl.zwsssf)."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "using DwC_A;\n",
        "\n",
        "var archivePath = \"./data/Papilionidae.zip\";\n",
        "var archive = new ArchiveReader(archivePath);\n",
        "archive.MetaData"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "var occurrence = archive.CoreFile;\n",
        "var multimedia = archive.Extensions.GetFileReaderByFileName(\"multimedia.txt\");\n",
        "display(occurrence);\n",
        "display(multimedia);"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Registering A Formatter\n",
        "\n",
        "A Formatter may be registered to display a row or single element as shown in the next cell.  The easiest approach is to first define a record to hold the column or row information that is going to be displayed.\n",
        "\n",
        "The the PocketView api can be used to build more complex html.  For example the following cell creates a new record of type `ScientificName` and displays the genus and species in italics."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "using Microsoft.DotNet.Interactive.Formatting;\n",
        "\n",
        "using static Microsoft.DotNet.Interactive.Formatting.PocketViewTags;\n",
        "\n",
        "public record ScientificName(string genus, string species);\n",
        "\n",
        "Formatter.Register<ScientificName>((scientificName, writer) => {\n",
        "    var output = div[style: \"font-style: italic\"]($\"{scientificName.genus} {scientificName.species}\");\n",
        "    writer.Write(output);\n",
        "}, \"text/html\" );"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Scientific Name\n",
        "\n",
        "We can use the new ScientificName record type to format Occurrence data as follows."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "using DwC_A.Terms;\n",
        "\n",
        "occurrence.DataRows.Take(10)\n",
        "    .Select(n => new{\n",
        "        date = n[Terms.eventDate],\n",
        "        scientificName = new ScientificName(n[Terms.genus], n[Terms.specificEpithet])\n",
        "    }).DisplayTable()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Links\n",
        "\n",
        "We can register a link formatter as well to provide create clickable urls."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "public record Link(string url);\n",
        "\n",
        "Formatter.Register<Link>((link, writer) =>{\n",
        "    var linkHtml = a[href: link.url](link.url);\n",
        "    writer.Write(linkHtml);\n",
        "}, \"text/html\");\n",
        "\n",
        "occurrence.DataRows.Take(10)\n",
        "    .Select(n => new{\n",
        "        date = n[Terms.eventDate],\n",
        "        scientificName = new ScientificName(n[Terms.genus], n[Terms.specificEpithet]),\n",
        "        link = new Link(n[Terms.references])\n",
        "    }).DisplayTable()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Displaying Images\n",
        "\n",
        "The multimedia file of this archive contains links to images hosted on the web.  We can display those images inline with our queries by registering an image formatter.\n",
        "\n",
        "Here we will use the PocketView api to add styles to restrict the height of the displayed image to 100px and center the optional caption text.  The formatter is registered using a new `ImageUrl` record type."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "public record ImageUrl(string url, string caption = \"\");\n",
        "\n",
        "Formatter.Register<ImageUrl>((image, writer) =>{\n",
        "    var fig = figure[style: \"text-align: center; padding: 5px;\"](\n",
        "        img[src: image.url, style: \"height: 100px; margin-left: auto; margin-right: auto;\"],\n",
        "        div[style: \"font-style: italic\"](image.caption)\n",
        "    );\n",
        "    writer.Write(fig);\n",
        "}, \"text/html\");"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Finally, we use the `ImageUrl` record type in our query to display a list of images along with the scientific name."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "using DwC_A.Terms;\n",
        "\n",
        "var gbifId = \"http://rs.gbif.org/terms/1.0/gbifID\";\n",
        "var identifier = \"http://purl.org/dc/terms/identifier\";\n",
        "\n",
        "var media = from o in occurrence.DataRows.Take(10)\n",
        "    join m in multimedia.DataRows on o[gbifId] equals m[gbifId]\n",
        "    select new{\n",
        "        date = o[Terms.eventDate],\n",
        "        link = new Link(o[Terms.references]),\n",
        "        image = new ImageUrl(m[identifier], o[Terms.scientificName])\n",
        "    }; \n",
        "\n",
        "media.DisplayTable()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Creating a Gallery\n",
        "\n",
        "We can put this all together by registering a formatter for `IEnumerable<ImageUrl>` as follows and create a gallery of images."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "dotnet_interactive": {
          "language": "csharp"
        },
        "vscode": {
          "languageId": "polyglot-notebook"
        }
      },
      "outputs": [],
      "source": [
        "Formatter.Register<IEnumerable<ImageUrl>>((images, writer) =>{\n",
        "    var figs = new List<dynamic>();\n",
        "        images.ToList().ForEach(image => {\n",
        "            figs.Add(div[style: \"float: left\"](image));\n",
        "        });\n",
        "    writer.Write(div(figs));\n",
        "}, \"text/html\");\n",
        "\n",
        "media.Select(n => n.image)"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": ".NET (C#)",
      "language": "C#",
      "name": ".net-csharp"
    },
    "language_info": {
      "file_extension": ".cs",
      "mimetype": "text/x-csharp",
      "name": "C#",
      "pygments_lexer": "csharp",
      "version": "8.0"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 4
}