From 2a683b54cc7d24722c5bd40aec713dcd468f5c17 Mon Sep 17 00:00:00 2001
From: Donald Lam <manholam8@gmail.com>
Date: Tue, 9 Jan 2024 21:18:07 +0800
Subject: [PATCH] add visualize README

---
 Analysis/README.md                      | 48 +++++++++++++++++++++++--
 Analysis/main.ipynb                     | 21 ++++++++---
 Analysis/{basis => reference}/full.json |  0
 Analysis/tools.py                       | 18 +++++-----
 Analysis/visualize.py                   |  8 ++---
 5 files changed, 75 insertions(+), 20 deletions(-)
 rename Analysis/{basis => reference}/full.json (100%)

diff --git a/Analysis/README.md b/Analysis/README.md
index ac2a573..d61466c 100644
--- a/Analysis/README.md
+++ b/Analysis/README.md
@@ -1,2 +1,46 @@
-## To-Do
-Write the README.
\ No newline at end of file
+# Visualization
+
+## Execution Process
+
+### Specify the Projection Matrix
+Construct all grids ranging from the minimum to maximum score of the questionnaire as a standard reference frame
+```py
+construct_reference("<questionnaire_name>", "<save_name>")
+```
+
+### Visualize data points
+1. Create a Visualize instance with PCA projection matrix using the standard reference frame
+```py
+# Extract the reference frame from JSON
+reference = extract_reference('<reference_path>')
+# Create the instance
+vis = Visualize('<questionnaire_name>', reference)
+```
+
+2. Add the data points on the constructed plane
+```py
+# Extract the data from JSON
+data, _ = extract_data('<data_path>')
+
+# Add the data
+vis.add(data, "<color>", "<label>")
+
+# Add the filtered data using DataFrame operations
+vis.add(data["<aspect>"], "<color>", "<label>")
+```
+
+3. Visualize the current constructed plane
+```py
+vis.plot()
+
+# Save the figure
+vis.plot(savename="<fig_name>")
+
+# Visualize the data with randomized z-order
+vis.plot(random_zorder=True)
+```
+
+4. Clear the plane
+```py
+vis.clean()
+```
diff --git a/Analysis/main.ipynb b/Analysis/main.ipynb
index 1153348..a362fd4 100644
--- a/Analysis/main.ipynb
+++ b/Analysis/main.ipynb
@@ -2,7 +2,7 @@
  "cells": [
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 10,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -38,12 +38,23 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 11,
    "metadata": {},
-   "outputs": [],
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "('template', 'language', 'version', 'label', 'order')"
+      ]
+     },
+     "execution_count": 11,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
    "source": [
-    "basis = extract_basis('basis/full.json')\n",
-    "vis = Visualize('BFI', basis)\n",
+    "reference = extract_reference('reference/full.json')\n",
+    "vis = Visualize('BFI', reference)\n",
     "data, info = extract_data('save/save.json')\n"
    ]
   },
diff --git a/Analysis/basis/full.json b/Analysis/reference/full.json
similarity index 100%
rename from Analysis/basis/full.json
rename to Analysis/reference/full.json
diff --git a/Analysis/tools.py b/Analysis/tools.py
index 463de05..e7b4be6 100644
--- a/Analysis/tools.py
+++ b/Analysis/tools.py
@@ -23,26 +23,26 @@ def get_questionnaire(name):
     except FileNotFoundError: raise FileNotFoundError("The 'questionnaires.json' file does not exist.")
 
 '''
-Construct the basis and fit to PCA to extract the projection matrix for dimensional reduction
+Construct the reference and fit to PCA to extract the projection matrix for dimensional reduction
 '''
-def construct_basis(questionnaire_name, savefile, mode='full'):
-    basis = list()
+def construct_reference(questionnaire_name, savefile, mode='full'):
+    reference = list()
     questionnaire = get_questionnaire(questionnaire_name)
     scales = questionnaire["scales"]
     categories = list(questionnaire["categories"].keys())
     combinations = list(product(scales, repeat=len(categories)))
     for item in combinations:
-        basis.append(dict(zip(categories, item)))
+        reference.append(dict(zip(categories, item)))
     with open(savefile, 'w') as f:
-        json.dump(basis, f, indent=4)
+        json.dump(reference, f, indent=4)
         
 '''
-Extract the fitting basis
+Extract the fitting reference
 '''
-def extract_basis(filename):
+def extract_reference(filename):
     with open(filename, 'r') as f:
-        basis = json.load(f)
-    df = pd.DataFrame(basis)
+        reference = json.load(f)
+    df = pd.DataFrame(reference)
     return df
 
 '''
diff --git a/Analysis/visualize.py b/Analysis/visualize.py
index b6424bf..74698ee 100644
--- a/Analysis/visualize.py
+++ b/Analysis/visualize.py
@@ -13,15 +13,15 @@
 class Visualize:
     '''
     Initialize a Visualize object for visualizing data using PCA.
-        qname (dataframe), basis (df)
+        qname (dataframe), reference (df)
     '''
-    def __init__(self, qname, basis):
+    def __init__(self, qname, reference):
         self.data = list()
         self.questionnaire = get_questionnaire(qname)
         dimensions = len(self.questionnaire["scales"])
         self.pca = PCA(n_components=dimensions)
-        # random.shuffle(basis.to_numpy())
-        pca_basis = self.pca.fit_transform(basis)
+        # random.shuffle(reference.to_numpy())
+        pca_basis = self.pca.fit_transform(reference)
         self.basis = {
             "x": pca_basis[:,0],
             "y": pca_basis[:,1],