From e656e5e29b644aaf1f351b147e42acc2f2c1c740 Mon Sep 17 00:00:00 2001 From: kellywujy Date: Fri, 27 Jan 2023 23:57:00 -0800 Subject: [PATCH] docs: Usage updated --- docs/example.ipynb | 506 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 492 insertions(+), 14 deletions(-) diff --git a/docs/example.ipynb b/docs/example.ipynb index db7ceb2..d3e6678 100644 --- a/docs/example.ipynb +++ b/docs/example.ipynb @@ -40,44 +40,522 @@ "cell_type": "code", "execution_count": 2, "metadata": {}, + "outputs": [], + "source": [ + "# Load all required package functions\n", + "from mercedestrenz.data import load_sample_mercedes_listings, listing_search\n", + "from mercedestrenz.train import train_mercedes_price_prediction_model\n", + "from mercedestrenz.predict import predict_mercedes_price\n", + "from mercedestrenz.visualizations import plot_mercedes_price" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### 1. load_sample_mercedes_listings() - a function for loading sample data\n", + "The package contains a static dataset for Craiglist used-car listings that were previously web scraped. Several key attributes about the used-car are available in the dataset, such as vehicle prices, models, car conditions, odometer readings, VINs, regions and transmission." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "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", + "
price_USDconditionpaint_colormodelodometer_miyearnum_cylindersfueltransmissiondrivesizetypestateVINtitle_statusdescription
01300usedNaNother12774.01969NaNgasautomaticNaNNaNNaNalNaNcleanCar has been sitting and everything is still o...
14000fairsilverother88100.019726gasautomaticrwdfull-sizecoupeal11402312009097cleanMercedes Benz 250c 1972. Runs and drives fine...
229500like newwhiteother18000.02018NaNgasmanualNaNNaNsedanalNaNcleanLike new, one owner, non smoker, garage kept. ...
3800fairsilverother150000.019976dieselautomaticrwdfull-sizesedanalNaNparts only1997 Mercedes E300 Diesel runs and drives need...
44500usedNaNother60000.02014NaNgasautomaticNaNNaNNaNakNaNclean2014 Mercedes GLK350 Awd 60k miles all options...
\n", + "
" + ], "text/plain": [ - "11142.06" + " price_USD condition paint_color model odometer_mi year num_cylinders \\\n", + "0 1300 used NaN other 12774.0 1969 NaN \n", + "1 4000 fair silver other 88100.0 1972 6 \n", + "2 29500 like new white other 18000.0 2018 NaN \n", + "3 800 fair silver other 150000.0 1997 6 \n", + "4 4500 used NaN other 60000.0 2014 NaN \n", + "\n", + " fuel transmission drive size type state VIN \\\n", + "0 gas automatic NaN NaN NaN al NaN \n", + "1 gas automatic rwd full-size coupe al 11402312009097 \n", + "2 gas manual NaN NaN sedan al NaN \n", + "3 diesel automatic rwd full-size sedan al NaN \n", + "4 gas automatic NaN NaN NaN ak NaN \n", + "\n", + " title_status description \n", + "0 clean Car has been sitting and everything is still o... \n", + "1 clean Mercedes Benz 250c 1972. Runs and drives fine... \n", + "2 clean Like new, one owner, non smoker, garage kept. ... \n", + "3 parts only 1997 Mercedes E300 Diesel runs and drives need... \n", + "4 clean 2014 Mercedes GLK350 Awd 60k miles all options... " ] }, - "execution_count": 2, + "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ - "# Load all required package functions\n", - "from mercedestrenz.data import load_sample_mercedes_listings, listing_search\n", - "from mercedestrenz.train import train_mercedes_price_prediction_model\n", - "from mercedestrenz.predict import predict_mercedes_price\n", - "from mercedestrenz.visualizations import plot_mercedes_price\n", "\n", "# Load the sample mercedes listings data into a dataframe\n", "data = load_sample_mercedes_listings()\n", + "data.head()\n" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### 2. listing_search() - a function for searching listing that match the expected budget range and sort by desired features\n", + "Use this function to search for the listings that match the user's expected price range. \n", + "- The results are filtered by an optional input, model. By default, all models will be shown, but the user can change it to narrow down the searching range to only the models of interest.\n", + "- The results are also sorted by ascending price and another the specified feature in the sort_feature parameter. By default the sort_feature is lower mileage value, but user has the flexibility to choose another numeric attribute." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "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", + "
price_USDmodelodometer_mititle_statusconditionnum_cylinderstypeVINpaint_colortransmissionyearstatedescriptiondrivefuelsize
24934999c-class0.0cleanexcellentNaNNaNWDBRN40JX4A552306NaNautomatic2004mn2004 *** Mercedes-Benz C-Class C 230 Kompresso...rwdgasNaN
24944999c-class0.0cleanexcellentNaNNaNWDBRN40JX4A552306NaNautomatic2004mn2004 *** Mercedes-Benz C-Class C 230 Kompresso...rwdgasNaN
68611900m-class0.0cleanexcellent6wagon4JGBB5GB9BA705850whiteautomatic2011ca2011 Mercedes-Benz M-Class RWD 4dr ML 350 - $1...fwdgasNaN
69011900m-class0.0cleanexcellent6wagon4JGBB5GB9BA705850whiteautomatic2011ca2011 Mercedes-Benz M-Class RWD 4dr ML 350 - $1...fwdgasNaN
69911900m-class0.0cleanexcellent6wagon4JGBB5GB9BA705850whiteautomatic2011ca2011 Mercedes-Benz M-Class RWD 4dr ML 350 - $1...fwdgasNaN
\n", + "
" + ], + "text/plain": [ + " price_USD model odometer_mi title_status condition num_cylinders \\\n", + "2493 4999 c-class 0.0 clean excellent NaN \n", + "2494 4999 c-class 0.0 clean excellent NaN \n", + "686 11900 m-class 0.0 clean excellent 6 \n", + "690 11900 m-class 0.0 clean excellent 6 \n", + "699 11900 m-class 0.0 clean excellent 6 \n", + "\n", + " type VIN paint_color transmission year state \\\n", + "2493 NaN WDBRN40JX4A552306 NaN automatic 2004 mn \n", + "2494 NaN WDBRN40JX4A552306 NaN automatic 2004 mn \n", + "686 wagon 4JGBB5GB9BA705850 white automatic 2011 ca \n", + "690 wagon 4JGBB5GB9BA705850 white automatic 2011 ca \n", + "699 wagon 4JGBB5GB9BA705850 white automatic 2011 ca \n", + "\n", + " description drive fuel size \n", + "2493 2004 *** Mercedes-Benz C-Class C 230 Kompresso... rwd gas NaN \n", + "2494 2004 *** Mercedes-Benz C-Class C 230 Kompresso... rwd gas NaN \n", + "686 2011 Mercedes-Benz M-Class RWD 4dr ML 350 - $1... fwd gas NaN \n", + "690 2011 Mercedes-Benz M-Class RWD 4dr ML 350 - $1... fwd gas NaN \n", + "699 2011 Mercedes-Benz M-Class RWD 4dr ML 350 - $1... fwd gas NaN " + ] + }, + "execution_count": 4, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ "\n", "# Return the top listings that are within a budget range specified by the user. Returns a pandas dataframe of results.\n", - "listing_search(data, budget=[2000, 20000], model = \"any\", sort_feature = \"odometer_mi\", ascending = True)\n", + "listings = listing_search(data, budget=[2000, 20000], model = \"any\", sort_feature = \"odometer_mi\", ascending = True)\n", + "listings.head()\n" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### 3. plot_mercedes_price() - a function for visualizing current matket's price distribution \n", + "This function will plot a density plot of a specific Mercedes-Benz model to see where the current vehicle's price falls within the distribution of prices for that model in the market." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": {}, + "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "/Users/kw/opt/miniconda3/envs/mercedestrenz/lib/python3.9/site-packages/altair/utils/core.py:317: FutureWarning: iteritems is deprecated and will be removed in a future version. Use .items instead.\n", + " for col_name, dtype in df.dtypes.iteritems():\n" + ] + }, + { + "data": { + "text/html": [ + "\n", + "
\n", + "" + ], + "text/plain": [ + "alt.LayerChart(...)" + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ "\n", "# Plot a price distribution of specific mercedes models, and see where an input price falls in the distribution.\n", - "plot_mercedes_price(model='c-class', price=30000, market_df=data)\n", + "plot_mercedes_price(model='c-class', price=30000, market_df=data)\n" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### 4. predict_mercedes_price() - a function for predicting a reasonable price in USD\n", "\n", - "# # Predict the price (in USD) of a Mercedes-Benz given the year, model, condition, paint color, and odometer reading.\n", - "predict_mercedes_price(\"e-class\", 2015, 55_000, \"fair\", \"silver\")" + "This function will predicts the price in USD of a Mercedes-Benz given the year, model, condition, paint color and odometer reading.\n", + "\n", + "It uses a pre-trained model built into the package to predict the price of themercedes. The model was trained on data from 1990 to 2022." ] }, { "cell_type": "code", - "execution_count": null, + "execution_count": 6, "metadata": {}, - "outputs": [], - "source": [] + "outputs": [ + { + "data": { + "text/plain": [ + "11142.06" + ] + }, + "execution_count": 6, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "\n", + "# # Predict the price (in USD) of a Mercedes-Benz given the year, model, condition, paint color, and odometer reading.\n", + "predict_mercedes_price(\"e-class\", 2015, 55_000, \"fair\", \"silver\")" + ] } ], "metadata": {