aifs-hints 0.1.0__py3-none-any.whl

aifs_hints/__init__.py

@@ -0,0 +1,4 @@
+from .helper import LEVELS, get_helper, list_exercises, load_all_hints
+
+__all__ = ["get_helper", "list_exercises", "load_all_hints", "LEVELS"]
+__version__ = "0.1.0"

aifs_hints/helper.py

@@ -0,0 +1,81 @@
+"""Graduated hints for exercise notebooks.
+
+Usage in a notebook:
+    from aifs_hints import get_helper
+    fetch_help = get_helper("Machine Learning", "Californian Housing Market")
+    fetch_help("10a", level=2)
+"""
+from importlib.resources import files
+
+import pandas as pd
+
+REQUIRED_COLUMNS = ["module", "exercise", "task", "todo", "nudge", "hint", "scaffold"]
+
+LEVELS = {
+    1: ("nudge", "🟢 Level 1 · Nudge"),
+    2: ("hint", "🟡 Level 2 · Hint"),
+    3: ("scaffold", "🔴 Level 3 · Scaffold"),
+}
+
+
+def _read(source):
+    return pd.read_csv(source, dtype={"task": str}, keep_default_na=False)
+
+
+def load_all_hints():
+    """Concatenate every CSV shipped in the package (src/aifs_hints/hints/**)."""
+    frames = []
+    for csv in _iter_csv(files("aifs_hints") / "hints"):
+        df = _read(csv)
+        df["source_file"] = csv.name
+        frames.append(df)
+    if not frames:
+        return pd.DataFrame(columns=REQUIRED_COLUMNS)
+    return pd.concat(frames, ignore_index=True)
+
+
+def _iter_csv(folder):
+    for entry in folder.iterdir():
+        if entry.is_dir():
+            yield from _iter_csv(entry)
+        elif entry.name.endswith(".csv"):
+            yield entry
+
+
+def list_exercises():
+    """(module, exercise) pairs available in the package."""
+    df = load_all_hints()
+    return sorted(set(zip(df["module"], df["exercise"])))
+
+
+def get_helper(module, exercise, source=None):
+    """Return a fetch_help(task, level=1, content=None) function bound to one exercise.
+
+    source: optional path or URL of a CSV, to override the hints shipped in the package
+            (useful to test a CSV before committing it).
+    """
+    df = _read(source) if source else load_all_hints()
+    df = df[(df["module"] == module) & (df["exercise"] == exercise)]
+    if df.empty:
+        raise ValueError(
+            f"No hints found for module={module!r}, exercise={exercise!r}. "
+            "Check the spelling, or call aifs_hints.list_exercises()."
+        )
+    df = df.set_index("task")
+
+    def fetch_help(task, level=1, content=None):
+        from IPython.display import Markdown, display
+
+        task = str(task)
+        if task not in df.index:
+            print(f"No help found for task {task}.")
+        elif content == "todo":
+            print(df.loc[task, "todo"])
+        elif level not in LEVELS:
+            print("level must be 1, 2 or 3.")
+        else:
+            column, title = LEVELS[level]
+            display(Markdown(f"**{title}**\n\n{df.loc[task, column]}"))
+
+    fetch_help.tasks = list(df.index)
+    return fetch_help

aifs_hints/hints/machine_learning/01-Californian_Housing_Market.csv

@@ -0,0 +1,222 @@
+"module","exercise","task","todo","nudge","hint","scaffold"
+"Machine Learning","Californian Housing Market","3a","###  Display the target values of the dataset                     ###","The target values are stored **inside the `data` object** you just loaded: find them and display them.","The object returned by sklearn is a **Bunch**: it works like a dictionary, so you access its elements **by key**.","`data['target']`"
+"Machine Learning","Californian Housing Market","3b","###  Display the names of the explanatory variables                ###","The names of the explanatory variables are also stored in `data`: find where, and display them.","List the **keys** of the Bunch with `.keys()` and pick the one that holds the names of the features.","`data['feature_names']`"
+"Machine Learning","Californian Housing Market","4","###  Build a DataFrame named dataset with:                         ###
+###   - one column per feature (with the feature names)            ###
+###   - a ""Price"" column containing the target                     ###
+###  Then display the first rows                                   ###","- Put the features in a DataFrame, with **the right column names**
+- Add the target as a new `Price` column
+- Check the first rows","- `pd.DataFrame` builds a DataFrame from a 2D array, and accepts a list of **column names**.
+- A new column is created by assigning values to it: `dataset['new_column'] = ...`","- `pd.DataFrame(data=..., columns=...)` → `data` : `data.data`, `columns` : `data.feature_names`
+- New column: `dataset['Price']` ← `data.target`"
+"Machine Learning","Californian Housing Market","5","# Visualize pairwise dependencies
+###  1. Create a scatter matrix of all the columns of dataset       ###
+###  2. Give it a title and a size big enough to be readable       ###
+###  3. Display the figure                                        ###","- Plot **every pair of columns** in a single figure
+- Make it big enough to be readable
+- 👀 How does each feature relate to `Price`?","- Plotly Express has a function that draws **all pairwise scatter plots at once**: `px.scatter_matrix`.
+- The default figure is too small for 9 columns: resize it with `fig.update_layout`.","- `px.scatter_matrix(dataset)`
+- `fig.update_layout(title=..., autosize=False, width=..., height=...)` → around 1200 x 1200
+- `fig.show()`"
+"Machine Learning","Californian Housing Market","6","###  1. Create a boolean mask that keeps the rows where:            ###
+###     AveRooms < 10, AveBedrms < 10, Population < 15000,         ###
+###     AveOccup < 10 and Price < 5                               ###
+###  2. Apply the mask to dataset                                 ###
+###  3. Make the same scatter matrix as before on the filtered data ###","- Write **one condition per column** (the thresholds are in the instructions)
+- Keep a row **only if all the conditions are true**
+- Apply this filter to `dataset`, then redo the plot of question 5","- A comparison on a column (`<`, `>`…) returns a **boolean Series**.
+- Combine boolean Series with `&` (not `and`).
+- Filter the rows of a DataFrame with a boolean mask using `.loc`.","- One condition: `(dataset['AveRooms'] < 10)` ⚠️ the **parentheses** are mandatory
+- Combine: `(condition_1) & (condition_2) & ...`
+- Filter: `dataset.loc[mask, :]`"
+"Machine Learning","Californian Housing Market","7","# Correlation matrix
+###  1. Compute the correlation matrix of dataset (round it)        ###
+###  2. Plot it as a heatmap, with the column names on both axes    ###
+###  3. Display the figure                                        ###","- Compute the **correlation** between every pair of columns
+- Display it as a **heatmap**
+- 👀 Read the `Price` row: which feature is the most correlated with the target?","- pandas computes the correlation matrix of a DataFrame with `.corr()`.
+- `px.imshow` displays a 2D table as a heatmap.","- `dataset.corr()` (add `.round(2)` for readability)
+- `px.imshow(corr_matrix, text_auto=True)` → `text_auto` writes the values in the cells"
+"Machine Learning","Californian Housing Market","8","# Separate target variable Y from features X
+print(""Separating labels from features..."")
+
+###  1. Store the list of features to use (only ""MedInc"") in       ###
+###     features_list, and the target name (""Price"") in           ###
+###     target_variable                                           ###
+###  2. X = the features_list columns of dataset                  ###
+###  3. Y = the target column                                     ###
+
+print(""...Done."")
+print()
+
+print('Y : ')
+print(Y.head())
+print()
+print('X :')
+print(X.head())","- `X` = only the `MedInc` column
+- `Y` = the `Price` column
+- ⚠️ `X` must stay a **table (2D)**: sklearn expects a 2D input for the features","- Select columns with `.loc`.
+- With a **list** of names, `.loc` returns a DataFrame (2D). With a **single** name, it returns a Series (1D).","- `features_list = ['MedInc']`
+- `dataset.loc[:, features_list]`
+- `dataset.loc[:, target_variable]`"
+"Machine Learning","Californian Housing Market","9","# Divide dataset Train set & Test set
+print(""Dividing into train and test sets..."")
+
+###  Split X and Y into X_train, X_test, Y_train, Y_test           ###
+###  (80% train / 20% test)                                        ###
+
+print(""...Done."")
+print()","- Split `X` and `Y` into a train set and a test set
+- 20% of the rows for the test set
+- Make the split **reproducible**","`train_test_split` (from `sklearn.model_selection`) returns **4 objects**, in this order: `X_train, X_test, Y_train, Y_test`.
+Its `random_state` parameter fixes the randomness.","`train_test_split(X, Y, test_size=0.2, random_state=0)`"
+"Machine Learning","Californian Housing Market","10a","print(""Preprocessing X_train..."")
+print(X_train.head())
+print()
+
+###  Standardize all the columns of X_train                        ###
+###  1. Instantiate a StandardScaler                              ###
+###  2. Fit it AND transform X_train in a single step             ###
+
+print(""...Done!"")
+print(X_train[0:5,:]) # X_train is now a numpy array","**Standardize** the training features: learn the mean and the standard deviation on the train set, and apply them.","- `StandardScaler` (from `sklearn.preprocessing`) standardizes every column.
+- Its `.fit_transform()` method **learns and applies** in a single call.
+- The result is a **numpy array**, no longer a DataFrame.","- `StandardScaler()`
+- `scaler.fit_transform(X_train)`"
+"Machine Learning","Californian Housing Market","10b","print(""Preprocessing X_test..."")
+print(X_test.head())
+print()
+
+###  Standardize X_test using the scaler fitted on X_train          ###
+
+print(""...Done!"")
+print(X_test[0:5,:]) # X_test is now a numpy array","Apply **the same standardization** to the test set, using only what was learned on the train set.","- Reuse the **same** `scaler` object.
+- `.transform()` applies the transformation **without learning** anything.
+- ⚠️ Fitting on the test set would **leak** information from the test set into your preprocessing.","`scaler.transform(X_test)`"
+"Machine Learning","Californian Housing Market","11a","# Train model
+print(""Train model..."")
+
+###  1. Instantiate a LinearRegression model named regressor        ###
+###     (it's used in the next cells)                             ###
+###  2. Fit it on the training set (X_train, Y_train)              ###
+
+print(""...Done."")","Create a **linear regression** model named `regressor`, and train it on the training set.","- The model is `LinearRegression` (from `sklearn.linear_model`).
+- Every sklearn model is trained with `.fit()`.","- `LinearRegression()`
+- `regressor.fit(X_train, Y_train)`"
+"Machine Learning","Californian Housing Market","11b","# Print R^2 scores
+###  Complete the two prints with the R2 score of regressor        ###
+###  on the training set and on the test set                       ###
+print(""R2 score on training set : "", )
+print(""R2 score on test set : "", )","- Compute the **R²** on the train set and on the test set
+- 👀 Are the two scores close?","sklearn regressors have a `.score()` method that returns the **R²** directly.
+(Alternative: `r2_score` from `sklearn.metrics`, with the true values and the predictions.)","- `regressor.score(X_train, Y_train)`
+- `regressor.score(X_test, Y_test)`"
+"Machine Learning","Californian Housing Market","12a","# Predictions on training set
+print(""Predictions on training set..."")
+
+###  Use the trained regressor to predict on X_train               ###
+###  Store the result in Y_train_pred                              ###
+
+print(""...Done."")
+print(Y_train_pred)
+print()","Use the trained model to **predict** the prices of the training set.","Every trained sklearn model has a `.predict()` method.","`regressor.predict(X_train)`"
+"Machine Learning","Californian Housing Market","12b","# Predictions on test set
+print(""Predictions on test set..."")
+
+###  Use the same trained regressor to predict on X_test           ###
+###  Store the result in Y_test_pred                               ###
+
+print(""...Done."")
+print(Y_test_pred)
+print()","Same thing on the test set, **without retraining** the model.","Use `.predict()` again, on the test features.","`regressor.predict(X_test)`"
+"Machine Learning","Californian Housing Market","12c","# Visualize the model
+
+# Visualize predictions on training set
+###  1. Scatter plot of the real values: x = X_train, y = Y_train  ###
+###  2. Add the regression line on top, with Y_train_pred as y     ###
+###  3. Display the figure                                        ###
+
+# Visualize predictions on test set
+###  Same thing on the test set: real values (X_test, Y_test)     ###
+###  + predictions (Y_test_pred) on the same figure               ###","For the train set, then for the test set, on the same figure:
+- the **real prices** as points
+- the **predictions** as a line","- `px.scatter` draws the points.
+- `fig.add_trace(go.Scatter(...))` adds a line on top of an existing figure.
+- ⚠️ `X_train` is now a **2D numpy array**: flatten it to 1D before giving it to plotly.","- Points: `px.scatter(x=..., y=Y_train, title=...)`
+- Line: `fig.add_trace(go.Scatter(x=..., y=Y_train_pred, name=...))`
+- `x` : `X_train.flatten().tolist()`"
+"Machine Learning","Californian Housing Market","13a","# Separate target variable Y from features X
+print(""Separating labels from features..."")
+
+###  1. Store the name of the target column (""Price"") in           ###
+###     a variable target_variable                                ###
+###  2. X = all columns except the target                         ###
+###  3. Y = only the target column                                ###
+
+print(""...Done."")
+print()
+
+print('Y : ')
+print(Y.head())
+print()
+print('X :')
+X.head()","- `X` = **all the columns except** `Price`
+- `Y` = the `Price` column","`.drop()` removes columns from a DataFrame (use `axis=1` for columns).","- `dataset.drop(target_variable, axis=1)`
+- `dataset.loc[:, target_variable]`"
+"Machine Learning","Californian Housing Market","13b","# Divide dataset Train set & Test set
+print(""Dividing into train and test sets..."")
+
+###  Split X and Y into X_train, X_test, Y_train, Y_test           ###
+###  (80% train / 20% test, same random_state as the baseline)     ###
+
+print(""...Done."")
+print()","Split again into train and test, **exactly like for the baseline**, so the comparison is fair.","Same `train_test_split` as in question 9: the **same `random_state`** gives the same rows in each set.","`train_test_split(X, Y, test_size=0.2, random_state=0)`"
+"Machine Learning","Californian Housing Market","13c","# Preprocessing
+print(""Preprocessing X_train..."")
+print(X_train.head())
+print()
+
+###  Standardize all the columns of X_train (fit + transform)      ###
+
+print(""...Done!"")
+print(X_train[0:5,:]) # X_train is now a numpy array","Standardize the training features again. ⚠️ `X` has more columns now.","You need a **new** `StandardScaler`: the previous one was fitted on one column only. Then `.fit_transform()`.","- `StandardScaler()`
+- `scaler.fit_transform(X_train)`"
+"Machine Learning","Californian Housing Market","13d","print(""Preprocessing X_test..."")
+print(X_test.head())
+print()
+
+###  Standardize X_test using the scaler fitted on X_train          ###
+
+print(""...Done!"")
+print(X_test[0:5,:]) # X_test is now a numpy array","Apply the standardization to the test set, **without learning** on it.","`.transform()` of the scaler you just fitted on `X_train`.","`scaler.transform(X_test)`"
+"Machine Learning","Californian Housing Market","13e","# Train model
+print(""Train model..."")
+
+###  Instantiate a new LinearRegression named regressor and fit it ###
+###  on the training set                                           ###
+
+print(""...Done."")","Train a new linear regression, this time on **all the features**.","Same model and same method as in question 11: `LinearRegression` and `.fit()`.","- `LinearRegression()`
+- `regressor.fit(X_train, Y_train)`"
+"Machine Learning","Californian Housing Market","13f","# Print R^2 scores
+###  Complete the two prints with the R2 score of regressor        ###
+###  Then compare them with the baseline model                     ###
+print(""R2 score on training set : "", )
+print(""R2 score on test set : "", )","- Compute the **R²** on the train set and on the test set
+- 👀 Compare with the baseline: how much do you gain with all the features?","Same method as in question 11: `.score()`.","- `regressor.score(X_train, Y_train)`
+- `regressor.score(X_test, Y_test)`"
+"Machine Learning","Californian Housing Market","14a","###  1. Store the names of the features in column_names             ###
+###  2. Create a DataFrame coefs with one row per feature and       ###
+###     its coefficient in the model                              ###
+###  3. Display coefs                                             ###","Build a table with **each feature name next to its coefficient** in the model.","- The learned coefficients are stored in the `.coef_` attribute of the model, **in the same order as the columns of `X`**.
+- The names are simply `X.columns` (no complex preprocessing here).
+- Build the table with `pd.DataFrame`, using the names as index.","`pd.DataFrame(index=column_names, data=regressor.coef_, columns=['coefficients'])`"
+"Machine Learning","Californian Housing Market","14b","###  1. Compute the absolute value of the coefficients and sort them ###
+###  2. Plot them in a horizontal bar chart                        ###
+###  3. Remove the legend and add a left margin for the labels     ###
+###  4. Display the figure                                        ###","- Rank the features by **importance** = size of the coefficient, **whatever its sign**
+- Plot them in a horizontal bar chart
+- 👀 Why can you compare the coefficients with each other here?","- `abs()` gives the absolute values, `.sort_values()` sorts them.
+- `px.bar` with a horizontal orientation, then `fig.update_layout` to hide the legend and leave room for the labels.
+- Coefficients are comparable because all the features were **standardized**.","- `abs(coefs).sort_values(by='coefficients')`
+- `px.bar(feature_importance, orientation='h')`
+- `fig.update_layout(showlegend=False, margin={'l': 120})`"

aifs_hints-0.1.0.dist-info/METADATA

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: aifs_hints
+Version: 0.1.0
+Summary: Graduated hints (nudge / hint / scaffold) for exercise notebooks
+Requires-Python: >=3.9
+Requires-Dist: pandas
+Requires-Dist: ipython
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"

aifs_hints-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+aifs_hints/__init__.py,sha256=QX9ZuL0prOL_k6DLKLtDW9uBApXRr69qzrfR7ePHEUc,165
+aifs_hints/helper.py,sha256=AOzZtpLAGIIvhLUXgKNM-_CCfR3zss_dYCFJtB2Gxns,2558
+aifs_hints/hints/machine_learning/01-Californian_Housing_Market.csv,sha256=Hzf3W7swBLFp-vfoWunyHNy6Twmfhayg5gUMzVFo9AQ,15307
+aifs_hints-0.1.0.dist-info/METADATA,sha256=ukOL7_K3t_mJcLCrE13pPwsYJpA_dYFiaLf6Ndw08pE,254
+aifs_hints-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+aifs_hints-0.1.0.dist-info/top_level.txt,sha256=6nFBaP-9SrQ5hW7FEyih-NCpTf070Lm3eArn3fM2fzk,11
+aifs_hints-0.1.0.dist-info/RECORD,,

aifs_hints-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

aifs_hints-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+aifs_hints