new improvements

- seprated insights & share_scores into different functions
- renamed methods in analyze.py
- wrote some docs for insights

Author: Bhupesh-V

demo.py

@@ -1,26 +1,30 @@
 """Usage example"""
 import os
 import pprint
-from plagcheck import plagcheck
+from plagcheck.plagcheck import check, insights, share_scores
 
 from dotenv import load_dotenv
 load_dotenv()
 
-language = "python"
+language = "java"
 userid = os.environ["USER_ID"]
 
 
-moss = plagcheck.check(language, userid)
+moss = check(language, userid)
 
-moss.addFilesByWildCard("testfiles/test_python*.py")
+moss.addFilesByWildCard("testfiles/test_java*.java")
 
 # or moss.addFile("testfiles/test_python.py")
 
 moss.submit()
 
 print(moss.getHomePage())
-pprint.pprint(moss.getResults())
-# print frequency of each shared solution
-pprint.pprint(moss.getShareScores())
+
+result = moss.getResults()
+
+pprint.pprint(result)
+
 # print potential distributor-culprit relationships
-pprint.pprint(moss.getInsights())
+pprint.pprint(insights(result))
+# print frequency of each shared solution
+pprint.pprint(share_scores(result))

docs/insights.md

@@ -0,0 +1,41 @@
+# Insights
+
+PlagCheck provides algorithmic analysis of Moss results.
+
+
+## M-group
+m-groups (moss-groups) are groups of solution which have similar code.
+For example A student who solves a programming problem may share their
+solution with 3 of his/her friends, that is a single m-group with 4 nodes.
+
+For example if you run [demo.py](https://github.com/codeclassroom/PlagCheck/blob/master/demo.py), `insights()` will return the following data:
+```python
+
+{'DCtoC Paths': [('testfiles/test_java5.java', 'testfiles/test_java2.java'),
+                 ('testfiles/test_java4.java', 'testfiles/test_java2.java')],
+ 'DtoC Paths': [('testfiles/test_java3.java', 'testfiles/test_java2.java'),
+                ('testfiles/test_java3.java', 'testfiles/test_java.java'),
+                ('testfiles/test_java7.java', 'testfiles/test_java6.java')],
+ 'DtoDC Paths': [('testfiles/test_java3.java', 'testfiles/test_java5.java'),
+                 ('testfiles/test_java3.java', 'testfiles/test_java4.java')]}
+
+```
+
+This analysis can be visulaized into following _Disconnected Directed Graph_
+
+![moss results](https://drive.google.com/uc?export=view&id=1Lc8obgjihfo7EGimn300mTtqfmHK0Zem)
+
+We assign Tags to every individual file which has been returned by Moss.
+
+1. D - Distributor
+Student(s) who distributed their
+code in a group.
+2. C - Culprit
+Student(s) who copied the shared
+code.
+3. DC - Both a Distributor & Culprit
+
+In the above depicted graph, there are 2 unique _m-groups_.
+
+1. Group 1 : [1, 2, 3, 4, 5]
+2. Group 2 : [7, 6]

mkdocs.yml

@@ -8,6 +8,7 @@ nav:
     - Documentation: index.md
     - Installation: installation.md
     - Usage: usage.md
+    - Insights: insights.md
     - Moss: moss.md
     - Changelog: changelog.md
     - About: about.md

plagcheck/__init__.py

@@ -1,2 +1,2 @@
 """The MOSS interface package for CodeClassroom"""
-from plagcheck.plagcheck import check
+from plagcheck.plagcheck import check, insights, share_scores

plagcheck/analyze.py

@@ -28,7 +28,7 @@ def __init__(self):
         self.nodes = []
         self.nodeCount = 0
 
-    def relatesTo(self, P1, P2, node1, node2):
+    def relate(self, P1, P2, node1, node2):
         """Set a path between two file nodes"""
         node_obj_dict = {}
 

plagcheck/plagcheck.py

@@ -43,6 +43,45 @@ def request(url: str):
     return req.decode("utf-8")
 
 
+def share_scores(moss_data: dict) -> dict:
+    """Share Score Insights"""
+    similar_code_files = []
+    for result in moss_data:
+        similar_code_files.append(result["file1"])
+        similar_code_files.append(result["file2"])
+
+    # frequency of files which are similar
+    share_score = collections.Counter(similar_code_files)
+
+    return dict(share_score)
+
+
+def insights(moss_data: dict) -> dict:
+    """Analysis for Moss"""
+    mg = Mgroups()
+    similar_code_files = set()
+    insights = {}
+
+    for r in moss_data:
+        similar_code_files.add(r["file1"])
+        similar_code_files.add(r["file2"])
+
+    mg.createNodes(similar_code_files)
+
+    for r in moss_data:
+        mg.relate(
+            r["percentage_file1"], r["percentage_file2"], r["file1"], r["file2"]
+        )
+
+    mg.set_tags()
+
+    insights["DtoC Paths"] = mg.d2c()
+    insights["DtoDC Paths"] = mg.d2dc()
+    insights["DCtoC Paths"] = mg.dc2c()
+
+    return insights
+
+
 class check:
     """
     Args:
@@ -133,40 +172,3 @@ def getResults(self) -> Tuple[str, Results]:
         """Return the result as a list of dictionary"""
 
         return self.moss_results
-
-    def getShareScores(self):
-        """Share Score Insights"""
-        similar_code_files = []
-        for result in self.moss_results:
-            similar_code_files.append(result["file1"])
-            similar_code_files.append(result["file2"])
-
-        # frequency of files which are similar
-        share_score = collections.Counter(similar_code_files)
-
-        return dict(share_score)
-
-    def getInsights(self):
-        """Analysis for Moss"""
-        mg = Mgroups()
-        similar_code_files = set()
-        insights = {}
-
-        for r in self.moss_results:
-            similar_code_files.add(r["file1"])
-            similar_code_files.add(r["file2"])
-
-        mg.createNodes(similar_code_files)
-
-        for r in self.moss_results:
-            mg.relatesTo(
-                r["percentage_file1"], r["percentage_file2"], r["file1"], r["file2"]
-            )
-
-        mg.set_tags()
-
-        insights["DtoC Paths"] = mg.d2c()
-        insights["DtoDC Paths"] = mg.d2dc()
-        insights["DCtoC Paths"] = mg.dc2c()
-
-        return insights