diff --git a/.github/workflows/mkdocs-release.yml b/.github/workflows/mkdocs-release.yml new file mode 100644 index 000000000..f625ab41d --- /dev/null +++ b/.github/workflows/mkdocs-release.yml @@ -0,0 +1,40 @@ +name: mkdocs-release + +on: + push: + branches: [ branch-* ] + +jobs: + publish-release: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - name: Checkout hopsworks-tutorials + uses: actions/checkout@v3 + with: + repository: logicalclocks/hopsworks-tutorials + path: docs/hopsworks-tutorials + fetch-depth: 0 + + - uses: actions/setup-python@v2 + with: + python-version: '3.8' + + - name: install deps + run: pip3 install pip==22.0.3 && pip3 install 'git+https://github.com/logicalclocks/feature-store-api@master#egg=hsfs[docs]&subdirectory=python' + + - name: copy tutorial images + run: python prepare_images.py + + - name: setup git + run: | + git config --global user.name Mike + git config --global user.email mike@docs.hopsworks.ai + + # Put this back and increment version when cutting a new release branch + # - name: mike deploy docs + # run: mike deploy 3.0 latest -u --push diff --git a/.github/workflows/mkdocs-test.yml b/.github/workflows/mkdocs-test.yml new file mode 100644 index 000000000..1e638e725 --- /dev/null +++ b/.github/workflows/mkdocs-test.yml @@ -0,0 +1,38 @@ +name: mkdocs-test + +on: pull_request + +jobs: + test-docs-build: + runs-on: ubuntu-latest + + steps: + - name: Checkout main repo + uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - name: Checkout hopsworks-tutorials + uses: actions/checkout@v3 + with: + repository: logicalclocks/hopsworks-tutorials + path: docs/hopsworks-tutorials + fetch-depth: 0 + + - uses: actions/setup-python@v2 + with: + python-version: '3.8' + + - name: install deps + run: pip3 install pip==22.0.3 && pip3 install 'git+https://github.com/logicalclocks/feature-store-api@master#egg=hsfs[docs]&subdirectory=python' + + - name: copy tutorial images + run: python prepare_images.py + + - name: setup git + run: | + git config --global user.name Mike + git config --global user.email mike@docs.hopsworks.ai + + - name: mike deploy docs + run: mike deploy 3.1-SNAPSHOT dev -u diff --git a/.gitignore b/.gitignore index add71dfa6..d90b8f4b0 100644 --- a/.gitignore +++ b/.gitignore @@ -109,6 +109,7 @@ venv.bak/ # mkdocs documentation site/ +docs/hopsworks-tutorials/ # mypy .mypy_cache/ diff --git a/docs/getting_started/images/01_featuregroups.png b/docs/getting_started/images/01_featuregroups.png deleted file mode 100644 index c2d8b0a4b..000000000 Binary files a/docs/getting_started/images/01_featuregroups.png and /dev/null differ diff --git a/docs/getting_started/images/02_training-dataset.png b/docs/getting_started/images/02_training-dataset.png deleted file mode 100644 index f8954e0ed..000000000 Binary files a/docs/getting_started/images/02_training-dataset.png and /dev/null differ diff --git a/docs/getting_started/images/03_model.png b/docs/getting_started/images/03_model.png deleted file mode 100644 index 2bb98ed29..000000000 Binary files a/docs/getting_started/images/03_model.png and /dev/null differ diff --git a/docs/getting_started/images/fg_overview.gif b/docs/getting_started/images/fg_overview.gif deleted file mode 100644 index e6bd61123..000000000 Binary files a/docs/getting_started/images/fg_overview.gif and /dev/null differ diff --git a/docs/getting_started/images/fg_statistics.gif b/docs/getting_started/images/fg_statistics.gif deleted file mode 100644 index 1c8fe0884..000000000 Binary files a/docs/getting_started/images/fg_statistics.gif and /dev/null differ diff --git a/docs/getting_started/images/fv_overview.gif b/docs/getting_started/images/fv_overview.gif deleted file mode 100644 index 5dd77672e..000000000 Binary files a/docs/getting_started/images/fv_overview.gif and /dev/null differ diff --git a/docs/getting_started/images/icon102.png b/docs/getting_started/images/icon102.png deleted file mode 100755 index bebb5b1cd..000000000 Binary files a/docs/getting_started/images/icon102.png and /dev/null differ diff --git a/docs/getting_started/images/provenance.gif b/docs/getting_started/images/provenance.gif deleted file mode 100644 index 4ad190fa2..000000000 Binary files a/docs/getting_started/images/provenance.gif and /dev/null differ diff --git a/docs/getting_started/images/serving_endpoints.gif b/docs/getting_started/images/serving_endpoints.gif deleted file mode 100644 index de46c5b4f..000000000 Binary files a/docs/getting_started/images/serving_endpoints.gif and /dev/null differ diff --git a/docs/getting_started/quickstart.ipynb b/docs/getting_started/quickstart.ipynb deleted file mode 100644 index 2bda7993b..000000000 --- a/docs/getting_started/quickstart.ipynb +++ /dev/null @@ -1,1587 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": { - "id": "8WLB6QFXksxw" - }, - "source": [ - "![Screenshot from 2022-06-16 14-24-57.png](data:image/png;base64,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)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/logicalclocks/hopsworks-tutorials/blob/master/quickstart.ipynb)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "Ovynr30zkqnO", - "outputId": "ab854e5a-4401-45b4-e834-1e65335dad6d" - }, - "outputs": [], - "source": [ - "!pip install -U hopsworks==3.0.0rc5 --quiet" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "NpwpPe1wxQ5M" - }, - "source": [ - "## 💽 Loading the Data\n", - "\n", - "The data you will use comes from three different CSV files:\n", - "\n", - "* credit_cards.csv: information such as the expiration date and provider.\n", - "* transactions.csv: events containing information about when a credit card was used, such as a timestamp, location, and the amount spent. A boolean fraud_label variable (True/False) tells us whether a transaction was fraudulent or not.\n", - "* profiles.csv: credit card user information such as birthdate and city of residence.\n", - "\n", - "In a production system, these CSV files would originate from separate data sources or tables, and probably separate data pipelines. All three files have a common credit card number column cc_num, which you will use later to join features together from the different datasets.\n", - "\n", - "Now, you can go ahead and load the data.\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/", - "height": 143 - }, - "id": "ARrJ_Bp5xMIk", - "outputId": "14e7a020-e04a-40d5-fdea-c4ba71f8a034" - }, - "outputs": [], - "source": [ - "import pandas as pd\n", - "import numpy as np\n", - "\n", - "window_len = \"4h\"\n", - "url = \"https://repo.hops.works/master/hopsworks-tutorials/data/card_fraud_data/\"" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "credit_cards_df = pd.read_csv(url + \"credit_cards.csv\")\n", - "credit_cards_df.head(3)\n", - "\n", - "profiles_df = pd.read_csv(url + \"profiles.csv\", parse_dates=[\"birthdate\"])\n", - "profiles_df.head(3)\n", - "\n", - "trans_df = pd.read_csv(url + \"transactions.csv\", parse_dates=[\"datetime\"])\n", - "trans_df.head(3)" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "HPq2qUtNxjaM" - }, - "source": [ - "\n", - "🛠️ Feature Engineering\n", - "\n", - "Fraudulent transactions can differ from regular ones in many different ways. Typical red flags would for instance be a large transaction volume/frequency in the span of a few hours. It could also be the case that elderly people in particular are targeted by fraudsters. To facilitate model learning, we will create additional features based on these patterns. In particular, we will create two types of features:\n", - "\n", - "* Features that aggregate data from different data sources. This could for instance be the age of a customer at the time of a transaction, which combines the birthdate feature from profiles.csv with the datetime feature from transactions.csv.\n", - "* Features that aggregate data from multiple time steps. An example of this could be the transaction frequency of a credit card in the span of a few hours, which is computed using a window function.\n", - "\n", - "Now you are ready to start with the first category.\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/", - "height": 206 - }, - "id": "ngEPnNzAxqsJ", - "outputId": "c8cf6082-1d1d-4bf7-9d81-ac2294146a27" - }, - "outputs": [], - "source": [ - "# Compute age at transaction.\n", - "age_df = trans_df.merge(profiles_df, on=\"cc_num\", how=\"left\")\n", - "trans_df[\"age_at_transaction\"] = (age_df[\"datetime\"] - age_df[\"birthdate\"]) / np.timedelta64(1, \"Y\")\n", - "\n", - "# Compute days until card expires.\n", - "card_expiry_df = trans_df.merge(credit_cards_df, on=\"cc_num\", how=\"left\")\n", - "card_expiry_df[\"expires\"] = pd.to_datetime(card_expiry_df[\"expires\"], format=\"%m/%y\")\n", - "trans_df[\"days_until_card_expires\"] = (card_expiry_df[\"expires\"] - card_expiry_df[\"datetime\"]) / np.timedelta64(1, \"D\")\n", - "\n", - "trans_df[[\"age_at_transaction\", \"days_until_card_expires\"]].head()\n" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "zEC12W4ux2Uk" - }, - "source": [ - "The next step is that you will create features from aggregations that are computed over every credit card over multiple time steps.\n", - "\n", - "You start by computing a feature that captures the physical distance between consecutive transactions, which we will call `loc_delta`. Here, you will use Haversine distance to quantify the distance between two longitude and latitude coordinates.\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "id": "rQ-g4ETOx4O5" - }, - "outputs": [], - "source": [ - "from math import radians\n", - "\n", - "# Do some simple preprocessing.\n", - "trans_df.sort_values(\"datetime\", inplace=True)\n", - "trans_df[[\"longitude\", \"latitude\"]] = trans_df[[\"longitude\", \"latitude\"]].applymap(radians)\n", - "\n", - "def haversine(long, lat):\n", - " \"\"\"Compute Haversine distance between each consecutive coordinate in (long, lat).\"\"\"\n", - "\n", - " long_shifted = long.shift()\n", - " lat_shifted = lat.shift()\n", - " long_diff = long_shifted - long\n", - " lat_diff = lat_shifted - lat\n", - "\n", - " a = np.sin(lat_diff/2.0)**2\n", - " b = np.cos(lat) * np.cos(lat_shifted) * np.sin(long_diff/2.0)**2\n", - " c = 2*np.arcsin(np.sqrt(a + b))\n", - "\n", - " return c\n", - "\n", - "\n", - "trans_df[\"loc_delta\"] = trans_df.groupby(\"cc_num\")\\\n", - " .apply(lambda x : haversine(x[\"longitude\"], x[\"latitude\"]))\\\n", - " .reset_index(level=0, drop=True)\\\n", - " .fillna(0)\n", - "\n" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "a_MHfwYsGfbo" - }, - "source": [ - "Next you will compute windowed aggregates. Here you will use 4-hour windows, but feel free to experiment with different window lengths by setting `window_len` below to a value of your choice." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/", - "height": 206 - }, - "id": "jmywmIVKGgLR", - "outputId": "32ad2881-9a27-483f-c8e4-9ef94af6dd6e" - }, - "outputs": [], - "source": [ - "cc_group = trans_df[[\"cc_num\", \"amount\", \"datetime\"]].groupby(\"cc_num\").rolling(window_len, on=\"datetime\")\n", - "\n", - "# Moving average of transaction volume.\n", - "df_4h_mavg = pd.DataFrame(cc_group.mean())\n", - "df_4h_mavg.columns = [\"trans_volume_mavg\", \"datetime\"]\n", - "df_4h_mavg = df_4h_mavg.reset_index(level=[\"cc_num\"])\n", - "df_4h_mavg = df_4h_mavg.drop(columns=[\"cc_num\", \"datetime\"])\n", - "df_4h_mavg = df_4h_mavg.sort_index()\n", - "\n", - "# Moving standard deviation of transaction volume.\n", - "df_4h_std = pd.DataFrame(cc_group.mean())\n", - "df_4h_std.columns = [\"trans_volume_mstd\", \"datetime\"]\n", - "df_4h_std = df_4h_std.reset_index(level=[\"cc_num\"])\n", - "df_4h_std = df_4h_std.drop(columns=[\"cc_num\", \"datetime\"])\n", - "df_4h_std = df_4h_std.fillna(0)\n", - "df_4h_std = df_4h_std.sort_index()\n", - "window_aggs_df = df_4h_std.merge(df_4h_mavg,left_index=True, right_index=True)\n", - "\n", - "# Moving average of transaction frequency.\n", - "df_4h_count = pd.DataFrame(cc_group.mean())\n", - "df_4h_count.columns = [\"trans_freq\", \"datetime\"]\n", - "df_4h_count = df_4h_count.reset_index(level=[\"cc_num\"])\n", - "df_4h_count = df_4h_count.drop(columns=[\"cc_num\", \"datetime\"])\n", - "df_4h_count = df_4h_count.sort_index()\n", - "window_aggs_df = window_aggs_df.merge(df_4h_count,left_index=True, right_index=True)\n", - "\n", - "# Moving average of location difference between consecutive transactions.\n", - "cc_group = trans_df[[\"cc_num\", \"loc_delta\", \"datetime\"]].groupby(\"cc_num\").rolling(window_len, on=\"datetime\").mean()\n", - "df_4h_loc_delta_mavg = pd.DataFrame(cc_group)\n", - "df_4h_loc_delta_mavg.columns = [\"loc_delta_mavg\", \"datetime\"]\n", - "df_4h_loc_delta_mavg = df_4h_loc_delta_mavg.reset_index(level=[\"cc_num\"])\n", - "df_4h_loc_delta_mavg = df_4h_loc_delta_mavg.drop(columns=[\"cc_num\", \"datetime\"])\n", - "df_4h_loc_delta_mavg = df_4h_loc_delta_mavg.sort_index()\n", - "window_aggs_df = window_aggs_df.merge(df_4h_loc_delta_mavg,left_index=True, right_index=True)\n", - "\n", - "window_aggs_df = window_aggs_df.merge(trans_df[[\"cc_num\", \"datetime\"]].sort_index(),left_index=True, right_index=True)\n", - "window_aggs_df.tail()\n" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "yB90r9qszLe2" - }, - "source": [ - "## 🪄 Creating Feature Groups\n", - "\n", - "A feature group can be seen as a collection of conceptually related features that are computed together at the same cadence. In your case, you will create a feature group for the transaction data and a feature group for the windowed aggregations on the transaction data. Both will have `tid` as primary key, which will allow you to join them together to create training data in a follow-on tutorial.\n", - "\n", - "Feature groups provide a namespace for features, so two features are allowed to have the same name as long as they belong to different feature groups. For instance, in a real-life setting we would likely want to experiment with different window lengths. In that case, we can create feature groups with identical schema for each window length.\n", - "\n", - "Before you can create a feature group we need to connect to our feature store.\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "WFmD_15TzMHX", - "outputId": "6acf8632-6993-485c-fb2a-31f27f7b462f" - }, - "outputs": [], - "source": [ - "import hopsworks\n", - "\n", - "project = hopsworks.login()\n", - "fs = project.get_feature_store()" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "EdpXZQnxzWkd" - }, - "source": [ - "To create a feature group we need to give it a name and specify a primary key. It is also good to provide a description of the contents of the feature group and a version number, if it is not defined it will automatically be incremented to 1." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "id": "kDUHXzJ3zXxN" - }, - "outputs": [], - "source": [ - "trans_fg = fs.get_or_create_feature_group(\n", - " name=\"transactions\",\n", - " version=\"1\",\n", - " description=\"Transaction data\",\n", - " primary_key=['cc_num'],\n", - " event_time=['datetime']\n", - ")" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "J3ZePNxmzbdn" - }, - "source": [ - "A full list of arguments can be found in the [documentation](https://docs.hopsworks.ai).\n", - "\n", - "At this point, we have only specified some metadata for the feature group. It does not store any data or even have a schema defined for the data. To make the feature group persistent we populate it with its associated data.\n", - "\n", - "If you have previously inserted this data into *trans_fg*, you can skip this step.\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "ptNT4PpPzcfV", - "outputId": "f432bd20-558a-4c62-e967-f96a2100f3b0" - }, - "outputs": [], - "source": [ - "trans_fg.insert(trans_df)" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "KzmLXQqizoZ4" - }, - "source": [ - "We can move on and do the same thing for the feature group with our windows aggregation." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "id": "PCE0H2TxzruP" - }, - "outputs": [], - "source": [ - "window_aggs_fg = fs.get_or_create_feature_group(\n", - " name=f\"transactions_{window_len}_aggs\",\n", - " version=1,\n", - " description=f\"Aggregate transaction data over {window_len} windows.\",\n", - " primary_key=['cc_num'],\n", - " event_time=['datetime']\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "TYk1qaE7zu0x", - "outputId": "a1c94e20-8718-456f-cc66-de655958b311" - }, - "outputs": [], - "source": [ - "window_aggs_fg.insert(window_aggs_df)" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "83QAknPe0Jui" - }, - "source": [ - "Click on the hyperlink printed in the cell output above to inspect your feature group in the UI." - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "Kp5O29jQ0YrY" - }, - "source": [ - "## 🔪 Feature Selection\n", - "\n", - "We start by selecting all the features we want to include for model training/inference.\n", - "\n", - "Hopsworks provides a simple DSL (domain specific language) for joining together features from different feature groups. You use the `select()/select_all()/select_except()` feature group methods to select features (from that feature group), and the `join()` method to join together features from a different feature group." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/", - "height": 347 - }, - "id": "DpM-7xwj0N4i", - "outputId": "1c7463e4-3ba5-440b-98f6-9c09995c3d76" - }, - "outputs": [], - "source": [ - "# Select features for training data.\n", - "ds_query = trans_fg.select([\"fraud_label\", \"category\", \"amount\", \"age_at_transaction\", \"days_until_card_expires\", \"loc_delta\"])\\\n", - " .join(window_aggs_fg.select_except([\"cc_num\"]), on=\"cc_num\")\\\n", - "\n", - "# Uncomment, if you want to inspect the data at this point\n", - "#ds_query.show(5)" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "fh8y7CWg0di9" - }, - "source": [ - "### What if features being joined together have the same name (but come from different feature groups)?\n", - "\n", - "The problem of name clashes when joining features together can easily happen. For example, recall that you computed the features in transactions_4h_aggs using 4-hour aggregates. If you had created another feature group for 12-hour aggregates, you may have designed an identical schema with the same feature names (just for 12-hours, not 4-hours). If you join features together with identical names from different feature groups, you should pass a prefix argument (e.g., `prefix='4hr'`) in the join operation to give the features unique names in the join object. See the [documentation](https://docs.hopsworks.ai) for more details.\n", - "\n", - "## 🤖 Transformation Functions\n", - "\n", - "You will preprocess our data using min-max scaling on numerical features and label encoding on categorical features. To do this, for each feature, you can define a one-to-one mapping between your feature and a transformation function. This ensures that transformation functions such as *min-max scaling* are fitted only on the train set (and not the validation/test set), which ensures that there is no leakage into the test set during training. The transformation functions are also needed for model inference pipelines, where pre-computed features are retrieved from the feature store and the same transformation functions (with the same state/parameters computed on the train set) are applied on the features in serving (inference pipelines).\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "id": "MbIo70e50VgP" - }, - "outputs": [], - "source": [ - "# Load the transformation functions.\n", - "min_max_scaler = fs.get_transformation_function(name=\"min_max_scaler\")\n", - "label_encoder = fs.get_transformation_function(name=\"label_encoder\")\n", - "\n", - "# Map features to transformation functions.\n", - "transformation_functions = {\n", - " \"category\": label_encoder,\n", - " \"amount\": min_max_scaler,\n", - " \"trans_volume_mavg\": min_max_scaler,\n", - " \"trans_volume_mstd\": min_max_scaler,\n", - " \"trans_freq\": min_max_scaler,\n", - " \"loc_delta\": min_max_scaler,\n", - " \"loc_delta_mavg\": min_max_scaler,\n", - " \"age_at_transaction\": min_max_scaler,\n", - " \"days_until_card_expires\": min_max_scaler,\n", - "}" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "1tIvbPlJ0xJQ" - }, - "source": [ - "## ⚙️ Feature View Creation\n", - "\n", - "The Feature View is the collection of features (from feature groups) and transformation functions used to train models and serve precomputed features to deployed models.\n", - "\n", - "The Feature View includes all of the features defined in the query object you created earlier. It can additionally include filters, one or more columns identified as the target(s) (or label) and the set of transformation functions and the features they are applied to. \n", - "\n", - "You create a Feature View with `fs.create_feature_view()`. " - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "TantyGyl0zqc", - "outputId": "1d20ea2d-b044-47dd-bb9a-b93a677ed7ac" - }, - "outputs": [], - "source": [ - "feature_view = fs.create_feature_view(\n", - " name='transactions_view',\n", - " query=ds_query,\n", - " version=1,\n", - " labels=[\"fraud_label\"],\n", - " transformation_functions=transformation_functions\n", - ")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "You can retrieve a reference to an existing feature view with: `fs.get_feature_view('transactions_view')`." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "feature_view = fs.get_feature_view('transactions_view', version=1)" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "hzwtiWqC1Gs5" - }, - "source": [ - "## 🏋️ Training Dataset Creation\n", - "\n", - "In Hopsworks, training data is the data from a set of features that is used to train a model. The FeatureView provides the set of features for the training data, but you can apply filters to select a subset of data from the data available for those features. For example, you could select training data for a given time range, or data only for users based on a particular geographic region. \n", - "Training data can be read as *in-memory Pandas DataFrames* or as (materialized) *files (.csv, .tfrecord, etc)* on disk. Training data is immutable and versioned. This makes training data also reproducible - you can delete the training data files and reproduce the exact same training data at a later point in time.\n", - "\n", - "Training data may be read with user-defined splits, such as:\n", - "\n", - "* Training set - the subset of training data used to train a model.\n", - "* Validation set - the subset of training data used to evaluate hparams when training a model\n", - "* Test set - the holdout subset of training data used to evaluate a model\n", - "\n", - "You use a FeatureView object to create training data, and there are different methods for reading training data as Pandas DataFrames or as creating training data as files. You can provide time filters specifing the start_time and end_time for training data.\n", - "\n", - "For example, this shows you how to create training data as files:\n", - "\n", - " from datetime import datetime\n", - " date_format = \"%Y-%m-%d %H:%M:%S\"\n", - "\n", - " start_time = int(float(datetime.strptime(\"2022-01-01 00:00:01\", date_format).timestamp()) * 1000)\n", - " end_time = int(float(datetime.strptime(\"2022-02-28 23:59:59\", date_format).timestamp()) * 1000)\n", - "\n", - " td_version, td_job = feature_view.create_training_data(\n", - " description = 'transactions_dataset_jan_feb',\n", - " data_format = 'csv',\n", - " write_options = {'wait_for_job': True},\n", - " coalesce = True,\n", - " start_time = start_time,\n", - " end_time = end_time,\n", - " )\n", - "\n", - "You can then retrieve the training data from the files using:\n", - "\n", - " X_train, y_train, X_test, y_test = feature_view.get_train_test_split(0.2)\n", - "\n", - "If you want to read the train/test set as Pandas DataFrames, use the call below which does not save training data as files, but stores metadata in the feature store that a version of training data was created for the feature view.\n", - "\n", - "🧬 Read train/test splits from a feature view" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "NGMyGRTnbQol", - "outputId": "49abbc54-c0ba-4e30-e9bc-91fd5342fe4e" - }, - "outputs": [], - "source": [ - "X_train, y_train, X_test, y_test = feature_view.train_test_split(0.2)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/", - "height": 206 - }, - "id": "RIidxsXb1hG3", - "outputId": "8d04d864-2be9-47d4-eae1-00e754b9897f" - }, - "outputs": [], - "source": [ - "X_train.head(5)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/", - "height": 206 - }, - "id": "LQ0F4B5s1lJh", - "outputId": "5771938f-1031-43c9-9b97-66cf0d3e6433" - }, - "outputs": [], - "source": [ - "y_train.head(5)" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "cpMXAUarmUEX" - }, - "source": [ - "Let's check the distribution of our target label." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "7yOvZZZNmW91", - "outputId": "4a20f728-708f-468e-eeae-39b8beb759bd" - }, - "outputs": [], - "source": [ - "y_train.value_counts(normalize=True)" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "uXUWJXAzmaV7" - }, - "source": [ - "Notice that the distribution is extremely skewed, which is natural considering that fraudulent transactions make up a tiny part of all transactions. Thus you should somehow address the class imbalance. There are many approaches for this, such as weighting the loss function, over- or undersampling, creating synthetic data, or modifying the decision threshold. In this example, you'll use the simplest method which is to just supply a class weight parameter to our learning algorithm. The class weight will affect how much importance is attached to each class, which in your case means that higher importance will be placed on positive (fraudulent) samples." - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "LxZfFvUDmdao" - }, - "source": [ - "## 🧬 Train Model\n", - "\n", - "Next you'll train a model. Here, you set the class weight of the positive class to be twice as big as the negative class.\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "2tXdVK91md5n", - "outputId": "049e125b-a49a-45df-b69e-f24226c3faeb" - }, - "outputs": [], - "source": [ - "from sklearn.linear_model import LogisticRegression\n", - "\n", - "pos_class_weight = 0.9\n", - "clf = LogisticRegression(class_weight={0: 1.0 - pos_class_weight, 1: pos_class_weight}, solver='liblinear')\n", - "clf.fit(X_train, y_train.values.ravel())" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "CWQlec77mkcZ" - }, - "source": [ - "Let's see how well it performs on your test data." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "qQK-dCZemmpe", - "outputId": "e054c772-d590-4fe7-992c-fa4db72cbf00" - }, - "outputs": [], - "source": [ - "from sklearn.metrics import classification_report\n", - "import pprint\n", - "\n", - "preds = clf.predict(X_test)\n", - "\n", - "report_dict = classification_report(y_test, preds, output_dict=True)\n", - "pprint.pprint(report_dict, width=2)" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "Mw20d2ehr5xt" - }, - "source": [ - "Pickle the model and write it to a local folder." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "iLZExWW5oFbG", - "outputId": "e3b27efe-52ab-48d0-8177-7a328c564900" - }, - "outputs": [], - "source": [ - "import joblib\n", - "\n", - "joblib.dump(clf, 'model.pkl')" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "mr = project.get_model_registry()" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "hvv1js3KczHh" - }, - "source": [ - "## 📝 Export Model\n", - "\n", - "Next you will export the model and attach additional information like the signature of the inputs/predictions, a concrete input example and evaluation metrics. In the last line, you upload the pickled model file to the Model Registry." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/" - }, - "id": "xjQ5JlMqsWdv", - "outputId": "46cd5673-0100-4bf7-a820-5b099286a28d" - }, - "outputs": [], - "source": [ - "from hsml.schema import Schema\n", - "from hsml.model_schema import ModelSchema\n", - "\n", - "input_schema = Schema(X_test)\n", - "output_schema = Schema(y_test)\n", - "\n", - "fraud_model = mr.sklearn.create_model(\"fraud2\",\n", - " metrics={'accuracy': report_dict['accuracy']},\n", - " input_example=X_test.head(1), \n", - " model_schema=ModelSchema(input_schema=input_schema, output_schema=output_schema))\n", - "\n", - "fraud_model.save('model.pkl')" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "-dX28wxChHQX" - }, - "source": [ - "## 🤖 Create Deployment\n", - "\n", - "Next step is to deploy the model on KServe behind Hopsworks for real-time inference requests." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/", - "height": 84, - "referenced_widgets": [ - "43c0b243b2c9417abc5072f82ba22457", - "4e326043046247f5ae5bfac3306cb145", - "a16b8eae9f614a44a9ee7f7ea900d1f2", - "a0e314c90c5a413d9701a6efcded884b", - "24536f939afa41f1acff4e55fae4423c", - "a26b3a1aa96f4eeaaad89d4d662fa010", - "ed9e0fc80c9e483cb7aafad007b57ea0", - "7887571c2ea4415080f60ea18be441b1", - "4559fa2eaf7348ae9dd5d1cfdd3e0bd5", - "7529396c14464b7b9e349c6ba003cddc", - "71ad3ff88d62426abda44fdb300b0484" - ] - }, - "id": "MHq7yu99sG3x", - "outputId": "119cbcf2-bf34-49c0-841b-d27c7cfc1e83" - }, - "outputs": [], - "source": [ - "deployment = fraud_model.deploy()\n", - "deployment.start()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "You can retrieve a reference to the model with mr.get_model(..) and a reference to the deployed model with `project.get_model_deployment(..)`" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "ms = project.get_model_serving()\n", - "deployment = ms.get_deployment(\"fraud2\")\n", - "fraud_model = mr.get_model(\"fraud2\", version=1)\n", - "print(fraud_model.input_example)" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "QKCTKfcaimxo" - }, - "source": [ - "## 🚀 Send Inference Requests\n", - "\n", - "Finally you can start making predictions with your model! \n", - "\n", - "Send inference requests to the deployed model as follows:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "colab": { - "base_uri": "https://localhost:8080/", - "height": 52 - }, - "id": "aL3-2W39tC-u", - "outputId": "fbda67a5-ce89-49ff-f113-a7dc8bbc2b6d" - }, - "outputs": [], - "source": [ - "deployment.predict({\"instances\":[fraud_model.input_example]})" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "id": "HmwNUVbHjO5I" - }, - "source": [ - "## 🥳 Next Steps\n", - "\n", - "Congratulations you've now completed the quickstart example for Managed Hopsworks.\n", - "\n", - "\n", - "Check out our other tutorials on ➡ https://github.com/logicalclocks/hopsworks-tutorials\n", - "\n", - "Or documentation at ➡ https://docs.hopsworks.ai" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [] - } - ], - "metadata": { - "colab": { - "collapsed_sections": [], - "name": "quickstart.ipynb", - "provenance": [] - }, - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "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.9" - }, - "widgets": { - "application/vnd.jupyter.widget-state+json": { - "192f266700894002b24eeff9b2136db3": { - "model_module": "@jupyter-widgets/base", - "model_module_version": "1.2.0", - "model_name": "LayoutModel", - "state": { - "_model_module": "@jupyter-widgets/base", - "_model_module_version": "1.2.0", - "_model_name": "LayoutModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/base", - "_view_module_version": "1.2.0", - "_view_name": "LayoutView", - "align_content": null, - "align_items": null, - "align_self": null, - "border": null, - "bottom": null, - "display": null, - "flex": null, - "flex_flow": null, - "grid_area": null, - "grid_auto_columns": null, - "grid_auto_flow": null, - "grid_auto_rows": null, - "grid_column": null, - "grid_gap": null, - "grid_row": null, - "grid_template_areas": null, - "grid_template_columns": null, - "grid_template_rows": null, - "height": null, - "justify_content": null, - "justify_items": null, - "left": null, - "margin": null, - "max_height": null, - "max_width": null, - "min_height": null, - "min_width": null, - "object_fit": null, - "object_position": null, - "order": null, - "overflow": null, - "overflow_x": null, - "overflow_y": null, - "padding": null, - "right": null, - "top": null, - "visibility": null, - "width": null - } - }, - "1b7c2a4d212646239113f831eeafc1cd": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "1.5.0", - "model_name": "DescriptionStyleModel", - "state": { - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "1.5.0", - "_model_name": "DescriptionStyleModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/base", - "_view_module_version": "1.2.0", - "_view_name": "StyleView", - "description_width": "" - } - }, - "24536f939afa41f1acff4e55fae4423c": { - "model_module": "@jupyter-widgets/base", - "model_module_version": "1.2.0", - "model_name": "LayoutModel", - "state": { - "_model_module": "@jupyter-widgets/base", - "_model_module_version": "1.2.0", - "_model_name": "LayoutModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/base", - "_view_module_version": "1.2.0", - "_view_name": "LayoutView", - "align_content": null, - "align_items": null, - "align_self": null, - "border": null, - "bottom": null, - "display": null, - "flex": null, - "flex_flow": null, - "grid_area": null, - "grid_auto_columns": null, - "grid_auto_flow": null, - "grid_auto_rows": null, - "grid_column": null, - "grid_gap": null, - "grid_row": null, - "grid_template_areas": null, - "grid_template_columns": null, - "grid_template_rows": null, - "height": null, - "justify_content": null, - "justify_items": null, - "left": null, - "margin": null, - "max_height": null, - "max_width": null, - "min_height": null, - "min_width": null, - "object_fit": null, - "object_position": null, - "order": null, - "overflow": null, - "overflow_x": null, - "overflow_y": null, - "padding": null, - "right": null, - "top": null, - "visibility": null, - "width": null - } - }, - "3f7e59807b824e86b47319bd47e32650": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "1.5.0", - "model_name": "HBoxModel", - "state": { - "_dom_classes": [], - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "1.5.0", - "_model_name": "HBoxModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/controls", - "_view_module_version": "1.5.0", - "_view_name": "HBoxView", - "box_style": "", - "children": [ - "IPY_MODEL_66c0d3f6020845d7a4203f33abf33818", - "IPY_MODEL_f22754bd6225452f8253ecff644c31d5", - "IPY_MODEL_77e516d3f3ce4c5488bf68825d260061" - ], - "layout": "IPY_MODEL_f91eeaa7449541819c9970f42963e2dd" - } - }, - "43c0b243b2c9417abc5072f82ba22457": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "1.5.0", - "model_name": "HBoxModel", - "state": { - "_dom_classes": [], - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "1.5.0", - "_model_name": "HBoxModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/controls", - "_view_module_version": "1.5.0", - "_view_name": "HBoxView", - "box_style": "", - "children": [ - "IPY_MODEL_4e326043046247f5ae5bfac3306cb145", - "IPY_MODEL_a16b8eae9f614a44a9ee7f7ea900d1f2", - "IPY_MODEL_a0e314c90c5a413d9701a6efcded884b" - ], - "layout": "IPY_MODEL_24536f939afa41f1acff4e55fae4423c" - } - }, - "4559fa2eaf7348ae9dd5d1cfdd3e0bd5": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "1.5.0", - "model_name": "ProgressStyleModel", - "state": { - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "1.5.0", - "_model_name": "ProgressStyleModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/base", - "_view_module_version": "1.2.0", - "_view_name": "StyleView", - "bar_color": null, - "description_width": "" - } - }, - "4e326043046247f5ae5bfac3306cb145": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "1.5.0", - "model_name": "HTMLModel", - "state": { - "_dom_classes": [], - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "1.5.0", - "_model_name": "HTMLModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/controls", - "_view_module_version": "1.5.0", - "_view_name": "HTMLView", - "description": "", - "description_tooltip": null, - "layout": "IPY_MODEL_a26b3a1aa96f4eeaaad89d4d662fa010", - "placeholder": "​", - "style": "IPY_MODEL_ed9e0fc80c9e483cb7aafad007b57ea0", - "value": "Deployment is running: 100%" - } - }, - "5fd0bd75549a47ae8a3042f1e0c61ba5": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "1.5.0", - "model_name": "DescriptionStyleModel", - "state": { - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "1.5.0", - "_model_name": "DescriptionStyleModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/base", - "_view_module_version": "1.2.0", - "_view_name": "StyleView", - "description_width": "" - } - }, - "66c0d3f6020845d7a4203f33abf33818": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "1.5.0", - "model_name": "HTMLModel", - "state": { - "_dom_classes": [], - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "1.5.0", - "_model_name": "HTMLModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/controls", - "_view_module_version": "1.5.0", - "_view_name": "HTMLView", - "description": "", - "description_tooltip": null, - "layout": "IPY_MODEL_d1c010a576d94f8bbcc6f535741f514b", - "placeholder": "​", - "style": "IPY_MODEL_5fd0bd75549a47ae8a3042f1e0c61ba5", - "value": "Model export complete: 100%" - } - }, - "71ad3ff88d62426abda44fdb300b0484": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "1.5.0", - "model_name": "DescriptionStyleModel", - "state": { - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "1.5.0", - "_model_name": "DescriptionStyleModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/base", - "_view_module_version": "1.2.0", - "_view_name": "StyleView", - "description_width": "" - } - }, - "7529396c14464b7b9e349c6ba003cddc": { - "model_module": "@jupyter-widgets/base", - "model_module_version": "1.2.0", - "model_name": "LayoutModel", - "state": { - "_model_module": "@jupyter-widgets/base", - "_model_module_version": "1.2.0", - "_model_name": "LayoutModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/base", - "_view_module_version": "1.2.0", - "_view_name": "LayoutView", - "align_content": null, - "align_items": null, - "align_self": null, - "border": null, - "bottom": null, - "display": null, - "flex": null, - "flex_flow": null, - "grid_area": null, - "grid_auto_columns": null, - "grid_auto_flow": null, - "grid_auto_rows": null, - "grid_column": null, - "grid_gap": null, - "grid_row": null, - "grid_template_areas": null, - "grid_template_columns": null, - "grid_template_rows": null, - "height": null, - "justify_content": null, - "justify_items": null, - "left": null, - "margin": null, - "max_height": null, - "max_width": null, - "min_height": null, - "min_width": null, - "object_fit": null, - "object_position": null, - "order": null, - "overflow": null, - "overflow_x": null, - "overflow_y": null, - "padding": null, - "right": null, - "top": null, - "visibility": null, - "width": null - } - }, - "77e516d3f3ce4c5488bf68825d260061": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "1.5.0", - "model_name": "HTMLModel", - "state": { - "_dom_classes": [], - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "1.5.0", - "_model_name": "HTMLModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/controls", - "_view_module_version": "1.5.0", - "_view_name": "HTMLView", - "description": "", - "description_tooltip": null, - "layout": "IPY_MODEL_192f266700894002b24eeff9b2136db3", - "placeholder": "​", - "style": "IPY_MODEL_1b7c2a4d212646239113f831eeafc1cd", - "value": " 6/6 [00:25<00:00, 5.19s/it]" - } - }, - "7887571c2ea4415080f60ea18be441b1": { - "model_module": "@jupyter-widgets/base", - "model_module_version": "1.2.0", - "model_name": "LayoutModel", - "state": { - "_model_module": "@jupyter-widgets/base", - "_model_module_version": "1.2.0", - "_model_name": "LayoutModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/base", - "_view_module_version": "1.2.0", - "_view_name": "LayoutView", - "align_content": null, - "align_items": null, - "align_self": null, - "border": null, - "bottom": null, - "display": null, - "flex": null, - "flex_flow": null, - "grid_area": null, - "grid_auto_columns": null, - "grid_auto_flow": null, - "grid_auto_rows": null, - "grid_column": null, - "grid_gap": null, - "grid_row": null, - "grid_template_areas": null, - "grid_template_columns": null, - "grid_template_rows": null, - "height": null, - "justify_content": null, - "justify_items": null, - "left": null, - "margin": null, - "max_height": null, - "max_width": null, - "min_height": null, - "min_width": null, - "object_fit": null, - "object_position": null, - "order": null, - "overflow": null, - "overflow_x": null, - "overflow_y": null, - "padding": null, - "right": null, - "top": null, - "visibility": null, - "width": null - } - }, - "a0e314c90c5a413d9701a6efcded884b": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "1.5.0", - "model_name": "HTMLModel", - "state": { - "_dom_classes": [], - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "1.5.0", - "_model_name": "HTMLModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/controls", - "_view_module_version": "1.5.0", - "_view_name": "HTMLView", - "description": "", - "description_tooltip": null, - "layout": "IPY_MODEL_7529396c14464b7b9e349c6ba003cddc", - "placeholder": "​", - "style": "IPY_MODEL_71ad3ff88d62426abda44fdb300b0484", - "value": " 1/1 [00:20<00:00, 5.12s/it]" - } - }, - "a16b8eae9f614a44a9ee7f7ea900d1f2": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "1.5.0", - "model_name": "FloatProgressModel", - "state": { - "_dom_classes": [], - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "1.5.0", - "_model_name": "FloatProgressModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/controls", - "_view_module_version": "1.5.0", - "_view_name": "ProgressView", - "bar_style": "success", - "description": "", - "description_tooltip": null, - "layout": "IPY_MODEL_7887571c2ea4415080f60ea18be441b1", - "max": 1, - "min": 0, - "orientation": "horizontal", - "style": "IPY_MODEL_4559fa2eaf7348ae9dd5d1cfdd3e0bd5", - "value": 1 - } - }, - "a26b3a1aa96f4eeaaad89d4d662fa010": { - "model_module": "@jupyter-widgets/base", - "model_module_version": "1.2.0", - "model_name": "LayoutModel", - "state": { - "_model_module": "@jupyter-widgets/base", - "_model_module_version": "1.2.0", - "_model_name": "LayoutModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/base", - "_view_module_version": "1.2.0", - "_view_name": "LayoutView", - "align_content": null, - "align_items": null, - "align_self": null, - "border": null, - "bottom": null, - "display": null, - "flex": null, - "flex_flow": null, - "grid_area": null, - "grid_auto_columns": null, - "grid_auto_flow": null, - "grid_auto_rows": null, - "grid_column": null, - "grid_gap": null, - "grid_row": null, - "grid_template_areas": null, - "grid_template_columns": null, - "grid_template_rows": null, - "height": null, - "justify_content": null, - "justify_items": null, - "left": null, - "margin": null, - "max_height": null, - "max_width": null, - "min_height": null, - "min_width": null, - "object_fit": null, - "object_position": null, - "order": null, - "overflow": null, - "overflow_x": null, - "overflow_y": null, - "padding": null, - "right": null, - "top": null, - "visibility": null, - "width": null - } - }, - "d1c010a576d94f8bbcc6f535741f514b": { - "model_module": "@jupyter-widgets/base", - "model_module_version": "1.2.0", - "model_name": "LayoutModel", - "state": { - "_model_module": "@jupyter-widgets/base", - "_model_module_version": "1.2.0", - "_model_name": "LayoutModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/base", - "_view_module_version": "1.2.0", - "_view_name": "LayoutView", - "align_content": null, - "align_items": null, - "align_self": null, - "border": null, - "bottom": null, - "display": null, - "flex": null, - "flex_flow": null, - "grid_area": null, - "grid_auto_columns": null, - "grid_auto_flow": null, - "grid_auto_rows": null, - "grid_column": null, - "grid_gap": null, - "grid_row": null, - "grid_template_areas": null, - "grid_template_columns": null, - "grid_template_rows": null, - "height": null, - "justify_content": null, - "justify_items": null, - "left": null, - "margin": null, - "max_height": null, - "max_width": null, - "min_height": null, - "min_width": null, - "object_fit": null, - "object_position": null, - "order": null, - "overflow": null, - "overflow_x": null, - "overflow_y": null, - "padding": null, - "right": null, - "top": null, - "visibility": null, - "width": null - } - }, - "d6462acb3ac6479f942e1a1b8da309a8": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "1.5.0", - "model_name": "ProgressStyleModel", - "state": { - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "1.5.0", - "_model_name": "ProgressStyleModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/base", - "_view_module_version": "1.2.0", - "_view_name": "StyleView", - "bar_color": null, - "description_width": "" - } - }, - "ed9e0fc80c9e483cb7aafad007b57ea0": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "1.5.0", - "model_name": "DescriptionStyleModel", - "state": { - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "1.5.0", - "_model_name": "DescriptionStyleModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/base", - "_view_module_version": "1.2.0", - "_view_name": "StyleView", - "description_width": "" - } - }, - "f22754bd6225452f8253ecff644c31d5": { - "model_module": "@jupyter-widgets/controls", - "model_module_version": "1.5.0", - "model_name": "FloatProgressModel", - "state": { - "_dom_classes": [], - "_model_module": "@jupyter-widgets/controls", - "_model_module_version": "1.5.0", - "_model_name": "FloatProgressModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/controls", - "_view_module_version": "1.5.0", - "_view_name": "ProgressView", - "bar_style": "success", - "description": "", - "description_tooltip": null, - "layout": "IPY_MODEL_f2ccbe863c224765bbe755fcb0ba4be7", - "max": 6, - "min": 0, - "orientation": "horizontal", - "style": "IPY_MODEL_d6462acb3ac6479f942e1a1b8da309a8", - "value": 6 - } - }, - "f2ccbe863c224765bbe755fcb0ba4be7": { - "model_module": "@jupyter-widgets/base", - "model_module_version": "1.2.0", - "model_name": "LayoutModel", - "state": { - "_model_module": "@jupyter-widgets/base", - "_model_module_version": "1.2.0", - "_model_name": "LayoutModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/base", - "_view_module_version": "1.2.0", - "_view_name": "LayoutView", - "align_content": null, - "align_items": null, - "align_self": null, - "border": null, - "bottom": null, - "display": null, - "flex": null, - "flex_flow": null, - "grid_area": null, - "grid_auto_columns": null, - "grid_auto_flow": null, - "grid_auto_rows": null, - "grid_column": null, - "grid_gap": null, - "grid_row": null, - "grid_template_areas": null, - "grid_template_columns": null, - "grid_template_rows": null, - "height": null, - "justify_content": null, - "justify_items": null, - "left": null, - "margin": null, - "max_height": null, - "max_width": null, - "min_height": null, - "min_width": null, - "object_fit": null, - "object_position": null, - "order": null, - "overflow": null, - "overflow_x": null, - "overflow_y": null, - "padding": null, - "right": null, - "top": null, - "visibility": null, - "width": null - } - }, - "f91eeaa7449541819c9970f42963e2dd": { - "model_module": "@jupyter-widgets/base", - "model_module_version": "1.2.0", - "model_name": "LayoutModel", - "state": { - "_model_module": "@jupyter-widgets/base", - "_model_module_version": "1.2.0", - "_model_name": "LayoutModel", - "_view_count": null, - "_view_module": "@jupyter-widgets/base", - "_view_module_version": "1.2.0", - "_view_name": "LayoutView", - "align_content": null, - "align_items": null, - "align_self": null, - "border": null, - "bottom": null, - "display": null, - "flex": null, - "flex_flow": null, - "grid_area": null, - "grid_auto_columns": null, - "grid_auto_flow": null, - "grid_auto_rows": null, - "grid_column": null, - "grid_gap": null, - "grid_row": null, - "grid_template_areas": null, - "grid_template_columns": null, - "grid_template_rows": null, - "height": null, - "justify_content": null, - "justify_items": null, - "left": null, - "margin": null, - "max_height": null, - "max_width": null, - "min_height": null, - "min_width": null, - "object_fit": null, - "object_position": null, - "order": null, - "overflow": null, - "overflow_x": null, - "overflow_y": null, - "padding": null, - "right": null, - "top": null, - "visibility": null, - "width": null - } - } - } - } - }, - "nbformat": 4, - "nbformat_minor": 4 -} \ No newline at end of file diff --git a/docs/tutorials/fraud_batch/1_feature_groups.ipynb b/docs/tutorials/fraud_batch/1_feature_groups.ipynb deleted file mode 100755 index 910fe1a9b..000000000 --- a/docs/tutorials/fraud_batch/1_feature_groups.ipynb +++ /dev/null @@ -1,935 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "bd1b0965", - "metadata": {}, - "source": [ - "![Screenshot from 2022-06-16 14-24-57.png](data:image/png;base64,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)" - ] - }, - { - "cell_type": "markdown", - "id": "eb87e56e", - "metadata": {}, - "source": [ - "# Part 01: Load, Engineer & Connect\n", - "\n", - "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/logicalclocks/hopsworks-tutorials/blob/master/fraud_batch/1_feature_groups.ipynb)\n", - "\n", - "This is the first part of the quick start series of tutorials about Hopsworks Feature Store. As part of this first module, we will work with data related to credit card transactions. \n", - "The objective of this tutorial is to demonstrate how to work with the **Hopworks Feature Store** for batch data with a goal of training and deploying a model that can predict fraudulent transactions.\n", - "\n", - "\n", - "## 🗒️ This notebook is divided in 3 sections:\n", - "1. Loading the data and feature engineeing,\n", - "2. Connect to the Hopsworks feature store,\n", - "3. Create feature groups and upload them to the feature store.\n", - "\n", - "![tutorial-flow](../images/01_featuregroups.png)\n", - "\n", - "First of all we will load the data and do some feature engineering on it." - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "cf0c2b64", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "\u001B[33mWARNING: You are using pip version 22.0.3; however, version 22.1.2 is available.\n", - "You should consider upgrading via the '/usr/bin/python3 -m pip install --upgrade pip' command.\u001B[0m\u001B[33m\n", - "\u001B[0m" - ] - } - ], - "source": [ - "!pip install -U hopsworks==3.0.0rc5 --quiet" - ] - }, - { - "cell_type": "markdown", - "id": "fadfb659", - "metadata": {}, - "source": [ - "## 💽 Loading the Data \n", - "\n", - "The data we will use comes from three different CSV files:\n", - "\n", - "- `credit_cards.csv`: credit card information such as expiration date and provider.\n", - "- `transactions.csv`: transaction information such as timestamp, location, and the amount. Importantly, the binary `fraud_label` variable tells us whether a transaction was fraudulent or not.\n", - "- `profiles.csv`: credit card user information such as birthdate and city of residence.\n", - "\n", - "We can conceptualize these CSV files as originating from separate data sources.\n", - "**All three files have a credit card number column `cc_num` in common, which we can use for joins.**\n", - "\n", - "Let's go ahead and load the data." - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "68ce9ada", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
cc_numproviderexpires
04796807885357879visa05/23
14529266636192966visa03/22
24922690008243953visa02/27
\n", - "
" - ], - "text/plain": [ - " cc_num provider expires\n", - "0 4796807885357879 visa 05/23\n", - "1 4529266636192966 visa 03/22\n", - "2 4922690008243953 visa 02/27" - ] - }, - "execution_count": 2, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "import pandas as pd\n", - "credit_cards_df = pd.read_csv(\"https://repo.hops.works/master/hopsworks-tutorials/data/card_fraud_data/credit_cards.csv\")\n", - "credit_cards_df.head(3)" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "0e78d1f6", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
namesexmailbirthdateCityCountrycc_num
0Catherine ZimmermanFvalenciajason@hotmail.com1988-09-20Bryn Mawr-SkywayUS4796807885357879
1Michael WilliamsMbrettkennedy@yahoo.com1977-03-01Gates-North GatesUS4529266636192966
2Jessica KruegerFmarthacruz@hotmail.com1947-09-10GreenfieldUS4922690008243953
\n", - "
" - ], - "text/plain": [ - " name sex mail birthdate \\\n", - "0 Catherine Zimmerman F valenciajason@hotmail.com 1988-09-20 \n", - "1 Michael Williams M brettkennedy@yahoo.com 1977-03-01 \n", - "2 Jessica Krueger F marthacruz@hotmail.com 1947-09-10 \n", - "\n", - " City Country cc_num \n", - "0 Bryn Mawr-Skyway US 4796807885357879 \n", - "1 Gates-North Gates US 4529266636192966 \n", - "2 Greenfield US 4922690008243953 " - ] - }, - "execution_count": 3, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "profiles_df = pd.read_csv(\"https://repo.hops.works/master/hopsworks-tutorials/data/card_fraud_data/profiles.csv\", parse_dates=[\"birthdate\"])\n", - "profiles_df.head(3)" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "b5774d94", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
tiddatetimecc_numcategoryamountlatitudelongitudecitycountryfraud_label
011df919988c134d97bbff2678eb68e222022-01-01 00:00:244473593503484549Health/Beauty62.9542.30865-83.48216CantonUS0
1dd0b2d6d4266ccd3bf05bc2ea91cf1802022-01-01 00:00:564272465718946864Grocery85.4533.52253-117.70755Laguna NiguelUS0
2e627f5d9a9739833bd52d2da51761fc32022-01-01 00:02:324104216579248948Domestic Transport21.6337.60876-77.37331MechanicsvilleUS0
\n", - "
" - ], - "text/plain": [ - " tid datetime cc_num \\\n", - "0 11df919988c134d97bbff2678eb68e22 2022-01-01 00:00:24 4473593503484549 \n", - "1 dd0b2d6d4266ccd3bf05bc2ea91cf180 2022-01-01 00:00:56 4272465718946864 \n", - "2 e627f5d9a9739833bd52d2da51761fc3 2022-01-01 00:02:32 4104216579248948 \n", - "\n", - " category amount latitude longitude city country \\\n", - "0 Health/Beauty 62.95 42.30865 -83.48216 Canton US \n", - "1 Grocery 85.45 33.52253 -117.70755 Laguna Niguel US \n", - "2 Domestic Transport 21.63 37.60876 -77.37331 Mechanicsville US \n", - "\n", - " fraud_label \n", - "0 0 \n", - "1 0 \n", - "2 0 " - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "trans_df = pd.read_csv(\"https://repo.hops.works/master/hopsworks-tutorials/data/card_fraud_data/transactions.csv\", parse_dates=[\"datetime\"])\n", - "trans_df.head(3)" - ] - }, - { - "cell_type": "markdown", - "id": "44ddf58f", - "metadata": {}, - "source": [ - "## 🛠️ Feature Engineering \n", - "\n", - "Fraudulent transactions can differ from regular ones in many different ways. Typical red flags would for instance be a large transaction volume/frequency in the span of a few hours. It could also be the case that elderly people in particular are targeted by fraudsters. To facilitate model learning we will create additional features based on these patterns. In particular, we will create two types of features:\n", - "1. **Features that aggregate data from different data sources**. This could for instance be the age of a customer at the time of a transaction, which combines the `birthdate` feature from `profiles.csv` with the `datetime` feature from `transactions.csv`.\n", - "2. **Features that aggregate data from multiple time steps**. An example of this could be the transaction frequency of a credit card in the span of a few hours, which is computed using a window function.\n", - "\n", - "Let's start with the first category." - ] - }, - { - "cell_type": "code", - "execution_count": 18, - "id": "6461d774", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
age_at_transactiondays_until_card_expires
097.5132971460.999722
133.7529191733.999352
280.899681242.998241
353.526088150.997639
446.005059515.997280
\n", - "
" - ], - "text/plain": [ - " age_at_transaction days_until_card_expires\n", - "0 97.513297 1460.999722\n", - "1 33.752919 1733.999352\n", - "2 80.899681 242.998241\n", - "3 53.526088 150.997639\n", - "4 46.005059 515.997280" - ] - }, - "execution_count": 18, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "import numpy as np\n", - "\n", - "# Compute age at transaction.\n", - "age_df = trans_df.merge(profiles_df, on=\"cc_num\", how=\"left\")\n", - "trans_df[\"age_at_transaction\"] = (age_df[\"datetime\"] - age_df[\"birthdate\"]) / np.timedelta64(1, \"Y\")\n", - "\n", - "# Compute days until card expires.\n", - "card_expiry_df = trans_df.merge(credit_cards_df, on=\"cc_num\", how=\"left\")\n", - "card_expiry_df[\"expires\"] = pd.to_datetime(card_expiry_df[\"expires\"], format=\"%m/%y\")\n", - "trans_df[\"days_until_card_expires\"] = (card_expiry_df[\"expires\"] - card_expiry_df[\"datetime\"]) / np.timedelta64(1, \"D\")\n", - "\n", - "trans_df[[\"age_at_transaction\", \"days_until_card_expires\"]].head()" - ] - }, - { - "cell_type": "markdown", - "id": "e4fbbd63", - "metadata": {}, - "source": [ - "Next, we create features that for each credit card aggregate data from multiple time steps.\n", - "\n", - "We start by computing the distance between consecutive transactions, which we will call `loc_delta`.\n", - "Here we use the [Haversine distance](https://scikit-learn.org/stable/modules/generated/sklearn.metrics.pairwise.haversine_distances.html?highlight=haversine#sklearn.metrics.pairwise.haversine_distances) to quantify the distance between two longitude and latitude coordinates." - ] - }, - { - "cell_type": "code", - "execution_count": 19, - "id": "03660624", - "metadata": {}, - "outputs": [], - "source": [ - "from math import radians\n", - "\n", - "# Do some simple preprocessing.\n", - "trans_df.sort_values(\"datetime\", inplace=True)\n", - "trans_df[[\"longitude\", \"latitude\"]] = trans_df[[\"longitude\", \"latitude\"]].applymap(radians)\n", - "\n", - "def haversine(long, lat):\n", - " \"\"\"Compute Haversine distance between each consecutive coordinate in (long, lat).\"\"\"\n", - "\n", - " long_shifted = long.shift()\n", - " lat_shifted = lat.shift()\n", - " long_diff = long_shifted - long\n", - " lat_diff = lat_shifted - lat\n", - "\n", - " a = np.sin(lat_diff/2.0)**2\n", - " b = np.cos(lat) * np.cos(lat_shifted) * np.sin(long_diff/2.0)**2\n", - " c = 2*np.arcsin(np.sqrt(a + b))\n", - "\n", - " return c\n", - "\n", - "\n", - "trans_df[\"loc_delta\"] = trans_df.groupby(\"cc_num\")\\\n", - " .apply(lambda x : haversine(x[\"longitude\"], x[\"latitude\"]))\\\n", - " .reset_index(level=0, drop=True)\\\n", - " .fillna(0)" - ] - }, - { - "cell_type": "markdown", - "id": "62121667", - "metadata": {}, - "source": [ - "Next we compute windowed aggregates. Here we will use 4-hour windows, but feel free to experiment with different window lengths by setting `window_len` below to a value of your choice." - ] - }, - { - "cell_type": "code", - "execution_count": 20, - "id": "aab205e9", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
trans_volume_mstdtrans_volume_mavgtrans_freqloc_delta_mavgcc_numdatetime
10601573.0873.0873.080.04563540320195218979612022-03-24 10:57:02
106016287.33287.33287.330.04584640320195218979612022-03-28 11:57:02
10601753.8853.8853.880.00012040320195218979612022-04-01 12:57:02
106018279.73279.73279.730.04592840320195218979612022-04-05 13:57:02
10601973.6673.6673.660.04597440320195218979612022-04-09 14:57:02
\n", - "
" - ], - "text/plain": [ - " trans_volume_mstd trans_volume_mavg trans_freq loc_delta_mavg \\\n", - "106015 73.08 73.08 73.08 0.045635 \n", - "106016 287.33 287.33 287.33 0.045846 \n", - "106017 53.88 53.88 53.88 0.000120 \n", - "106018 279.73 279.73 279.73 0.045928 \n", - "106019 73.66 73.66 73.66 0.045974 \n", - "\n", - " cc_num datetime \n", - "106015 4032019521897961 2022-03-24 10:57:02 \n", - "106016 4032019521897961 2022-03-28 11:57:02 \n", - "106017 4032019521897961 2022-04-01 12:57:02 \n", - "106018 4032019521897961 2022-04-05 13:57:02 \n", - "106019 4032019521897961 2022-04-09 14:57:02 " - ] - }, - "execution_count": 20, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "window_len = \"4h\"\n", - "cc_group = trans_df[[\"cc_num\", \"amount\", \"datetime\"]].groupby(\"cc_num\").rolling(window_len, on=\"datetime\")\n", - "\n", - "# Moving average of transaction volume.\n", - "df_4h_mavg = pd.DataFrame(cc_group.mean())\n", - "df_4h_mavg.columns = [\"trans_volume_mavg\", \"datetime\"]\n", - "df_4h_mavg = df_4h_mavg.reset_index(level=[\"cc_num\"])\n", - "df_4h_mavg = df_4h_mavg.drop(columns=[\"cc_num\", \"datetime\"])\n", - "df_4h_mavg = df_4h_mavg.sort_index()\n", - "\n", - "# Moving standard deviation of transaction volume.\n", - "df_4h_std = pd.DataFrame(cc_group.mean())\n", - "df_4h_std.columns = [\"trans_volume_mstd\", \"datetime\"]\n", - "df_4h_std = df_4h_std.reset_index(level=[\"cc_num\"])\n", - "df_4h_std = df_4h_std.drop(columns=[\"cc_num\", \"datetime\"])\n", - "df_4h_std = df_4h_std.fillna(0)\n", - "df_4h_std = df_4h_std.sort_index()\n", - "window_aggs_df = df_4h_std.merge(df_4h_mavg,left_index=True, right_index=True)\n", - "\n", - "# Moving average of transaction frequency.\n", - "df_4h_count = pd.DataFrame(cc_group.mean())\n", - "df_4h_count.columns = [\"trans_freq\", \"datetime\"]\n", - "df_4h_count = df_4h_count.reset_index(level=[\"cc_num\"])\n", - "df_4h_count = df_4h_count.drop(columns=[\"cc_num\", \"datetime\"])\n", - "df_4h_count = df_4h_count.sort_index()\n", - "window_aggs_df = window_aggs_df.merge(df_4h_count,left_index=True, right_index=True)\n", - "\n", - "# Moving average of location difference between consecutive transactions.\n", - "cc_group = trans_df[[\"cc_num\", \"loc_delta\", \"datetime\"]].groupby(\"cc_num\").rolling(window_len, on=\"datetime\").mean()\n", - "df_4h_loc_delta_mavg = pd.DataFrame(cc_group)\n", - "df_4h_loc_delta_mavg.columns = [\"loc_delta_mavg\", \"datetime\"]\n", - "df_4h_loc_delta_mavg = df_4h_loc_delta_mavg.reset_index(level=[\"cc_num\"])\n", - "df_4h_loc_delta_mavg = df_4h_loc_delta_mavg.drop(columns=[\"cc_num\", \"datetime\"])\n", - "df_4h_loc_delta_mavg = df_4h_loc_delta_mavg.sort_index()\n", - "window_aggs_df = window_aggs_df.merge(df_4h_loc_delta_mavg,left_index=True, right_index=True)\n", - "\n", - "window_aggs_df = window_aggs_df.merge(trans_df[[\"cc_num\", \"datetime\"]].sort_index(),left_index=True, right_index=True)\n", - "window_aggs_df.tail()" - ] - }, - { - "cell_type": "markdown", - "id": "2e25f1ea", - "metadata": {}, - "source": [ - "### Convert date time object to unix epoch in milliseconds" - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "ab0048f5", - "metadata": {}, - "outputs": [], - "source": [ - "trans_df.datetime = trans_df.datetime.values.astype(np.int64) // 10 ** 6\n", - "window_aggs_df.datetime = window_aggs_df.datetime.values.astype(np.int64) // 10 ** 6" - ] - }, - { - "cell_type": "markdown", - "id": "8d81124a", - "metadata": {}, - "source": [ - "## 🪄 Creating Feature Groups \n", - "\n", - "A [feature group](https://docs.hopsworks.ai/feature-store-api/latest/generated/feature_group/) can be seen as a collection of conceptually related features. In our case, we will create a feature group for the transaction data and a feature group for the windowed aggregations on the transaction data. Both will have `cc_num` as primary key, which will allow us to join them when creating a dataset in the next tutorial.\n", - "\n", - "Feature groups can also be used to define a namespace for features. For instance, in a real-life setting we would likely want to experiment with different window lengths. In that case, we can create feature groups with identical schema for each window length. \n", - "\n", - "Before we can create a feature group we need to connect to our feature store." - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "472dc254", - "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "DeprecationWarning: the imp module is deprecated in favour of importlib; see the module's documentation for alternative uses\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Connected. Call `.close()` to terminate connection gracefully.\n" - ] - } - ], - "source": [ - "import hopsworks\n", - "\n", - "project = hopsworks.login()\n", - "\n", - "fs = project.get_feature_store()" - ] - }, - { - "cell_type": "markdown", - "id": "80ca38a4", - "metadata": {}, - "source": [ - "To create a feature group we need to give it a name and specify a primary key. It is also good to provide a description of the contents of the feature group and a version number, if it is not defined it will automatically be incremented to `1`." - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "ce9ea36d", - "metadata": {}, - "outputs": [], - "source": [ - "trans_fg = fs.get_or_create_feature_group(\n", - " name=\"transactions\",\n", - " version=1,\n", - " description=\"Transaction data\",\n", - " primary_key=['cc_num'],\n", - " event_time=['datetime']\n", - ")" - ] - }, - { - "cell_type": "markdown", - "id": "450f94e9", - "metadata": {}, - "source": [ - "A full list of arguments can be found in the [documentation](https://docs.hopsworks.ai/feature-store-api/latest/generated/api/feature_store_api/#create_feature_group).\n", - "\n", - "At this point, we have only specified some metadata for the feature group. It does not store any data or even have a schema defined for the data. To make the feature group persistent we populate it with its associated data using the `insert` function." - ] - }, - { - "cell_type": "code", - "execution_count": 11, - "id": "c23ade7b", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Feature Group created successfully, explore it at https://c.app.hopsworks.ai:443/p/124/fs/72/fg/72\n", - "Launching offline feature group backfill job...\n", - "Backfill Job started successfully, you can follow the progress at https://c.app.hopsworks.ai/p/124/jobs/named/transactions_1_offline_fg_backfill/executions\n" - ] - }, - { - "data": { - "text/plain": [ - "(, None)" - ] - }, - "execution_count": 11, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "trans_fg.insert(trans_df)" - ] - }, - { - "cell_type": "code", - "execution_count": 13, - "id": "2e00a3f4-7749-46af-bd01-78e5126f12ae", - "metadata": {}, - "outputs": [], - "source": [ - "feature_descriptions = [\n", - " {\"name\": \"tid\", \"description\": \"Transaction id\"},\n", - " {\"name\": \"datetime\", \"description\": \"Transaction time\"},\n", - " {\"name\": \"cc_num\", \"description\": \"Number of the credit card performing the transaction\"},\n", - " {\"name\": \"category\", \"description\": \"Expense category\"},\n", - " {\"name\": \"amount\", \"description\": \"Dollar amount of the transaction\"},\n", - " {\"name\": \"latitude\", \"description\": \"Transaction location latitude\"},\n", - " {\"name\": \"longitude\", \"description\": \"Transaction location longitude\"},\n", - " {\"name\": \"city\", \"description\": \"City in which the transaction was made\"},\n", - " {\"name\": \"country\", \"description\": \"Country in which the transaction was made\"},\n", - " {\"name\": \"fraud_label\", \"description\": \"Whether the transaction was fraudulent or not\"},\n", - " {\"name\": \"age_at_transaction\", \"description\": \"Age of the card holder when the transaction was made\"},\n", - " {\"name\": \"days_until_card_expires\", \"description\": \"Card validity days left when the transaction was made\"},\n", - " {\"name\": \"loc_delta\", \"description\": \"Haversine distance between this transaction location and the previous transaction location from the same card\"},\n", - "]\n", - "\n", - "for desc in feature_descriptions: \n", - " trans_fg.update_feature_description(desc[\"name\"], desc[\"description\"])" - ] - }, - { - "cell_type": "markdown", - "id": "c0aed1e7", - "metadata": {}, - "source": [ - "At the creation of the feature group, you will prompted with an URL that will directly link to it; there you will be able to explore some of the aspects of your newly created feature group.\n", - "\n", - "[//]: <> (insert GIF here)" - ] - }, - { - "cell_type": "markdown", - "id": "f7bdca21", - "metadata": {}, - "source": [ - "We can move on and do the same thing for the feature group with our windows aggregation." - ] - }, - { - "cell_type": "code", - "execution_count": 16, - "id": "7b11a34d", - "metadata": {}, - "outputs": [], - "source": [ - "window_aggs_fg = fs.get_or_create_feature_group(\n", - " name=f\"transactions_{window_len}_aggs\",\n", - " version=1,\n", - " description=f\"Aggregate transaction data over {window_len} windows.\",\n", - " primary_key=['cc_num'],\n", - " event_time=['datetime']\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": 13, - "id": "9276c51c", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Feature Group created successfully, explore it at https://c.app.hopsworks.ai:443/p/124/fs/72/fg/73\n", - "Launching offline feature group backfill job...\n", - "Backfill Job started successfully, you can follow the progress at https://c.app.hopsworks.ai/p/124/jobs/named/transactions_4h_aggs_1_offline_fg_backfill/executions\n" - ] - }, - { - "data": { - "text/plain": [ - "(, None)" - ] - }, - "execution_count": 13, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "window_aggs_fg.insert(window_aggs_df)" - ] - }, - { - "cell_type": "code", - "execution_count": 22, - "id": "532e7301-935d-4cdd-95ea-2c68a50c80d5", - "metadata": {}, - "outputs": [], - "source": [ - "feature_descriptions = [\n", - " {\"name\": \"datetime\", \"description\": \"Transaction time\"},\n", - " {\"name\": \"cc_num\", \"description\": \"Number of the credit card performing the transaction\"},\n", - " {\"name\": \"loc_delta_mavg\", \"description\": \"Moving average of location difference between consecutive transactions from the same card\"},\n", - " {\"name\": \"trans_freq\", \"description\": \"Moving average of transaction frequency from the same card\"},\n", - " {\"name\": \"trans_volume_mavg\", \"description\": \"Moving average of transaction volume from the same card\"},\n", - " {\"name\": \"trans_volume_mstd\", \"description\": \"Moving standard deviation of transaction volume from the same card\"},\n", - "]\n", - "\n", - "for desc in feature_descriptions: \n", - " window_aggs_fg.update_feature_description(desc[\"name\"], desc[\"description\"])" - ] - }, - { - "cell_type": "markdown", - "id": "a704dcc9", - "metadata": {}, - "source": [ - "Both feature groups are now accessible and searchable in the UI\n", - "\n", - "![fg-overview](../images/fg_overview.gif)" - ] - }, - { - "cell_type": "markdown", - "id": "ccdab7eb", - "metadata": {}, - "source": [ - "## ⏭️ **Next:** Part 02 \n", - "\n", - "In the following notebook we will use our feature groups to create a dataset we can train a model on." - ] - } - ], - "metadata": { - "interpreter": { - "hash": "e1ddeae6eefc765c17da80d38ea59b893ab18c0c0904077a035ef84cfe367f83" - }, - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "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.9" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} \ No newline at end of file diff --git a/docs/tutorials/fraud_batch/2_feature_view_creation.ipynb b/docs/tutorials/fraud_batch/2_feature_view_creation.ipynb deleted file mode 100755 index e165bcee3..000000000 --- a/docs/tutorials/fraud_batch/2_feature_view_creation.ipynb +++ /dev/null @@ -1,879 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "![Screenshot from 2022-06-16 14-24-57.png](data:image/png;base64,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)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Part 02: Training Data & Feature views\n", - "\n", - "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/logicalclocks/hopsworks-tutorials/blob/master/fraud_batch/2_feature_view_creation.ipynb)\n", - "\n", - "This is the second part of the quick start series of tutorials about Hopsworks Feature Store. This notebook explains how to read from a feature group and create training dataset within the feature store\n", - "\n", - "## 🗒️ In this notebook we will see how to create a training dataset from the feature groups:\n", - "1. **Select the features** we want to train our model on,\n", - "2. **How the features should be preprocessed,**\n", - "3. **Create a dataset split** for training and validation data.\n", - "\n", - "![tutorial-flow](../images/02_training-dataset.png) " - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Connected. Call `.close()` to terminate connection gracefully.\n", - "\n", - "Logged in to project, explore it here https://c.app.hopsworks.ai:443/p/124\n", - "Connected. Call `.close()` to terminate connection gracefully.\n" - ] - }, - { - "name": "stderr", - "output_type": "stream", - "text": [ - "DeprecationWarning: the imp module is deprecated in favour of importlib; see the module's documentation for alternative uses\n" - ] - } - ], - "source": [ - "import hopsworks\n", - "\n", - "project = hopsworks.login()\n", - "\n", - "fs = project.get_feature_store()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## 🔪 Feature Selection \n", - "\n", - "We start by selecting all the features we want to include for model training/inference." - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "metadata": {}, - "outputs": [], - "source": [ - "# Load feature groups.\n", - "trans_fg = fs.get_feature_group('transactions', version=1)\n", - "window_aggs_fg = fs.get_feature_group('transactions_4h_aggs', version=1)" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "2022-06-20 09:38:17,044 INFO: USE `robin100_featurestore`\n", - "2022-06-20 09:38:18,287 INFO: WITH right_fg0 AS (SELECT *\n", - "FROM (SELECT `fg1`.`fraud_label` `fraud_label`, `fg1`.`category` `category`, `fg1`.`amount` `amount`, `fg1`.`age_at_transaction` `age_at_transaction`, `fg1`.`days_until_card_expires` `days_until_card_expires`, `fg1`.`loc_delta` `loc_delta`, `fg1`.`cc_num` `join_pk_cc_num`, `fg1`.`datetime` `join_evt_datetime`, `fg0`.`trans_volume_mstd` `trans_volume_mstd`, `fg0`.`trans_volume_mavg` `trans_volume_mavg`, `fg0`.`trans_freq` `trans_freq`, `fg0`.`loc_delta_mavg` `loc_delta_mavg`, RANK() OVER (PARTITION BY `fg0`.`cc_num`, `fg1`.`datetime` ORDER BY `fg0`.`datetime` DESC) pit_rank_hopsworks\n", - "FROM `robin100_featurestore`.`transactions_1` `fg1`\n", - "INNER JOIN `robin100_featurestore`.`transactions_4h_aggs_1` `fg0` ON `fg1`.`cc_num` = `fg0`.`cc_num` AND `fg1`.`datetime` >= `fg0`.`datetime`) NA\n", - "WHERE `pit_rank_hopsworks` = 1) (SELECT `right_fg0`.`fraud_label` `fraud_label`, `right_fg0`.`category` `category`, `right_fg0`.`amount` `amount`, `right_fg0`.`age_at_transaction` `age_at_transaction`, `right_fg0`.`days_until_card_expires` `days_until_card_expires`, `right_fg0`.`loc_delta` `loc_delta`, `right_fg0`.`trans_volume_mstd` `trans_volume_mstd`, `right_fg0`.`trans_volume_mavg` `trans_volume_mavg`, `right_fg0`.`trans_freq` `trans_freq`, `right_fg0`.`loc_delta_mavg` `loc_delta_mavg`\n", - "FROM right_fg0)\n" - ] - }, - { - "name": "stderr", - "output_type": "stream", - "text": [ - "UserWarning: pandas only support SQLAlchemy connectable(engine/connection) ordatabase string URI or sqlite3 DBAPI2 connectionother DBAPI2 objects are not tested, please consider using SQLAlchemy\n" - ] - }, - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
fraud_labelcategoryamountage_at_transactiondays_until_card_expiresloc_deltatrans_volume_mstdtrans_volume_mavgtrans_freqloc_delta_mavg
00Grocery93.5125.334094175.9122800.00000093.51093.51093.5100.000000
10Domestic Transport65.1425.335632175.3504860.31957465.14065.14065.1400.319574
20Grocery0.2625.336235175.1303470.3141480.2600.2600.2600.314148
30Grocery1.4325.336660174.9750580.0000000.8450.8450.8450.157074
40Grocery19.7525.344710172.0346640.10531319.75019.75019.7500.105313
\n", - "
" - ], - "text/plain": [ - " fraud_label category amount age_at_transaction \\\n", - "0 0 Grocery 93.51 25.334094 \n", - "1 0 Domestic Transport 65.14 25.335632 \n", - "2 0 Grocery 0.26 25.336235 \n", - "3 0 Grocery 1.43 25.336660 \n", - "4 0 Grocery 19.75 25.344710 \n", - "\n", - " days_until_card_expires loc_delta trans_volume_mstd trans_volume_mavg \\\n", - "0 175.912280 0.000000 93.510 93.510 \n", - "1 175.350486 0.319574 65.140 65.140 \n", - "2 175.130347 0.314148 0.260 0.260 \n", - "3 174.975058 0.000000 0.845 0.845 \n", - "4 172.034664 0.105313 19.750 19.750 \n", - "\n", - " trans_freq loc_delta_mavg \n", - "0 93.510 0.000000 \n", - "1 65.140 0.319574 \n", - "2 0.260 0.314148 \n", - "3 0.845 0.157074 \n", - "4 19.750 0.105313 " - ] - }, - "execution_count": 3, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "# Select features for training data.\n", - "ds_query = trans_fg.select([\"fraud_label\", \"category\", \"amount\", \"age_at_transaction\", \"days_until_card_expires\", \"loc_delta\"])\\\n", - " .join(window_aggs_fg.select_except([\"cc_num\"]))\n", - "\n", - "ds_query.show(5)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Recall that we computed the features in `transactions_4h_aggs` using 4-hour aggregates. If we had created multiple feature groups with identical schema for different window lengths, and wanted to include them in the join we would need to include a prefix argument in the join to avoid feature name clash. See the [documentation](https://docs.hopsworks.ai/feature-store-api/latest/generated/api/query_api/#join) for more details." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "🤖 Transformation Functions \n", - "\n", - "We will preprocess our data using *min-max scaling* on numerical features and *label encoding* on categorical features. To do this we simply define a mapping between our features and transformation functions. This ensures that transformation functions such as *min-max scaling* are fitted only on the training data (and not the validation/test data), which ensures that there is no data leakage." - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "metadata": {}, - "outputs": [], - "source": [ - "# Load transformation functions.\n", - "min_max_scaler = fs.get_transformation_function(name=\"min_max_scaler\")\n", - "label_encoder = fs.get_transformation_function(name=\"label_encoder\")\n", - "\n", - "# Map features to transformations.\n", - "transformation_functions = {\n", - " \"category\": label_encoder,\n", - " \"amount\": min_max_scaler,\n", - " \"trans_volume_mavg\": min_max_scaler,\n", - " \"trans_volume_mstd\": min_max_scaler,\n", - " \"trans_freq\": min_max_scaler,\n", - " \"loc_delta\": min_max_scaler,\n", - " \"loc_delta_mavg\": min_max_scaler,\n", - " \"age_at_transaction\": min_max_scaler,\n", - " \"days_until_card_expires\": min_max_scaler,\n", - "}" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## ⚙️ Feature View Creation \n", - "\n", - "The Feature Views allows schema in form of a query with filters, define a model target feature/label and additional transformation functions.\n", - "In order to create a Feature View we may use `fs.create_feature_view()`" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Feature view created successfully, explore it at https://c.app.hopsworks.ai:443/p/124/fs/72/fv/transactions_view/version/1\n" - ] - } - ], - "source": [ - "feature_view = fs.create_feature_view(\n", - " name='transactions_view',\n", - " query=ds_query,\n", - " labels=[\"fraud_label\"],\n", - " transformation_functions=transformation_functions\n", - ")" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "tags": [] - }, - "source": [ - "## 🏋️ Training Dataset Creation\n", - "\n", - "In Hopsworks training data is a query where the projection (set of features) is determined by the parent FeatureView with an optional snapshot on disk of the data returned by the query.\n", - "\n", - "**Training Dataset may contain splits such as:** \n", - "* Training set - the subset of training data used to train a model.\n", - "* Validation set - the subset of training data used to evaluate hparams when training a model\n", - "* Test set - the holdout subset of training data used to evaluate a mode\n", - "\n", - "Training dataset is created using `fs.create_train_validation_test_split()` method." - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Training dataset job started successfully, you can follow the progress at https://c.app.hopsworks.ai/p/124/jobs/named/transactions_view_1_1_create_fv_td_20062022073937/executions\n" - ] - }, - { - "name": "stderr", - "output_type": "stream", - "text": [ - "VersionWarning: Incremented version to `1`.\n" - ] - } - ], - "source": [ - "td_version, td_job = feature_view.create_train_validation_test_split(\n", - " description = 'transactions_dataset',\n", - " data_format = 'csv',\n", - " validation_size = 0.2,\n", - " test_size = 0.1,\n", - " write_options = {'wait_for_job': True},\n", - " coalesce = True,\n", - ")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## 🪝 Training Dataset retreival \n", - "\n", - "To retrieve training data from storage (already materialised) or from feature groups direcly we can use `get_training_dataset` or `get_train_validation_test_split` methods. You need to provide the version of the training dataset you want to retrieve." - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "metadata": {}, - "outputs": [], - "source": [ - "X_train, y_train, X_val, y_val, X_test, y_test = feature_view.get_train_validation_test_split(td_version)" - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
categoryamountage_at_transactiondays_until_card_expiresloc_deltatrans_volume_mstdtrans_volume_mavgtrans_freqloc_delta_mavg
000.0000000.0108580.8504520.0249550.0000000.0000000.0000000.027577
100.0000000.0473780.9437220.0357180.0000000.0000000.0000000.039471
200.0000000.0637590.1320260.0000440.0000000.0000000.0000000.000048
300.0000000.3406030.2084660.2119020.0000000.0000000.0000000.234169
400.0000000.9546610.8748340.1839110.0000000.0000000.0000000.203237
..............................
7420650.0057030.2066130.2289330.0980710.0021560.0021560.0021560.103897
7420750.0073040.9093310.7289890.2146880.0047020.0047020.0047020.210192
7420850.0136290.5162880.3144430.0861540.0058320.0058320.0058320.102090
7420980.0001700.1321640.8164310.2176380.0001700.0001700.0001700.240507
7421080.0004880.4889830.6070040.0434700.0004880.0004880.0004880.048038
\n", - "

74211 rows × 9 columns

\n", - "
" - ], - "text/plain": [ - " category amount age_at_transaction days_until_card_expires \\\n", - "0 0 0.000000 0.010858 0.850452 \n", - "1 0 0.000000 0.047378 0.943722 \n", - "2 0 0.000000 0.063759 0.132026 \n", - "3 0 0.000000 0.340603 0.208466 \n", - "4 0 0.000000 0.954661 0.874834 \n", - "... ... ... ... ... \n", - "74206 5 0.005703 0.206613 0.228933 \n", - "74207 5 0.007304 0.909331 0.728989 \n", - "74208 5 0.013629 0.516288 0.314443 \n", - "74209 8 0.000170 0.132164 0.816431 \n", - "74210 8 0.000488 0.488983 0.607004 \n", - "\n", - " loc_delta trans_volume_mstd trans_volume_mavg trans_freq \\\n", - "0 0.024955 0.000000 0.000000 0.000000 \n", - "1 0.035718 0.000000 0.000000 0.000000 \n", - "2 0.000044 0.000000 0.000000 0.000000 \n", - "3 0.211902 0.000000 0.000000 0.000000 \n", - "4 0.183911 0.000000 0.000000 0.000000 \n", - "... ... ... ... ... \n", - "74206 0.098071 0.002156 0.002156 0.002156 \n", - "74207 0.214688 0.004702 0.004702 0.004702 \n", - "74208 0.086154 0.005832 0.005832 0.005832 \n", - "74209 0.217638 0.000170 0.000170 0.000170 \n", - "74210 0.043470 0.000488 0.000488 0.000488 \n", - "\n", - " loc_delta_mavg \n", - "0 0.027577 \n", - "1 0.039471 \n", - "2 0.000048 \n", - "3 0.234169 \n", - "4 0.203237 \n", - "... ... \n", - "74206 0.103897 \n", - "74207 0.210192 \n", - "74208 0.102090 \n", - "74209 0.240507 \n", - "74210 0.048038 \n", - "\n", - "[74211 rows x 9 columns]" - ] - }, - "execution_count": 8, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "X_train" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
categoryamountage_at_transactiondays_until_card_expiresloc_deltatrans_volume_mstdtrans_volume_mavgtrans_freqloc_delta_mavg
003.336858e-070.8352810.7356710.0435151.052428e-021.052428e-021.052428e-020.088640
106.673716e-070.0302660.4379240.2070046.673716e-076.673716e-076.673716e-070.228756
206.673716e-070.5015130.7705570.0608606.673716e-076.673716e-076.673716e-070.067256
306.673716e-070.6686910.3091890.1177576.673716e-076.673716e-076.673716e-070.130131
406.673716e-070.6719360.7731860.1897456.673716e-076.673716e-076.673716e-070.209683
..............................
2115241.403816e-030.9093310.7289870.0453512.677114e-032.677114e-032.677114e-030.160770
2115341.718482e-030.4765480.2335720.0843732.240900e-032.240900e-032.240900e-030.138877
2115442.564709e-030.5604560.8355850.1476918.005345e-038.005345e-038.005345e-030.176319
2115543.218733e-030.4485470.6437850.0402161.141806e-031.141806e-031.141806e-030.137911
2115683.098940e-030.2668950.2703630.0977793.098940e-033.098940e-033.098940e-030.108053
\n", - "

21157 rows × 9 columns

\n", - "
" - ], - "text/plain": [ - " category amount age_at_transaction days_until_card_expires \\\n", - "0 0 3.336858e-07 0.835281 0.735671 \n", - "1 0 6.673716e-07 0.030266 0.437924 \n", - "2 0 6.673716e-07 0.501513 0.770557 \n", - "3 0 6.673716e-07 0.668691 0.309189 \n", - "4 0 6.673716e-07 0.671936 0.773186 \n", - "... ... ... ... ... \n", - "21152 4 1.403816e-03 0.909331 0.728987 \n", - "21153 4 1.718482e-03 0.476548 0.233572 \n", - "21154 4 2.564709e-03 0.560456 0.835585 \n", - "21155 4 3.218733e-03 0.448547 0.643785 \n", - "21156 8 3.098940e-03 0.266895 0.270363 \n", - "\n", - " loc_delta trans_volume_mstd trans_volume_mavg trans_freq \\\n", - "0 0.043515 1.052428e-02 1.052428e-02 1.052428e-02 \n", - "1 0.207004 6.673716e-07 6.673716e-07 6.673716e-07 \n", - "2 0.060860 6.673716e-07 6.673716e-07 6.673716e-07 \n", - "3 0.117757 6.673716e-07 6.673716e-07 6.673716e-07 \n", - "4 0.189745 6.673716e-07 6.673716e-07 6.673716e-07 \n", - "... ... ... ... ... \n", - "21152 0.045351 2.677114e-03 2.677114e-03 2.677114e-03 \n", - "21153 0.084373 2.240900e-03 2.240900e-03 2.240900e-03 \n", - "21154 0.147691 8.005345e-03 8.005345e-03 8.005345e-03 \n", - "21155 0.040216 1.141806e-03 1.141806e-03 1.141806e-03 \n", - "21156 0.097779 3.098940e-03 3.098940e-03 3.098940e-03 \n", - "\n", - " loc_delta_mavg \n", - "0 0.088640 \n", - "1 0.228756 \n", - "2 0.067256 \n", - "3 0.130131 \n", - "4 0.209683 \n", - "... ... \n", - "21152 0.160770 \n", - "21153 0.138877 \n", - "21154 0.176319 \n", - "21155 0.137911 \n", - "21156 0.108053 \n", - "\n", - "[21157 rows x 9 columns]" - ] - }, - "execution_count": 9, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "X_val" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The feature view and training dataset are now visible in the UI\n", - "\n", - "![fg-overview](../images/fv_overview.gif)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## ⏭️ **Next:** Part 03 \n", - "\n", - "In the following notebook, we will train a model on the dataset we created in this notebook and have quick overview of the lineage." - ] - } - ], - "metadata": { - "interpreter": { - "hash": "31f2aee4e71d21fbe5cf8b01ff0e069b9275f58929596ceb00d14d90e3e16cd6" - }, - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "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.9" - } - }, - "nbformat": 4, - "nbformat_minor": 4 -} \ No newline at end of file diff --git a/docs/tutorials/fraud_batch/3_model_training.ipynb b/docs/tutorials/fraud_batch/3_model_training.ipynb deleted file mode 100755 index 626e26501..000000000 --- a/docs/tutorials/fraud_batch/3_model_training.ipynb +++ /dev/null @@ -1,631 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "543717fc", - "metadata": {}, - "source": [ - "![Screenshot from 2022-06-16 14-24-57.png](data:image/png;base64,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)" - ] - }, - { - "cell_type": "markdown", - "id": "d5db0af3", - "metadata": {}, - "source": [ - "# Part 03: Model training & UI Exploration\n", - "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/logicalclocks/hopsworks-tutorials/blob/master/fraud_batch/3_model_training.ipynb)\n", - "\n", - "In this last notebook, we will train a model on the dataset we created in the previous tutorial. We will train our model using standard Python and Scikit-learn, although it could just as well be trained with other machine learning frameworks such as PySpark, TensorFlow, and PyTorch. We will also show some of the exploration that can be done in Hopsworks, notably the search functions and the lineage.\n", - "\n", - "## 🗒️ This notebook is divided in 3 main sections:\n", - "1. **Loading the training data**\n", - "2. **Train the model**\n", - "3. **Explore feature groups and views** via the UI.\n", - "\n", - "![tutorial-flow](../images/03_model.png)" - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "79d97c37", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Connected. Call `.close()` to terminate connection gracefully.\n", - "\n", - "Logged in to project, explore it here https://c.app.hopsworks.ai:443/p/124\n" - ] - }, - { - "name": "stderr", - "output_type": "stream", - "text": [ - "DeprecationWarning: the imp module is deprecated in favour of importlib; see the module's documentation for alternative uses\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Connected. Call `.close()` to terminate connection gracefully.\n" - ] - } - ], - "source": [ - "import hopsworks\n", - "\n", - "project = hopsworks.login()\n", - "\n", - "fs = project.get_feature_store()" - ] - }, - { - "cell_type": "markdown", - "id": "f0d8bfb5", - "metadata": {}, - "source": [ - "## ✨ Load Training Data \n", - "\n", - "First, we'll need to fetch the training dataset that we created in the previous notebook. We will use January - February data training and testing." - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "c2702114", - "metadata": {}, - "outputs": [], - "source": [ - "import pandas as pd\n", - "from sklearn.linear_model import LogisticRegression\n", - "\n", - "# Load data.\n", - "feature_view = fs.get_feature_view(\"transactions_view\", 1)\n", - "X_train, y_train, X_val, y_val, X_test, y_test = feature_view.get_train_validation_test_split(1)" - ] - }, - { - "cell_type": "markdown", - "id": "36070a3c", - "metadata": {}, - "source": [ - "We will train a model to predict `fraud_label` given the rest of the features." - ] - }, - { - "cell_type": "markdown", - "id": "94acc187", - "metadata": {}, - "source": [ - "Let's check the distribution of our target label." - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "2dc84cc8", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "fraud_label\n", - "0 0.998545\n", - "1 0.001455\n", - "dtype: float64" - ] - }, - "execution_count": 3, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "y_train.value_counts(normalize=True)" - ] - }, - { - "cell_type": "markdown", - "id": "e546c204", - "metadata": {}, - "source": [ - "Notice that the distribution is extremely skewed, which is natural considering that fraudulent transactions make up a tiny part of all transactions. Thus we should somehow address the class imbalance. There are many approaches for this, such as weighting the loss function, over- or undersampling, creating synthetic data, or modifying the decision threshold. In this example, we'll use the simplest method which is to just supply a class weight parameter to our learning algorithm. The class weight will affect how much importance is attached to each class, which in our case means that higher importance will be placed on positive (fraudulent) samples." - ] - }, - { - "cell_type": "markdown", - "id": "39fe274e", - "metadata": {}, - "source": [ - "## 🏃 Train Model\n", - "\n", - "Next we'll train a model. Here, we set the class weight of the positive class to be twice as big as the negative class." - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "70bcd17b", - "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "DataConversionWarning: A column-vector y was passed when a 1d array was expected. Please change the shape of y to (n_samples, ), for example using ravel().\n" - ] - }, - { - "data": { - "text/plain": [ - "LogisticRegression(class_weight={0: 0.09999999999999998, 1: 0.9},\n", - " solver='liblinear')" - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "# Train model.\n", - "pos_class_weight = 0.9\n", - "clf = LogisticRegression(class_weight={0: 1.0 - pos_class_weight, 1: pos_class_weight}, solver='liblinear')\n", - "clf.fit(X_train, y_train)" - ] - }, - { - "cell_type": "markdown", - "id": "c3bbd9c3", - "metadata": {}, - "source": [ - "Let's see how well it performs on our validation data." - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "6fbd02f5", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - " precision recall f1-score support\n", - "\n", - " 0 1.00 1.00 1.00 21132\n", - " 1 0.00 0.00 0.00 25\n", - "\n", - " accuracy 1.00 21157\n", - " macro avg 0.50 0.50 0.50 21157\n", - "weighted avg 1.00 1.00 1.00 21157\n", - "\n" - ] - }, - { - "name": "stderr", - "output_type": "stream", - "text": [ - "UndefinedMetricWarning: Precision and F-score are ill-defined and being set to 0.0 in labels with no predicted samples. Use `zero_division` parameter to control this behavior.\n", - "UndefinedMetricWarning: Precision and F-score are ill-defined and being set to 0.0 in labels with no predicted samples. Use `zero_division` parameter to control this behavior.\n", - "UndefinedMetricWarning: Precision and F-score are ill-defined and being set to 0.0 in labels with no predicted samples. Use `zero_division` parameter to control this behavior.\n" - ] - } - ], - "source": [ - "from sklearn.metrics import classification_report\n", - "\n", - "preds = clf.predict(X_val)\n", - "\n", - "print(classification_report(y_val, preds))\n" - ] - }, - { - "cell_type": "markdown", - "id": "4e32237f", - "metadata": {}, - "source": [ - "## Use the model to score transactions \n", - "We trained model based on January - February data. Now lets retrieve March data and score whether transactions are fraudulend or not \n" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "1b284826", - "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "VersionWarning: No training dataset version was provided to initialise batch scoring . Defaulting to version 1.\n" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "2022-06-20 09:44:08,897 INFO: USE `robin100_featurestore`\n", - "2022-06-20 09:44:09,915 INFO: WITH right_fg0 AS (SELECT *\n", - "FROM (SELECT `fg1`.`category` `category`, `fg1`.`amount` `amount`, `fg1`.`age_at_transaction` `age_at_transaction`, `fg1`.`days_until_card_expires` `days_until_card_expires`, `fg1`.`loc_delta` `loc_delta`, `fg1`.`cc_num` `join_pk_cc_num`, `fg1`.`datetime` `join_evt_datetime`, `fg0`.`trans_volume_mstd` `trans_volume_mstd`, `fg0`.`trans_volume_mavg` `trans_volume_mavg`, `fg0`.`trans_freq` `trans_freq`, `fg0`.`loc_delta_mavg` `loc_delta_mavg`, RANK() OVER (PARTITION BY `fg1`.`cc_num`, `fg1`.`datetime` ORDER BY `fg0`.`datetime` DESC) pit_rank_hopsworks\n", - "FROM `robin100_featurestore`.`transactions_1` `fg1`\n", - "INNER JOIN `robin100_featurestore`.`transactions_4h_aggs_1` `fg0` ON `fg1`.`cc_num` = `fg0`.`cc_num` AND `fg1`.`datetime` >= `fg0`.`datetime`\n", - "WHERE `fg1`.`datetime` >= 1641164401000 AND `fg1`.`datetime` <= 1648763999000) NA\n", - "WHERE `pit_rank_hopsworks` = 1) (SELECT `right_fg0`.`category` `category`, `right_fg0`.`amount` `amount`, `right_fg0`.`age_at_transaction` `age_at_transaction`, `right_fg0`.`days_until_card_expires` `days_until_card_expires`, `right_fg0`.`loc_delta` `loc_delta`, `right_fg0`.`trans_volume_mstd` `trans_volume_mstd`, `right_fg0`.`trans_volume_mavg` `trans_volume_mavg`, `right_fg0`.`trans_freq` `trans_freq`, `right_fg0`.`loc_delta_mavg` `loc_delta_mavg`\n", - "FROM right_fg0)\n" - ] - }, - { - "name": "stderr", - "output_type": "stream", - "text": [ - "UserWarning: pandas only support SQLAlchemy connectable(engine/connection) ordatabase string URI or sqlite3 DBAPI2 connectionother DBAPI2 objects are not tested, please consider using SQLAlchemy\n" - ] - } - ], - "source": [ - "from datetime import datetime\n", - "date_format = \"%Y-%m-%d %H:%M:%S\"\n", - "# Create training datasets based event time filter\n", - "start_time = int(float(datetime.strptime(\"2022-01-03 00:00:01\", date_format).timestamp()) * 1000)\n", - "end_time = int(float(datetime.strptime(\"2022-03-31 23:59:59\", date_format).timestamp()) * 1000)\n", - "\n", - "march_transactions = feature_view.get_batch_data(start_time = start_time, end_time = end_time)" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "98ade6cf", - "metadata": {}, - "outputs": [ - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
categoryamountage_at_transactiondays_until_card_expiresloc_deltatrans_volume_mstdtrans_volume_mavgtrans_freqloc_delta_mavg
040.0031200.0915970.1397470.0000000.0031200.0031200.0031200.000000
120.0021730.0916150.1394740.1222000.0021730.0021730.0021730.135041
240.0000080.0916220.1393670.1201250.0000080.0000080.0000080.132748
340.0000470.0916280.1392910.0000000.0000280.0000280.0000280.066374
440.0006590.0917250.1378620.0402700.0006590.0006590.0006590.044502
..............................
10299700.0007360.3573640.4812940.2289040.0007360.0007360.0007360.252957
10299800.0028160.3573990.4807780.1667190.0028160.0028160.0028160.184238
10299900.0029340.3574030.4807210.1668740.0028750.0028750.0028750.184323
10300000.0103220.3574700.4797350.0011490.0103220.0103220.0103220.001270
10300100.0005920.3576040.4777600.1666900.0005920.0005920.0005920.184206
\n", - "

103002 rows × 9 columns

\n", - "
" - ], - "text/plain": [ - " category amount age_at_transaction days_until_card_expires \\\n", - "0 4 0.003120 0.091597 0.139747 \n", - "1 2 0.002173 0.091615 0.139474 \n", - "2 4 0.000008 0.091622 0.139367 \n", - "3 4 0.000047 0.091628 0.139291 \n", - "4 4 0.000659 0.091725 0.137862 \n", - "... ... ... ... ... \n", - "102997 0 0.000736 0.357364 0.481294 \n", - "102998 0 0.002816 0.357399 0.480778 \n", - "102999 0 0.002934 0.357403 0.480721 \n", - "103000 0 0.010322 0.357470 0.479735 \n", - "103001 0 0.000592 0.357604 0.477760 \n", - "\n", - " loc_delta trans_volume_mstd trans_volume_mavg trans_freq \\\n", - "0 0.000000 0.003120 0.003120 0.003120 \n", - "1 0.122200 0.002173 0.002173 0.002173 \n", - "2 0.120125 0.000008 0.000008 0.000008 \n", - "3 0.000000 0.000028 0.000028 0.000028 \n", - "4 0.040270 0.000659 0.000659 0.000659 \n", - "... ... ... ... ... \n", - "102997 0.228904 0.000736 0.000736 0.000736 \n", - "102998 0.166719 0.002816 0.002816 0.002816 \n", - "102999 0.166874 0.002875 0.002875 0.002875 \n", - "103000 0.001149 0.010322 0.010322 0.010322 \n", - "103001 0.166690 0.000592 0.000592 0.000592 \n", - "\n", - " loc_delta_mavg \n", - "0 0.000000 \n", - "1 0.135041 \n", - "2 0.132748 \n", - "3 0.066374 \n", - "4 0.044502 \n", - "... ... \n", - "102997 0.252957 \n", - "102998 0.184238 \n", - "102999 0.184323 \n", - "103000 0.001270 \n", - "103001 0.184206 \n", - "\n", - "[103002 rows x 9 columns]" - ] - }, - "execution_count": 7, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "march_transactions" - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "cf708c28", - "metadata": {}, - "outputs": [], - "source": [ - "predictions = clf.predict(march_transactions)" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "id": "c9c42003", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "array([0, 0, 0, ..., 0, 0, 0])" - ] - }, - "execution_count": 9, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "predictions" - ] - }, - { - "cell_type": "markdown", - "id": "d8c6b712", - "metadata": { - "jp-MarkdownHeadingCollapsed": true, - "tags": [] - }, - "source": [ - "## 👓 Exploration\n", - "In the Hopsworks feature store, the metadata allows for multiple levels of explorations and review. Here we will show a few of those capacities. \n", - "\n", - "### 🔎 Search \n", - "Using the search function in the ui, you can query any aspect of the feature groups, feature_view and training data that was previously created.\n", - "\n", - "### 📊 Statistics \n", - "We can also enable statistics in one or all the feature groups." - ] - }, - { - "cell_type": "code", - "execution_count": 10, - "id": "2b1eed95", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Statistics Job started successfully, you can follow the progress at https://c.app.hopsworks.ai/p/124/jobs/named/transactions_1_compute_stats_20062022074522/executions\n" - ] - } - ], - "source": [ - "trans_fg = fs.get_feature_group(\"transactions\", version = 1)\n", - "trans_fg.statistics_config = {\n", - " \"enabled\": True,\n", - " \"histograms\": True,\n", - " \"correlations\": True\n", - "}\n", - "\n", - "trans_fg.update_statistics_config()\n", - "trans_fg.compute_statistics()" - ] - }, - { - "cell_type": "markdown", - "id": "ee9d4ce0", - "metadata": {}, - "source": [ - "![fg-statistics](../images/fg_statistics.gif)\n", - "\n", - "\n", - "### ⛓️ Lineage \n", - "In all the feature groups and feature view you can look at the relation between each abstractions; what feature group created which training dataset and that is used in which model.\n", - "This allows for a clear undestanding of the pipeline in relation to each element. " - ] - }, - { - "cell_type": "markdown", - "id": "ee42a342", - "metadata": {}, - "source": [ - "## 🎁 Wrapping things up \n", - "\n", - "We have now performed a simple training with training data that we have created in the feature store. This concludes the fisrt module and introduction to the core aspect of the feauture store. In the second module we will introduce streaming and external feature groups for a similar fraud use case." - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "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.9" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} \ No newline at end of file diff --git a/docs/tutorials/fraud_online/1_feature_groups.ipynb b/docs/tutorials/fraud_online/1_feature_groups.ipynb deleted file mode 100755 index 370815545..000000000 --- a/docs/tutorials/fraud_online/1_feature_groups.ipynb +++ /dev/null @@ -1,403 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "dba770f4", - "metadata": {}, - "source": [ - "![Screenshot from 2022-06-16 14-24-57.png](data:image/png;base64,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)" - ] - }, - { - "cell_type": "markdown", - "id": "86f66405", - "metadata": {}, - "source": [ - "# Part 01: Load, Engineer & Connect\n", - "\n", - "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/logicalclocks/hopsworks-tutorials/blob/master/fraud_online/1_feature_groups.ipynb)\n", - "\n", - "This is the first part of the quick start series of tutorials about Hopsworks Feature Store. As part of this first module, we will work with data related to credit card transactions. \n", - "The objective of this tutorial is to demonstrate how to work with the **Hopworks Feature Store** for batch data with a goal of training and deploying a model that can predict fraudulent transactions.\n", - "\n", - "## 🗒️ This notebook is divided in 3 sections:\n", - "1. Loading the data and feature engineeing,\n", - "2. Connect to the Hopsworks feature store,\n", - "3. Create feature groups and upload them to the feature store.\n", - "\n", - "![tutorial-flow](../images/01_featuregroups.png)\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "91fef88b", - "metadata": {}, - "outputs": [], - "source": [ - "!pip install -U hopsworks==3.0.0rc5 --quiet" - ] - }, - { - "cell_type": "markdown", - "id": "86cd6dca", - "metadata": {}, - "source": [ - "First of all we will load the data and do some feature engineering on it." - ] - }, - { - "cell_type": "markdown", - "id": "747920f7", - "metadata": {}, - "source": [ - "## 💽 Loading the Data \n", - "\n", - "The data we will use comes from three different CSV files:\n", - "\n", - "- `credit_cards.csv`: credit card information such as the expiration date and provider.\n", - "- `transactions.csv`: events containing information about when a credit card was used, such as a timestamp, location, and the amount spent. A boolean fraud_label variable (True/False) tells us whether a transaction was fraudulent or not.\n", - "- `profiles.csv`: credit card user information such as birthdate and city of residence.\n", - "\n", - "In a production system, these CSV files would originate from separate data sources or tables, and probably separate data pipelines. **All three files have a common credit card number column cc_num, which you will use later to join features together from the different datasets.**\n", - "\n", - "Now, you can go ahead and load the data." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "bc5ce3a2", - "metadata": {}, - "outputs": [], - "source": [ - "import numpy as np\n", - "import pandas as pd\n", - "from datetime import datetime, timedelta\n", - " \n", - "credit_cards_df = pd.read_csv(\"https://repo.hops.works/master/hopsworks-tutorials/data/card_fraud_online/credit_cards.csv\")\n", - "credit_cards_df.head(3)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "ba8a61a7", - "metadata": {}, - "outputs": [], - "source": [ - "profiles_df = pd.read_csv(\"https://repo.hops.works/master/hopsworks-tutorials/data/card_fraud_online/profiles.csv\", parse_dates=[\"birthdate\"])\n", - "profiles_df.head(3)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "776d60b9", - "metadata": {}, - "outputs": [], - "source": [ - "trans_df = pd.read_csv(\"https://repo.hops.works/master/hopsworks-tutorials/data/card_fraud_online/transactions.csv\", parse_dates=[\"datetime\"])\n", - "trans_df.head(3)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "d3077178", - "metadata": {}, - "outputs": [], - "source": [ - "trans_df = trans_df[trans_df.category == \"Cash Withdrawal\"].reset_index(level=0, drop=True)\n", - "trans_df[\"country\"] = trans_df[\"country\"].fillna(\"US\")\n", - "profiles_df = profiles_df[profiles_df.cc_num.isin(trans_df.cc_num.unique())].reset_index(level=0, drop=True)\n", - "credit_cards_df = credit_cards_df[credit_cards_df.cc_num.isin(trans_df.cc_num.unique())].reset_index(level=0, drop=True)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "a271cad8", - "metadata": {}, - "outputs": [], - "source": [ - "trans_df.sort_values([\"datetime\",\"cc_num\"], inplace=True)" - ] - }, - { - "cell_type": "markdown", - "id": "97f66a0b", - "metadata": {}, - "source": [ - "## 🛠️ Feature Engineering \n", - "\n", - "Fraudulent transactions can differ from regular ones in many different ways. Typical red flags would for instance be a large transaction volume/frequency in the span of a few hours. It could also be the case that elderly people in particular are targeted by fraudsters. To facilitate model learning we will create additional features based on these patterns. In particular, we will create two types of features:\n", - "1. **Features that aggregate data from different data sources**. This could for instance be the age of a customer at the time of a transaction, which combines the `birthdate` feature from `profiles.csv` with the `datetime` feature from `transactions.csv`.\n", - "2. **Features that aggregate data from multiple time steps**. An example of this could be the transaction frequency of a credit card in the span of a few hours, which is computed using a window function.\n", - "\n", - "Let's start with the first category." - ] - }, - { - "cell_type": "markdown", - "id": "3a7d3193", - "metadata": {}, - "source": [ - "Now you are ready to start by computing the distance between consecutive transactions, which we will call `loc_delta`.\n", - "Here we use the [Haversine distance](https://scikit-learn.org/stable/modules/generated/sklearn.metrics.pairwise.haversine_distances.html?highlight=haversine#sklearn.metrics.pairwise.haversine_distances) to quantify the distance between two longitude and latitude coordinates." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "165f5f47", - "metadata": {}, - "outputs": [], - "source": [ - "from math import radians\n", - "\n", - "# Feature engineering.\n", - "trans_df.sort_values(\"datetime\", inplace=True)\n", - "trans_df[[\"longitude\", \"latitude\"]] = trans_df[[\"longitude\", \"latitude\"]].applymap(radians)\n", - "\n", - "def haversine(long, lat, shift):\n", - " \"\"\"Compute Haversine distance between each consecutive coordinate in (long, lat).\"\"\"\n", - "\n", - " long_shifted = long.shift(shift)\n", - " lat_shifted = lat.shift(shift)\n", - " long_diff = long_shifted - long\n", - " lat_diff = lat_shifted - lat\n", - "\n", - " a = np.sin(lat_diff/2.0)**2\n", - " b = np.cos(lat) * np.cos(lat_shifted) * np.sin(long_diff/2.0)**2\n", - " c = 2*np.arcsin(np.sqrt(a + b))\n", - "\n", - " return c\n", - "\n", - "def time_delta(datetime_value, shift):\n", - " \"\"\"Compute time difference between each consecutive transaction.\"\"\"\n", - "\n", - " time_shifted = datetime_value.shift(shift)\n", - " return time_shifted\n", - "\n", - "trans_df[\"loc_delta_t_plus_1\"] = trans_df.groupby(\"cc_num\")\\\n", - " .apply(lambda x : haversine(x[\"longitude\"], x[\"latitude\"], 1))\\\n", - " .reset_index(level=0, drop=True)\\\n", - " .fillna(0)\n", - "\n", - "trans_df[\"loc_delta_t_minus_1\"] = trans_df.groupby(\"cc_num\")\\\n", - " .apply(lambda x : haversine(x[\"longitude\"], x[\"latitude\"], -1))\\\n", - " .reset_index(level=0, drop=True)\\\n", - " .fillna(0)\n", - "\n", - "trans_df[\"time_delta_t_plus_1\"] = trans_df.groupby(\"cc_num\")\\\n", - " .apply(lambda x : time_delta(x[\"datetime\"], 1 ))\\\n", - " .reset_index(level=0, drop=True)\n", - "\n", - "trans_df[\"time_delta_t_minus_1\"] = trans_df.groupby(\"cc_num\")\\\n", - " .apply(lambda x : time_delta(x[\"datetime\"], -1))\\\n", - " .reset_index(level=0, drop=True)\n", - "\n", - "trans_df[\"time_delta_t_plus_1\"] = (trans_df.datetime - trans_df.time_delta_t_plus_1 )/ np.timedelta64(1, 'D')\n", - "trans_df[\"time_delta_t_minus_1\"] = (trans_df.time_delta_t_minus_1 - trans_df.datetime )/ np.timedelta64(1, 'D')\n", - "trans_df[\"time_delta_t_plus_1\"] = trans_df.time_delta_t_plus_1.fillna(0)\n", - "trans_df[\"time_delta_t_minus_1\"] = trans_df.time_delta_t_minus_1.fillna(0) " - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "1755e299", - "metadata": {}, - "outputs": [], - "source": [ - "trans_df = trans_df[[\"tid\",\"datetime\",\"cc_num\",\"category\",\"amount\",\"city\",\"country\",\"fraud_label\",\"loc_delta_t_plus_1\", \"loc_delta_t_minus_1\", \"time_delta_t_plus_1\", \"time_delta_t_minus_1\"]]" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "81b4b36c", - "metadata": {}, - "outputs": [], - "source": [ - "trans_df.datetime = trans_df.datetime.values.astype(np.int64) // 10 ** 6\n", - "trans_df" - ] - }, - { - "cell_type": "markdown", - "id": "d93ace20", - "metadata": {}, - "source": [ - "## 🪄 Creating Feature Groups \n", - "\n", - "A [feature group](https://docs.hopsworks.ai/feature-store-api/latest/generated/feature_group/) can be seen as a collection of conceptually related features. In our case, we will create a feature group for the transaction data and a feature group for the windowed aggregations on the transaction data. Both will have `tid` as primary key, which will allow us to join them when creating a dataset in the next tutorial.\n", - "\n", - "Feature groups can also be used to define a namespace for features. For instance, in a real-life setting we would likely want to experiment with different window lengths. In that case, we can create feature groups with identical schema for each window length. \n", - "\n", - "Before you can create a feature group you need to connect to our feature store." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "7997d511", - "metadata": {}, - "outputs": [], - "source": [ - "import hopsworks\n", - "\n", - "project = hopsworks.login()\n", - "\n", - "fs = project.get_feature_store()" - ] - }, - { - "cell_type": "markdown", - "id": "4aa97688", - "metadata": {}, - "source": [ - "To create a feature group we need to give it a name and specify a primary key. It is also good to provide a description of the contents of the feature group and a version number, if it is not defined it will automatically be incremented to `1`." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "8be295ac", - "metadata": {}, - "outputs": [], - "source": [ - "trans_fg = fs.get_or_create_feature_group(\n", - " name=\"transactions_online_fg\",\n", - " version=1,\n", - " description=\"Transaction data\",\n", - " primary_key=['cc_num'],\n", - " event_time=['datetime'],\n", - " online_enabled=True\n", - ")\n" - ] - }, - { - "cell_type": "markdown", - "id": "9d1c7350", - "metadata": {}, - "source": [ - "Here you have also set `online_enabled=True`, which enables low latency access to the data. A full list of arguments can be found in the [documentation](https://docs.hopsworks.ai/feature-store-api/latest/generated/api/feature_store_api/#create_feature_group).\n", - "\n", - "At this point, you have only specified some metadata for the feature group. It does not store any data or even have a schema defined for the data. To make the feature group persistent you need to populate it with its associated data using the `insert` function." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "0ad7d71d", - "metadata": {}, - "outputs": [], - "source": [ - "trans_fg.insert(trans_df)" - ] - }, - { - "cell_type": "markdown", - "id": "a06ee84d", - "metadata": {}, - "source": [ - "We can move on and do the same thing for the feature group with our windows aggregation." - ] - }, - { - "cell_type": "markdown", - "id": "dcc4e7af", - "metadata": {}, - "source": [ - "Click on the hyperlink printed in the cell output above to inspect your feature group in the UI.\n", - "\n", - "![fg-overview](../images/fg_overview.gif)" - ] - }, - { - "cell_type": "markdown", - "id": "8e8fa1c1", - "metadata": {}, - "source": [ - "## 👓 Exploration\n", - "In the Hopsworks feature store, the metadata allows for multiple levels of explorations and review. Here we will show a few of those capacities. \n", - "\n", - "### 🔎 Search \n", - "Using the search function in the ui, you can query any aspect of the feature groups, feature_view and training data that was previously created.\n", - "\n", - "### 📊 Statistics \n", - "You can also enable statistics in the feature groups." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "a09bcf81", - "metadata": {}, - "outputs": [], - "source": [ - "trans_fg = fs.get_feature_group(\"transactions_online_fg\", version = 1)\n", - "trans_fg.statistics_config = {\n", - " \"enabled\": True,\n", - " \"histograms\": True,\n", - " \"correlations\": True\n", - "}\n", - "\n", - "trans_fg.update_statistics_config()\n", - "trans_fg.compute_statistics()" - ] - }, - { - "cell_type": "markdown", - "id": "a35c1ef3", - "metadata": {}, - "source": [ - "![fg-statistics](../images/fg_statistics.gif)\n" - ] - }, - { - "cell_type": "markdown", - "id": "b9d96f3c", - "metadata": {}, - "source": [ - "## ⏭️ **Next:** Part 02 \n", - "\n", - "In the following notebook you will use our feature groups to create a dataset you can train a model on." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "d12c32f5", - "metadata": {}, - "outputs": [], - "source": [] - } - ], - "metadata": { - "interpreter": { - "hash": "e1ddeae6eefc765c17da80d38ea59b893ab18c0c0904077a035ef84cfe367f83" - }, - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "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.9" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} \ No newline at end of file diff --git a/docs/tutorials/fraud_online/2_feature_view_creation.ipynb b/docs/tutorials/fraud_online/2_feature_view_creation.ipynb deleted file mode 100755 index 8ec86a2f1..000000000 --- a/docs/tutorials/fraud_online/2_feature_view_creation.ipynb +++ /dev/null @@ -1,302 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "![Screenshot from 2022-06-16 14-24-57.png](data:image/png;base64,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)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Part 02: Training Data & Feature views\n", - "\n", - "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/logicalclocks/hopsworks-tutorials/blob/master/fraud_online/2_feature_view_creation.ipynb)\n", - "\n", - "This is the second part of the quick start series of tutorials about Hopsworks Feature Store. This notebook explains how to read from a feature group and create training dataset within the feature store\n", - "\n", - "## 🗒️ In this notebook we will see how to create a training dataset from the feature groups: \n", - "1. **Select the features** we want to train our model on,\n", - "2. **How the features should be preprocessed,**\n", - "3. **Create a dataset** for training fraud detection model.\n", - "\n", - "![tutorial-flow](../images/02_training-dataset.png) " - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "import hopsworks\n", - "\n", - "project = hopsworks.login()\n", - "\n", - "fs = project.get_feature_store()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## 🔪 Feature Selection \n", - "\n", - "We start by selecting all the features we want to include for model training/inference." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "# Load feature groups.\n", - "trans_fg = fs.get_feature_group('transactions_online_fg', version=1)\n", - "\n", - "# Select features for training data.\n", - "ds_query = trans_fg.select([\"fraud_label\", \"loc_delta_t_plus_1\", \"loc_delta_t_minus_1\", \"time_delta_t_plus_1\", \"time_delta_t_minus_1\", \"country\"])\n", - "\n", - "# uncomment this if you would like to view query results\n", - "# ds_query.show(5)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Recall that you computed the features in `transactions_fg`. If you had created multiple feature groups with identical schema for different window lengths, and wanted to include them in the join you would need to include a prefix argument in the join to avoid feature name clash. See the [documentation](https://docs.hopsworks.ai/feature-store-api/latest/generated/api/query_api/#join) for more details." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "🤖 Transformation Functions \n", - "\n", - "We will preprocess our data using *min-max scaling* on numerical features and *label encoding* on categorical features. To do this we simply define a mapping between our features and transformation functions. This ensures that transformation functions such as *min-max scaling* are fitted only on the training data (and not the validation/test data), which ensures that there is no data leakage." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "# Load the transformation functions.\n", - "min_max_scaler = fs.get_transformation_function(name=\"min_max_scaler\")\n", - "label_encoder = fs.get_transformation_function(name=\"label_encoder\")\n", - "\n", - "# Map features to transformation functions.\n", - "transformation_functions = {\n", - " \"loc_delta_t_plus_1\": min_max_scaler, \n", - " \"loc_delta_t_minus_1\": min_max_scaler, \n", - " \"time_delta_t_plus_1\": min_max_scaler, \n", - " \"time_delta_t_minus_1\": min_max_scaler,\n", - " \"country\": label_encoder\n", - "}" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## ⚙️ Feature View Creation \n", - "\n", - "The Feature Views allows schema in form of a query with filters, define a model target feature/label and additional transformation functions.\n", - "In order to create a Feature View we may use `fs.create_feature_view()`" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "feature_view = fs.create_feature_view(\n", - " name='fraud_online_model_view',\n", - " query=ds_query,\n", - " labels=[\"fraud_label\"],\n", - " transformation_functions=transformation_functions\n", - ")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "To view and explore data in the feature view we can retrieve batch data using `get_batch_data()` method " - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## 🏋️ Training Dataset Creation\n", - "\n", - "In Hopsworks training data is a query where the projection (set of features) is determined by the parent FeatureView with an optional snapshot on disk of the data returned by the query.\n", - "\n", - "**Training Dataset may contain splits such as:** \n", - "* Training set - the subset of training data used to train a model.\n", - "* Validation set - the subset of training data used to evaluate hparams when training a model\n", - "* Test set - the holdout subset of training data used to evaluate a mode\n", - "\n", - "Training dataset is created using `fs.create_training_dataset()` method.\n", - "\n", - "**From feature view APIs we can also create training datasts based on even time filters specifing `start_time` and `end_time`** \n", - "\n" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "from datetime import datetime\n", - "date_format = \"%Y-%m-%d %H:%M:%S\"" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "# Create training datasets based event time filter\n", - "start_time = int(float(datetime.strptime(\"2022-01-01 00:00:01\", date_format).timestamp()) * 1000)\n", - "end_time = int(float(datetime.strptime(\"2022-02-28 23:59:59\", date_format).timestamp()) * 1000)\n", - "\n", - "td_jan_feb_version, td_job = feature_view.create_training_data(\n", - " start_time = start_time,\n", - " end_time = end_time, \n", - " description = 'transactions_dataset_jan_feb',\n", - " data_format = \"csv\",\n", - " coalesce = True,\n", - " write_options = {'wait_for_job': True},\n", - " )" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "start_time = int(float(datetime.strptime(\"2022-03-01 00:00:01\", date_format).timestamp()) * 1000)\n", - "end_time = int(float(datetime.strptime(\"2022-03-31 23:59:59\", date_format).timestamp()) * 1000)\n", - "\n", - "td_mar_version, td_job = feature_view.create_training_data(\n", - " start_time = start_time,\n", - " end_time = end_time,\n", - " description = 'transactions_dataset_mar',\n", - " data_format = \"csv\",\n", - " coalesce = True,\n", - " write_options = {'wait_for_job': True},\n", - " )\n" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## 🪝 Training Dataset retreival \n", - "\n", - "To retrieve training data from storage (already materialised) or from feature groups direcly we can use `get_training_dataset_splits` or `get_training_dataset` methods. If version is not provided or provided version has not already existed, it creates a new version of training data according to given arguments and returns a dataframe. If version is provided and has already existed, it reads training data from storage or feature groups and returns a dataframe. If split is provided, it reads the specific split." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "train_jan_feb_x, train_jan_feb_y = feature_view.get_training_data(td_jan_feb_version)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "test_mar_x, test_mar_y = feature_view.get_training_data(td_mar_version)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "train_jan_feb_x" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "test_mar_x" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The feature view and training dataset are now visible in the UI\n", - "\n", - "![fg-overview](../images/fv_overview.gif)\n", - "\n", - "### ⛓️ Lineage \n", - "In all the feature groups and feature view you can look at the relation between each abstractions; what feature group created which training dataset and that is used in which model.\n", - "This allows for a clear undestanding of the pipeline in relation to each element. \n", - "\n", - "![provenance](../images/provenance.gif)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## ⏭️ **Next:** Part 03 \n", - "\n", - "In the following notebook, you will train a model on the dataset you created in this notebook." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [] - } - ], - "metadata": { - "interpreter": { - "hash": "31f2aee4e71d21fbe5cf8b01ff0e069b9275f58929596ceb00d14d90e3e16cd6" - }, - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "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.9" - } - }, - "nbformat": 4, - "nbformat_minor": 4 -} diff --git a/docs/tutorials/fraud_online/3_model_training.ipynb b/docs/tutorials/fraud_online/3_model_training.ipynb deleted file mode 100755 index 9409ba04f..000000000 --- a/docs/tutorials/fraud_online/3_model_training.ipynb +++ /dev/null @@ -1,555 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "65c1b926", - "metadata": {}, - "source": [ - "![Screenshot from 2022-06-16 14-24-57.png](data:image/png;base64,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)" - ] - }, - { - "cell_type": "markdown", - "id": "1a97d239", - "metadata": {}, - "source": [ - "# Part 03: Model training & UI Exploration\n", - "\n", - "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/logicalclocks/hopsworks-tutorials/blob/master/fraud_online/3_model_training.ipynb)\n", - "\n", - "In this last notebook, we will train a model on the dataset we created in the previous tutorial. We will train our model using standard Python and Scikit-learn, although it could just as well be trained with other machine learning frameworks such as PySpark, TensorFlow, and PyTorch. We will also show some of the exploration that can be done in Hopsworks, notably the search functions and the lineage.\n", - "\n", - "## 🗒️ This notebook is divided in 5 main sections:\n", - "1. **Loading the training data**\n", - "2. **Train the model**\n", - "3. **Register model to Hopsworks model registry**.\n", - "4. **Deploy the model on KServe behind Hopsworks for real-time inference requests**.\n", - "5. **Test model deployment and use model serving rest APIs**.\n", - "\n", - "![tutorial-flow](../images/03_model.png)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "62f98488", - "metadata": {}, - "outputs": [], - "source": [ - "import hopsworks\n", - "\n", - "project = hopsworks.login()\n", - "\n", - "fs = project.get_feature_store()" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "f41f8378", - "metadata": {}, - "outputs": [], - "source": [ - "feature_view = fs.get_feature_view(\"fraud_online_model_view\", 1)" - ] - }, - { - "cell_type": "markdown", - "id": "a5113b97", - "metadata": {}, - "source": [ - "## ✨ Load Training Data \n", - "\n", - "First, we'll need to fetch the training dataset that we created in the previous notebook. We will use January - February data training and testing." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "5f33dd35", - "metadata": {}, - "outputs": [], - "source": [ - "import pandas as pd\n", - "from sklearn.linear_model import LogisticRegression\n", - "\n", - "train_jan_feb_x, train_jan_feb_y = feature_view.get_training_data(1)\n", - "test_mar_x, test_mar_y = feature_view.get_training_data(2)" - ] - }, - { - "cell_type": "markdown", - "id": "bb68bd57", - "metadata": {}, - "source": [ - "## 🏃 Train Model\n", - "\n", - "Next we'll train a model. Here, we set the class weight of the positive class to be twice as big as the negative class." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "01e6127d", - "metadata": {}, - "outputs": [], - "source": [ - "import numpy as np\n", - "from sklearn.ensemble import IsolationForest\n", - "\n", - "# fit the model\n", - "clf = IsolationForest(max_samples=100)\n", - "clf.fit(train_jan_feb_x)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "793f0cd1", - "metadata": {}, - "outputs": [], - "source": [ - "# Train Predictions\n", - "y_pred_train = clf.predict(train_jan_feb_x)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "cf5d9191", - "metadata": {}, - "outputs": [], - "source": [ - "# Test Predictions\n", - "y_pred_test = clf.predict(test_mar_x)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "39efab3e", - "metadata": {}, - "outputs": [], - "source": [ - "from sklearn.metrics import confusion_matrix, f1_score\n", - "from matplotlib import pyplot\n", - "import seaborn as sn\n", - "\n", - "%matplotlib inline\n", - "\n", - "if_cm=confusion_matrix(test_mar_y, y_pred_test)\n", - "pd.DataFrame(if_cm)\n", - "df_cm = pd.DataFrame(if_cm, ['step', 'True Normal', 'True Fraud'],['Pred Normal', 'step', 'Pred Fraud'])\n", - "df_cm.drop(index=\"step\",inplace=True)\n", - "df_cm.drop(\"step\", axis=1, inplace=True)\n", - "\n", - "pyplot.figure(figsize = (8,4))\n", - "sn.set(font_scale=1.4)#for label size\n", - "sn.heatmap(df_cm, annot=True,annot_kws={\"size\": 16},fmt='g')# font size" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "405861cc", - "metadata": {}, - "outputs": [], - "source": [ - "if_cm=confusion_matrix(train_jan_feb_y, y_pred_train)\n", - "pd.DataFrame(if_cm)\n", - "df_cm = pd.DataFrame(if_cm, ['step', 'True Normal', 'True Fraud'],['Pred Normal', 'step', 'Pred Fraud'])\n", - "df_cm.drop(index=\"step\",inplace=True)\n", - "df_cm.drop(\"step\", axis=1, inplace=True)\n", - "\n", - "pyplot.figure(figsize = (8,4))\n", - "sn.set(font_scale=1.4)#for label size\n", - "sn.heatmap(df_cm, annot=True,annot_kws={\"size\": 16},fmt='g')# font size" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "d154b6e3", - "metadata": {}, - "outputs": [], - "source": [ - "from sklearn.metrics import f1_score\n", - "# Compute f1 score\n", - "metrics = {\"fscore\": f1_score(test_mar_y, y_pred_test, average='micro')}\n", - "metrics" - ] - }, - { - "cell_type": "markdown", - "id": "0808daed", - "metadata": {}, - "source": [ - "\n", - "## Register model\n", - "\n", - "One of the features in Hopsworks is the model registry. This is where we can store different versions of models and compare their performance. Models from the registry can then be served as API endpoints.\n", - "\n", - "Let's connect to the model registry using the HSML library from Hopsworks." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "f56939c5", - "metadata": {}, - "outputs": [], - "source": [ - "mr = project.get_model_registry()" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "cb395a54", - "metadata": {}, - "outputs": [], - "source": [ - "import joblib\n", - "\n", - "joblib.dump(clf, 'model.pkl')" - ] - }, - { - "cell_type": "markdown", - "id": "094956ac", - "metadata": {}, - "source": [ - "The model needs to be set up with a Model Schema, which describes the inputs and outputs for a model.\n", - "\n", - "A Model Schema can be automatically generated from training examples, as shown below." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "41394294", - "metadata": {}, - "outputs": [], - "source": [ - "from hsml.schema import Schema\n", - "from hsml.model_schema import ModelSchema\n", - "\n", - "input_schema = Schema(train_jan_feb_x)\n", - "output_schema = Schema(train_jan_feb_y)\n", - "model_schema = ModelSchema(input_schema=input_schema, output_schema=output_schema)\n", - "\n", - "model_schema.to_dict()" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "c8f23250", - "metadata": {}, - "outputs": [], - "source": [ - "test_credit_card = [4467360740682089]\n", - "model = mr.sklearn.create_model(\n", - " name=\"fraud_online_tutorial_model\",\n", - " metrics=metrics,\n", - " description=\"Isolation forest anomaly detection model\",\n", - " input_example = test_credit_card,\n", - " model_schema=model_schema\n", - ")\n", - "\n", - "model.save('model.pkl')" - ] - }, - { - "cell_type": "markdown", - "id": "80709ea1", - "metadata": {}, - "source": [ - "## Deploy model\n", - "### About Model Serving\n", - "Models can be served via KFServing or \"default\" serving, which means a Docker container exposing a Flask server. For KFServing models, or models written in Tensorflow, you do not need to write a prediction file (see the section below). However, for sklearn models using default serving, you do need to proceed to write a prediction file.\n", - "\n", - "In order to use KFServing, you must have Kubernetes installed and enabled on your cluster.\n", - "\n", - "### Create the Prediction File\n", - "In order to deploy a model, you need to write a Python file containing the logic to return a prediction from the model. Don't worry, this is usually a matter of just modifying some paths in a template script. An example can be seen in the code block below, where we have taken this Scikit-learn template script and changed two paths (see comments)." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "ea08b207", - "metadata": {}, - "outputs": [], - "source": [ - "%%writefile predict_example.py\n", - "import os\n", - "import hsfs\n", - "from sklearn.externals import joblib\n", - "\n", - "class Predict(object):\n", - "\n", - " def __init__(self):\n", - " \"\"\" Initializes the serving state, reads a trained model\"\"\" \n", - " # get feature store handle\n", - " fs_conn = hsfs.connection()\n", - " self.fs = fs_conn.get_feature_store()\n", - " \n", - " # get feature views\n", - " self.fv = self.fs.get_feature_view(\"fraud_online_model_view\", 1)\n", - " \n", - " # initialise serving\n", - " self.fv.init_serving(1)\n", - "\n", - " # load the trained model\n", - " self.model = joblib.load(os.environ[\"ARTIFACT_FILES_PATH\"] + \"/model.pkl\")\n", - " print(\"Initialization Complete\")\n", - "\n", - " def predict(self, inputs):\n", - " \"\"\" Serves a prediction request usign a trained model\"\"\"\n", - " return self.model.predict(self.fv.get_feature_vector({\"cc_num\": inputs[0]})).tolist() # Numpy Arrays are not JSON serializable\n" - ] - }, - { - "cell_type": "markdown", - "id": "0eef6b74", - "metadata": {}, - "source": [ - "If you wonder why we use the path Models/fraud_tutorial_model/1/model.pkl, it is useful to know that the Data Sets tab in the Hopsworks UI lets you browse among the different files in the project. Registered models will be found underneath the Models directory. Since we saved our model with the name fraud_tutorial_model, that's the directory we should look in. 1 is just the version of the model we want to deploy.\n", - "\n", - "This script needs to be put into a known location in the Hopsworks file system. Let's call the file predict_example.py and put it in the Models directory." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "bc9e59ce", - "metadata": {}, - "outputs": [], - "source": [ - "import os\n", - "dataset_api = project.get_dataset_api()\n", - "\n", - "uploaded_file_path = dataset_api.upload(\"predict_example.py\", \"Models\", overwrite=True)\n", - "predictor_script_path = os.path.join(\"/Projects\", project.name, uploaded_file_path)" - ] - }, - { - "cell_type": "markdown", - "id": "86399139", - "metadata": {}, - "source": [ - "## Create the deployment\n", - "Here, we fetch the model we want from the model registry and define a configuration for the deployment. For the configuration, we need to specify the serving type (default or KFserving) and in this case, since we use default serving and an sklearn model, we need to give the location of the prediction script." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "3816d5c3", - "metadata": {}, - "outputs": [], - "source": [ - "# Use the model name from the previous notebook.\n", - "model = mr.get_model(\"fraud_online_tutorial_model\", version=1)\n", - "\n", - "# Give it any name you want\n", - "deployment = model.deploy(\n", - " name=\"fraudonlinemodeldeployment\", \n", - " model_server=\"PYTHON\",\n", - " serving_tool=\"KSERVE\",\n", - " script_file=predictor_script_path\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "8cbe7b79", - "metadata": {}, - "outputs": [], - "source": [ - "print(\"Deployment: \" + deployment.name)\n", - "deployment.describe()" - ] - }, - { - "cell_type": "markdown", - "id": "5655bbed", - "metadata": {}, - "source": [ - "#### The deployment has now been registered. However, to start it you need to run:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "1f4f719e", - "metadata": {}, - "outputs": [], - "source": [ - "deployment.start()" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "97e396dc", - "metadata": {}, - "outputs": [], - "source": [ - "deployment.get_logs()" - ] - }, - { - "cell_type": "markdown", - "id": "8ddb53fa", - "metadata": {}, - "source": [ - "## Using the deployment\n", - "Let's use the input example that we registered together with the model to query the deployment." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "5802d351", - "metadata": {}, - "outputs": [], - "source": [ - "data = {\n", - " \"inputs\": model.input_example\n", - "}\n", - "\n", - "deployment.predict(data)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "30fb1d1d", - "metadata": {}, - "outputs": [], - "source": [ - "deployment.get_logs()" - ] - }, - { - "cell_type": "markdown", - "id": "1375739f", - "metadata": {}, - "source": [ - "### Use REST endpoint\n", - "\n", - "You can also use a REST endpoint for your model. To do this you need to create an API key with 'serving' enabled, and retrieve the endpoint URL from the Model Serving UI.\n", - "\n", - "Go to the Model Serving UI and click on the eye icon next to a model to retrieve the endpoint URL. The shorter URL is an internal endpoint that you can only reach from within Hopsworks. If you want to call it from outside, you need one of the longer URLs. \n", - "\n", - "\n", - "![serving-endpoints](../images/serving_endpoints.gif)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "c3f53c9c", - "metadata": {}, - "outputs": [], - "source": [ - "import os\n", - "import requests\n", - "\n", - "mr = project.get_model_registry()\n", - "\n", - "# Use the model name from the previous notebook.\n", - "model = mr.get_model(\"fraud_tutorial_model\", version=1)\n", - "\n", - "test_inputs = [model.input_example]\n", - "\n", - "API_KEY = \"...\" # Put your API key here.\n", - "MODEL_SERVING_URL = \"...\" # Put model serving endppoint here.\n", - "HOST_NAME = \"...\" # Put your hopsworks model serving hostname here \n", - "\n", - "data = {\"inputs\": test_inputs}\n", - "headers = {\n", - " \"Content-Type\": \"application/json\", \"Accept\": \"application/json\",\n", - " \"Authorization\": f\"ApiKey {API_KEY}\",\n", - " \"Host\": HOST_NAME}\n", - "\n", - "response = requests.post(MODEL_SERVING_URL, verify=False, headers=headers, json=data)\n", - "response.json()" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "2190fab6", - "metadata": {}, - "outputs": [], - "source": [ - "# Now lets test feature vectors from online store\n", - "data = {\"inputs\": 4467360740682089}\n", - "response = requests.post(url, verify=False, headers=headers, json=data)\n", - "response.json()" - ] - }, - { - "cell_type": "markdown", - "id": "4b1c78d7", - "metadata": {}, - "source": [ - "## Stop Deployment\n", - "To stop the deployment we simply run:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "ccde7f76", - "metadata": {}, - "outputs": [], - "source": [ - "deployment.stop()" - ] - }, - { - "cell_type": "markdown", - "id": "395f3c2f", - "metadata": {}, - "source": [ - "## 🎁 Wrapping things up \n", - "\n", - "In this module we introduced stream feature group, performed with training data that we have created from feature view and depoyed model in production." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "0639f4cb", - "metadata": {}, - "outputs": [], - "source": [] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "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.9" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} diff --git a/mkdocs.yml b/mkdocs.yml index add9dc24a..a3adfd1c4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,16 +10,16 @@ edit_uri: "" nav: - Home: index.md - - Getting Started: getting_started/quickstart.ipynb + - Getting Started: hopsworks-tutorials/quickstart.ipynb - Tutorials: - Fraud Batch: - - 1. Feature Groups: tutorials/fraud_batch/1_feature_groups.ipynb - - 2. Feature View: tutorials/fraud_batch/2_feature_view_creation.ipynb - - 3. Model Training: tutorials/fraud_batch/3_model_training.ipynb + - 1. Feature Groups: hopsworks-tutorials/fraud_batch/1_feature_groups.ipynb + - 2. Feature View: hopsworks-tutorials/fraud_batch/2_feature_view_creation.ipynb + - 3. Model Training: hopsworks-tutorials/fraud_batch/3_model_training.ipynb - Fraud Online: - - 1. Feature Groups: tutorials/fraud_online/1_feature_groups.ipynb - - 2. Feature View: tutorials/fraud_online/2_feature_view_creation.ipynb - - 3. Model Training: tutorials/fraud_online/3_model_training.ipynb + - 1. Feature Groups: hopsworks-tutorials/fraud_online/1_feature_groups.ipynb + - 2. Feature View: hopsworks-tutorials/fraud_online/2_feature_view_creation.ipynb + - 3. Model Training: hopsworks-tutorials/fraud_online/3_model_training.ipynb - Concepts: - Hopsworks Platform: concepts/hopsworks.md - Feature Store: diff --git a/prepare_images.py b/prepare_images.py new file mode 100644 index 000000000..1a98d073f --- /dev/null +++ b/prepare_images.py @@ -0,0 +1,20 @@ +import argparse +import shutil +import os + +if __name__ == "__main__": + parser = argparse.ArgumentParser() + parser.add_argument('--path', '-p', help="path to the hopsworks tutorials dir", type=str, default="docs/hopsworks-tutorials") + parser.add_argument('--src', '-s', help="name of directory with images to copy", type=str, default="images") + + args = parser.parse_args() + + except_dirs = [".git", args.src] + + sub_dirs = [ + element for element in os.listdir(args.path) + if os.path.isdir(os.path.join(args.path, element)) and element not in except_dirs + ] + + for dst in sub_dirs: + shutil.copytree(os.path.join(args.path, args.src), os.path.join(args.path, dst, args.src), dirs_exist_ok=True)