second pass before requesting review

Blargian · Blargian · commit 04019d6cda77 · 2025-09-30T12:06:15.000+02:00
diff --git a/docs/use-cases/AI_ML/jupyter-notebook.md b/docs/use-cases/AI_ML/jupyter-notebook.md
@@ -1,9 +1,9 @@
 ---
 slug: /use-cases/AI/jupyter-notebook
-sidebar_label: 'Exploring data in Jupyter notebooks with chdb'
-title: 'Exploring data in Jupyter notebooks with chdb'
-description: 'This guide explains how to setup and use chdb to explore data from ClickHouse Cloud or local files in Jupyer notebooks'
-keywords: ['ML', 'Jupyer', 'chdb', 'pandas']
+sidebar_label: 'Exploring data in Jupyter notebooks with chDB'
+title: 'Exploring data in Jupyter notebooks with chDB'
+description: 'This guide explains how to setup and use chDB to explore data from ClickHouse Cloud or local files in Jupyer notebooks'
+keywords: ['ML', 'Jupyer', 'chDB', 'pandas']
 doc_type: 'guide'
 ---
 
@@ -18,14 +18,20 @@ import image_7 from '@site/static/images/use-cases/AI_ML/jupyter/7.png';
 import image_8 from '@site/static/images/use-cases/AI_ML/jupyter/8.png';
 import image_9 from '@site/static/images/use-cases/AI_ML/jupyter/9.png';
 
-# Exploring data with Jupyter notebooks and chdb
+# Exploring data with Jupyter notebooks and chDB
 
-In this guide, you will learn how you can explore a dataset on ClickHouse Cloud data in Jupyter notebook with the help of [chdb](/chdb) - a fast in-process SQL OLAP Engine powered by ClickHouse.
+In this guide, you will learn how you can explore a dataset on ClickHouse Cloud data in Jupyter notebook with the help of [chDB](/chdb) - a fast in-process SQL OLAP Engine powered by ClickHouse.
 
-Pre-requisites:
+**Prerequisites**:
 - a virtual environment
 - a working ClickHouse Cloud service and your [connection details](/cloud/guides/sql-console/gather-connection-details)
 
+**What you'll learn:**
+- Connect to ClickHouse Cloud from Jupyter notebooks using chDB
+- Query remote datasets and convert results to Pandas DataFrames
+- Combine cloud data with local CSV files for analysis
+- Visualize data using matplotlib
+
 We'll be using the UK Property Price dataset which is available on ClickHouse Cloud as one of the starter datasets.
 It contains data about the prices that houses were sold for in the United Kingdom from 1995 to 2024.
 
@@ -47,7 +53,7 @@ Then click `Import dataset`:
 
 ClickHouse will automatically create the `pp_complete` table in the `default` database and fill the table with 28.92 million rows of price point data.
 
-In order to reduce the likelihood of exposing your credentials, we recommend to add your Cloud username and password as environment variables.
+In order to reduce the likelihood of exposing your credentials, we recommend to add your Cloud username and password as environment variables on your local machine.
 From a terminal run the following command to add your username and password as environment variables:
 
 ```bash
@@ -57,7 +63,7 @@ export CLICKHOUSE_PASSWORD=your_actual_password
 
 :::note
 The environment variables above persist only as long as your terminal session.
-To set them permanently, for Linux or MacOS you'll want to set these permanently.
+To set them permanently, add them to your shell configuration file.
 :::
 
 Now activate your virtual environment.
@@ -67,7 +73,7 @@ From within your virtual environment, install Jupyter Notebook with the followin
 pip install notebook
 ```
 
-and launch Jupyter Notebook with the following command:
+launch Jupyter Notebook with the following command:
 
 ```python
 jupyter notebook
@@ -83,13 +89,13 @@ Select any Python kernel available to you, in this example we will select the `i
 
 <Image size="md" img={image_5} alt="Select kernel"/>
 
-In a blank cell, you can type the following command to install chdb which we will be using connect to our remote ClickHouse Cloud instance:
+In a blank cell, you can type the following command to install chDB which we will be using connect to our remote ClickHouse Cloud instance:
 
 ```python
 pip install chdb
 ```
 
-You can now import chdb and run a simple query to check that everything is set up correctly:
+You can now import chDB and run a simple query to check that everything is set up correctly:
 
 ```python
 import chdb
@@ -100,11 +106,11 @@ print(result)
 
 ## Exploring the data {#exploring-the-data}
 
-With the UK price paid data set up and chdb up and running in a Jupyter notebook, we can now get started exploring our data.
+With the UK price paid data set up and chDB up and running in a Jupyter notebook, we can now get started exploring our data.
 
-Let's imagine we are interested in checking how price has changed with time for a specific area in the UK, for instance: London.
-ClickHouse's [`remoteSecure`](/sql-reference/table-functions/remote) function allows us to easily retrieve the data from ClickHouse Cloud.
-We can instruct chdb to return it in process as a Pandas data frame - which is a convenient and familiar way of working with data.
+Let's imagine we are interested in checking how price has changed with time for a specific area in the UK such as the capital city, London.
+ClickHouse's [`remoteSecure`](/sql-reference/table-functions/remote) function allows you to easily retrieve the data from ClickHouse Cloud.
+You can instruct chDB to return this data in process as a Pandas data frame - which is a convenient and familiar way of working with data.
 
 Write the following query to fetch the UK price paid data from your ClickHouse Cloud service and turn it into a `pandas.DataFrame`:
 
@@ -127,7 +133,7 @@ SELECT
     toYear(date) AS year,
     avg(price) AS avg_price
 FROM remoteSecure(
-'ztztn4astx.europe-west4.gcp.clickhouse.cloud',
+'****.europe-west4.gcp.clickhouse.cloud',
 default.pp_complete,
 '{username}',
 '{password}'
@@ -141,17 +147,20 @@ df = chdb.query(query, "DataFrame")
 df.head()
 ```
 
-In the snippet above, `chdb.query(query, "DataFrame")` runs the specified query and outputs the result to the terminal as a pandas DataFrame.
+In the snippet above, `chdb.query(query, "DataFrame")` runs the specified query and outputs the result to the terminal as a Pandas DataFrame.
 In the query we are using the `remoteSecure` function to connect to ClickHouse Cloud.
 The `remoteSecure` functions takes as parameters:
 - a connection string
 - the name of the database and table to use
-- your user name
+- your username
 - your password
 
-As a security best practice, you should should prefer using environment variables for the username and password parameters rather than specifying them directly in the function, although this is possible if you wish.
+As a security best practice, you should prefer using environment variables for the username and password parameters rather than specifying them directly in the function, although this is possible if you wish.
 
-The `remoteSecure` function connects to the remote ClickHouse Cloud service, runs the query and returns the result. Depending on the size of your data this could take a few seconds. In this case we return an average price point per year, and filter by `town='LONDON'`. The result is then stored as a DataFrame in a variable called `df`.
+The `remoteSecure` function connects to the remote ClickHouse Cloud service, runs the query and returns the result.
+Depending on the size of your data, this could take a few seconds.
+In this case we return an average price point per year, and filter by `town='LONDON'`.
+The result is then stored as a DataFrame in a variable called `df`.
 
 `df.head` displays only the first few rows of the returned data:
 
@@ -170,7 +179,7 @@ dtype: object
 ```
 
 Notice that while `date` is of type `Date` in ClickHouse, in the resulting data frame it is of type `uint16`.
-chdb automatically infers the most appropriate type when returning the DataFrame.
+chDB automatically infers the most appropriate type when returning the DataFrame.
 
 With the data now available to us in a familiar form, let's explore how prices of property in London have changed with time.
 
@@ -194,10 +203,11 @@ plt.show()
 
 <Image size="md" img={image_7} alt="dataframe preview"/>
 
-Perhaps unsurprisingly, property prices in London have massively increased over time.
+Perhaps unsurprisingly, property prices in London have increased substantially over time.
 
-A colleague has sent us a .csv file with additional housing related variables.
-Let's plot some of these against the housing prices and see if we can discover any interesting correlations.
+A fellow data scientist has sent us a .csv file with additional housing related variables and is curious how 
+the number of houses sold in London has changed over time.
+Let's plot some of these against the housing prices and see if we can discover any correlation.
 
 You can use the `file` table engine to read files directly on your local machine.
 In a new cell, run the following command to make a new DataFrame from the local .csv file.
@@ -207,7 +217,7 @@ query = f"""
 SELECT 
     toYear(date) AS year,
     sum(houses_sold)*1000
-    FROM file('/Users/sstruw/Desktop/housing_in_london_monthly_variables.csv')
+    FROM file('/Users/datasci/Desktop/housing_in_london_monthly_variables.csv')
 WHERE area = 'city of london' AND houses_sold IS NOT NULL
 GROUP BY toYear(date)
 ORDER BY year;
@@ -265,9 +275,15 @@ plt.show()
 
 <Image size="md" img={image_9} alt="Plot of remote data set and local data set"/>
 
-It looks like housing prices in London have steadily risen over the years, while the number of houses sold has fluctuated greatly over time but generally trends downwards, at times even dropping below 1995 levels.
-Yikes!
+From the plotted data, we see that sales started around 160000 in the year 1995 and surged quickly, peaking at around 540000 in 19999.
+After that, volumes declined sharply through the mid-2000s, dropping severely during the 2007-2008 financial crisis and falling to around 140 000.
+Prices on the other hand showed steady, consistent growth from about £150,000 in 1995 to around £300,000 by 2005.
+Growth accelerated significantly after 2012, rising steeply from roughly £400,000 to over £1,000,000 by 2019.
+Unlike sales volume, prices showed minimal impact from the 2008 crisis and maintained an upward trajectory. Yikes!
 
 ## Summary {#summary}
 
-Whilst your average London-based data scientist may not be able to afford their own home any time soon, chdb allows you to easily work with data from multiple sources like ClickHouse Cloud and local CSV files easily in Jupyter notebook using the libraries you know and love like Pandas and matplotlib.
+This guide demonstrated how chDB enables seamless data exploration in Jupyter notebooks by connecting ClickHouse Cloud with local data sources.
+Using the UK Property Price dataset, we showed how to query remote ClickHouse Cloud data with the `remoteSecure()` function, read local CSV files with the `file()` table engine, and convert results directly to Pandas DataFrames for analysis and visualization.
+Through chDB, data scientists can leverage ClickHouse's powerful SQL capabilities alongside familiar Python tools like Pandas and matplotlib, making it easy to combine multiple data sources for comprehensive analysis.
+While many a London-based data scientist may not be able to afford their own home or apartment any time soon, at least they can analyze the market that priced them out!
