Add serialization guide to docs

docs/source/guides/guides_index.rst

@@ -11,3 +11,4 @@ The guides below provide more detail on the functionality of Woodwork.
    statistical_insights
    using_woodwork_with_dask_and_koalas
    custom_types_and_type_inference
+   saving_and_loading_dataframes

docs/source/guides/saving_and_loading_dataframes.ipynb

@@ -0,0 +1,264 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "federal-queensland",
+   "metadata": {},
+   "source": [
+    "# Saving and Loading DataFrames\n",
+    "\n",
+    "In this guide, you will learn how to save and load Woodwork DataFrames.\n",
+    "\n",
+    "## Saving a Woodwork DataFrame\n",
+    "\n",
+    "After defining a Woodwork DataFrame with the proper logical types and semantic tags, you can save the DataFrame and  typing information by using `DataFrame.ww.to_disk`. This method will create a directory that contains a `data` folder and a `woodwork_typing_info.json` file. To illustrate, we will use this retail DataFrame which already comes configured with Woodwork typing information."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "tender-inventory",
+   "metadata": {
+    "scrolled": false
+   },
+   "outputs": [],
+   "source": [
+    "from woodwork.demo import load_retail\n",
+    "df = load_retail(nrows=100)\n",
+    "df.ww.schema"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "wooden-danish",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df.head()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "designed-soccer",
+   "metadata": {},
+   "source": [
+    "From the `ww` acessor, use `to_disk` to save the Woodwork DataFrame."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "powered-protein",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df.ww.to_disk('retail')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "interstate-tactics",
+   "metadata": {},
+   "source": [
+    "You should see a new directory that contains the data and typing information.\n",
+    "\n",
+    "```\n",
+    "retail\n",
+    "├── data\n",
+    "│   └── demo_retail_data.csv\n",
+    "└── woodwork_typing_info.json\n",
+    "```\n",
+    "\n",
+    "### Data Directory\n",
+    "\n",
+    "The `data` directory contains the underlying data written in the specified format. The method derives the filename from  `DataFrame.ww.name` and uses CSV as the default format. You can change the format by setting the method's `format` parameter to any of the following formats:\n",
+    "\n",
+    "- csv (default)\n",
+    "- pickle\n",
+    "- parquet\n",
+    "\n",
+    "### Typing Information\n",
+    "\n",
+    "In the `woodwork_typing_info.json`, you can see all of the typing information and metadata associated with the DataFrame. This information includes:\n",
+    "\n",
+    "- the version of the schema at the time of saving the DataFrame\n",
+    "- the DataFrame name specified by `DataFrame.ww.name`\n",
+    "- the column names for the index and time index\n",
+    "- the column typing information, which contains the logical types with their parameters and semantic tags for each column\n",
+    "- the loading information required for the DataFrame type and file format\n",
+    "- the table metadata provided by `DataFrame.ww.metadata` (must be JSON serializable)\n",
+    "\n",
+    "```text\n",
+    "{\n",
+    "    \"schema_version\": \"10.0.2\",\n",
+    "    \"name\": \"demo_retail_data\",\n",
+    "    \"index\": \"order_product_id\",\n",
+    "    \"time_index\": \"order_date\",\n",
+    "    \"column_typing_info\": [...],\n",
+    "    \"loading_info\": {\n",
+    "        \"table_type\": \"pandas\",\n",
+    "        \"location\": \"data/demo_retail_data.csv\",\n",
+    "        \"type\": \"csv\",\n",
+    "        \"params\": {\n",
+    "            \"compression\": null,\n",
+    "            \"sep\": \",\",\n",
+    "            \"encoding\": \"utf-8\",\n",
+    "            \"engine\": \"python\",\n",
+    "            \"index\": false\n",
+    "        }\n",
+    "    },\n",
+    "    \"table_metadata\": {}\n",
+    "}\n",
+    "```\n",
+    "\n",
+    "## Loading a Woodwork DataFrame\n",
+    "\n",
+    "After saving a Woodwork DataFrame, you can load the DataFrame and typing information by using `woodwork.deserialize.read_woodwork_table`. This function will use the stored typing information in the specified directory to recreate the Woodwork DataFrame."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "oriental-baking",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from woodwork.deserialize import read_woodwork_table\n",
+    "df = read_woodwork_table('retail')\n",
+    "df.ww.schema"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "dependent-liberty",
+   "metadata": {},
+   "source": [
+    "### Loading the DataFrame and typing information separately\n",
+    "\n",
+    "You can also load the Woodwork DataFrame and typing information separately by using `woodwork.read_file`.  This approach is helpful if you want to save and load the typing information outside the specified directory or read a data file directly into a Woodwork DataFrame. To illustrate, we will load the typing information first before reading data files in different formats directly into a Woodwork DataFrame. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "senior-richards",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from json import load\n",
+    "\n",
+    "with open('retail/woodwork_typing_info.json') as file:\n",
+    "    typing_information = load(file)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "mighty-bargain",
+   "metadata": {},
+   "source": [
+    "Let's create the data files in different formats from a pandas DataFrame."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "suspected-transcription",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pandas as pd\n",
+    "\n",
+    "pandas_df = pd.read_csv('retail/data/demo_retail_data.csv')\n",
+    "pandas_df.to_csv('retail/data.csv')\n",
+    "pandas_df.to_parquet('retail/data.parquet')\n",
+    "pandas_df.to_feather('retail/data.feather')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "patent-comfort",
+   "metadata": {},
+   "source": [
+    "Now, you can use `read_file` to load the data directly into a Woodwork DataFrame. This function uses the `content_type` parameter to determine the file format. If `content_type` is not specified, the function will try to infer the file format from the file extension."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "induced-newton",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from woodwork import read_file\n",
+    "\n",
+    "woodwork_df = read_file(\n",
+    "    filepath='retail/data.csv',\n",
+    "    content_type='csv',\n",
+    "    index=typing_information['index'],\n",
+    "    time_index=typing_information['time_index'],\n",
+    ")\n",
+    "\n",
+    "woodwork_df = read_file(\n",
+    "    filepath='retail/data.parquet',\n",
+    "    content_type='parquet',\n",
+    "    index=typing_information['index'],\n",
+    "    time_index=typing_information['time_index'],\n",
+    ")\n",
+    "\n",
+    "woodwork_df = read_file(\n",
+    "    filepath='retail/data.feather',\n",
+    "    content_type='feather',\n",
+    "    index=typing_information['index'],\n",
+    "    time_index=typing_information['time_index'],\n",
+    ")\n",
+    "\n",
+    "woodwork_df.ww"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "detailed-gather",
+   "metadata": {},
+   "source": [
+    "The parameters related to typing information such as the index, time index, logical types, and semantics tags are optional. So, you can read data files into Woodwork DataFrames and let Woodwork inference the typing information automatically."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "freelance-charlotte",
+   "metadata": {
+    "nbsphinx": "hidden"
+   },
+   "outputs": [],
+   "source": [
+    "# cleanup retail directory\n",
+    "from shutil import rmtree\n",
+    "rmtree('retail')"
+   ]
+  }
+ ],
+ "metadata": {
+  "celltoolbar": "Edit Metadata",
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.8"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/source/release_notes.rst

@@ -9,11 +9,12 @@ Future Release
   * Fixes
   * Changes
   * Documentation Changes
+        * Add guide for saving and loading Woodwork DataFrames (:pr:`1066`)
   * Testing Changes
         * Add additional reviewers to minimum and latest dependency checkers (:pr:`1070`, :pr:`1073`, :pr:`1077`)
 
     Thanks to the following people for contributing to this release:
-    :user:`gsheni`
+    :user:`gsheni`, :user:`jeff-hernandez`
 
 v0.5.1 Jul 22, 2021
 ===================