Skip to content

Commit

Permalink
Merge pull request #190 from siqirua/branch-WrapUp
Browse files Browse the repository at this point in the history
Add implementation of stats to DG
  • Loading branch information
SinhaVedant authored Nov 13, 2023
2 parents 28210d5 + a82e9cb commit ac297a1
Show file tree
Hide file tree
Showing 9 changed files with 206 additions and 41 deletions.
106 changes: 86 additions & 20 deletions docs/DeveloperGuide.md
Original file line number Diff line number Diff line change
Expand Up @@ -221,13 +221,13 @@ The following sequence diagram illustrates the process of execution of an `FindS

### Sort Commands

The Sort related feature allows NUS professors to sort the currently displayed students or student scores. When successfully executed, the sorted students or student scores will be shown on the Graphical User Interface. <br>
The Sort related features allows NUS professors to sort the currently displayed students or student scores. When successfully executed, the sorted students or student scores will be shown on the Graphical User Interface. <br>

We will discuss the implementation of sortScore (Sort Student Scores) command here and omit the discussion of the implementation of sortStu command since it is very similar to sortScore command and simpler.
We will discuss the implementation of `sortScore` (Sort Student Scores) command here and omit the discussion of the implementation of `sortStu` command since it is very similar to `sortScore` command and simpler.

#### Implementation

The `sortScoreCommand` (Sort Student Scores) mechanism is facilitated by GradedComponentBook, StudentBook and StudentScoreBook. It implements the following operations:
The `sortScore` mechanism is facilitated by GradedComponentBook, StudentBook and StudentScoreBook. It implements the following operations:

* `GradedComponentBook#hasGc(GcName gcName)` - Returns true if a graded component is already created and in the graded component list.
* `studentScoreBook.sortStudentScore(Boolean isReverse)` - Filters the student scores with the given graded component and sort them according to the given reverse order.
Expand All @@ -251,8 +251,42 @@ The following sequence diagram shows how the sort student scores operation works

<puml src="diagrams/SortScoreCommandSequenceDiagram.puml" alt="SortScoreCommandSequenceDiagram"></puml>

The following activity diagram summarizes what happens when a user executes a new sortScore command:<br>
The following activity diagram summarizes what happens when a user executes a new `sortScore` command:<br>
<puml src="diagrams/SortScoreActivityDiagram.puml" alt="SortScoreActivityDiagram" />

### Stats Commands

The Stats related features allows NUS professors to calculate the statistics of student scores effectively. When successfully executed, the relevant statistics will be shown in the result display box of Graphical User Interface. <br>

We will discuss the implementation of `compStats` (calculate the statistics for a specific graded component) command here and omit the discussion of the implementation of `stats` command since it is very similar to `compStats` command and simpler.

#### Implementation

The `compStats` mechanism is facilitated by GradedComponentBook, StudentBook and StudentScoreBook. It implements the following operations:

* `GradedComponentBook#hasGc(GcName gcName)` - Returns true if a graded component is already created and in the graded component list.
* `studentBook.getStudentList()` - Returns the stored list of students.
* `compStatsCommand.generateOverallStatsSummary(List<Student> students)` - Returns a string represented all the relevant statistics.
* `statsCalculator` - A class that helps calculate different types of statistical measures.

Given below is an example usage scenario and how the `compStats` mechanism behaves at each step.

Step 1. The user executes `compStats c/Midterm` command to calculate the statistics of student scores of Midterm. The `compStats` command calls CompStatsCommandParser#parse() which parses the string keyed into the command line of the GUI.

Step 2. `CompStatsCommandParser#parse()` invokes the creation of a `CompStatsCommand` object.
> **Note**: If a command fails its execution due to incorrect command format, it will not create a `CompStatsCommand` object, an error message will be displayed and user will retype their command.
Step 4. Upon creation and execution of `CompStatsCommand` object, `GradedComponentBook#hasGc(GcName gcName)`, `studentBook.getStudentList()` and `compStatsCommand.generateOverallStatsSummary(List<Student> students)` methods are called.
> **Note**: If upon invoking `GradedComponentBook#hasGc(GcName gcName)` method and return value is false, it will throw an error and will not call the remaining two methods, so statistics will not be calculated and displayed.
Step 5. After successfully calculating the statistics, a `CommandResult` object will be created to show the calculated statistics.

The following sequence diagram shows how the `compStats` operation works:<br>

<puml src="diagrams/CompStatsCommandSequenceDiagram.puml" alt="SortScoreCommandSequenceDiagram"></puml>

The following activity diagram summarizes what happens when a user executes a new `compStats` command:<br>
<puml src="diagrams/CompStatsActivityDiagram.puml" alt="CompStatsActivityDiagram" />

### Auto-grading

Expand Down Expand Up @@ -684,28 +718,60 @@ testers are expected to do more *exploratory* testing.

1. Prerequisites: List all students using the `listAll` command. Multiple students in the list.

1. Test case: `deleteStu 1`<br>
Expected: First student is deleted from the student list. All related scores are deleted from the score list. Details of the deleted student shown in the status message. Timestamp in the status bar is updated.
1. Test case: `deleteStu 1`<br>
Expected: First student is deleted from the student list. All related scores are deleted from the score list. Details of the deleted student shown in the status message. Timestamp in the status bar is updated.

1. Test case: `deleteStu 0`<br>
Expected: No student is deleted. Error details shown in the status message. Status bar remains the same.
1. Test case: `deleteStu 0`<br>
Expected: No student is deleted. Error details shown in the status message. Status bar remains the same.

1. Other incorrect delete commands to try: `deleteStu`, `deleteStu x`, `...` (where x is larger than the list size)<br>
Expected: Similar to previous.

1. _{ more test cases …​ }_
1. Other incorrect delete commands to try: `deleteStu`, `deleteStu x`, `...` (where x is larger than the list size)<br>
Expected: Similar to previous.

### Finding a student
1. Find a student in ModuLight
1. Prerequisite: student list is not empty.
1. Test case: `findStu g/T00`
Expected: All students from tutorial group `T00` will be displayed. All graded components and all scores related to the displayed students should be displayed.
1. Test case: `findStu`
Expected: Since there is no search words given, all students, student scores and graded components will be displayed.
2. Test case: `findStu n/John n/Amy`
Expected: All students whose name contains `John` or `Amy` (case-insensitive) will be displayed. All graded components and all scores related to the displayed students should be displayed.
3. Test case: `findStu n/John g/T00`
Expected: All students whose name contains `John` (case-insensitive) and is from `T00` will be displayed. All graded components and all scores related to the displayed students should be displayed.
1. Test case: `findStu g/T00`
Expected: All students from tutorial group `T00` will be displayed. All graded components and all scores related to the displayed students should be displayed.
1. Test case: `findStu`
Expected: Since there is no search words given, all students, student scores and graded components will be displayed.
2. Test case: `findStu n/John n/Amy`
Expected: All students whose name contains `John` or `Amy` (case-insensitive) will be displayed. All graded components and all scores related to the displayed students should be displayed.
3. Test case: `findStu n/John g/T00`
Expected: All students whose name contains `John` (case-insensitive) and is from `T00` will be displayed. All graded components and all scores related to the displayed students should be displayed.

### Sorting Students
1. Sort students in ModuLight
1. Prerequisite: displayed student list is not empty.
2. Test case: `sortStu`
Expected: The displayed students are sorted by their total scores.
3. Test case: `sortStu o/n r/t`
Expected: The displayed students are sorted by their names in the reverse alphabetical order.
4. Test case: `sortStu o/wrongInput`
Expected: An error message that states "Invalid command format!" and the correct usage is shown.

### Sorting Student Scores
1. Sort student scores in ModuLight
1. Prerequisite: displayed student list and student score list are not empty and a graded component with name "Midterm" is created.
2. Test case: `sortScore c/Midterm`
Expected: Only Midterm student scores are shown and they are sorted in the ascending order.
3. Test case: `sortScore c/Final` (Assuming there is no such graded component with name "Final")
Expected: An error message that states "This graded component is not created. Please check if the information is correct" is shown.


### Calculating Statistics
1. Calculate overall statistics of students' total scores
1. Prerequisite: student list and student score list are not empty and there is at least a valid score in Tut `T01`.
1. Test case: `stats`
Expected: A message that states all relevant statistical measures (The exhausitive list can be found in [UG](https://ay2324s1-cs2103t-w08-2.github.io/tp/UserGuide.html#calculating-overall-statistics-stats)) are shown.
2. Test case: `stats st/max st/min`
Expected: A message that states the max and min is shown.
3. Test case: `stats g/T01`
Expected: A message that states all relevant statistical measures of Tut `T01` is shown.
4. Test case: `stats st/wrongInput`
Expected: An error message that states "Some statistic measures are not supported yet." and all supported statistical measures are shown.
2. Prerequisite: student score list is empty
1. Test case: `stats`
Expected: An error message that state "Please have at least one score fulfilling the condition." is shown.


### Saving data
Expand Down
29 changes: 18 additions & 11 deletions docs/UserGuide.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,16 +109,16 @@ The following section gives an overview of the parameters used for the commands

<box type="info" seamless>

> **Note**: Graded Component and Student Score parameters for score calculation
>
> * The maximum marks of a graded component and marks of a student score are both **absolute values** and are used together to
**Note**: Graded Component and Student Score parameters for score calculation

* The maximum marks of a graded component and marks of a student score are both **absolute values** and are used together to
determine the relative performance of a student for a component. <br> For instance, if the maximum marks for a component Midterms is 50, and the marks for the student is 35, then the student scored 35/50 =70% on this graded component.
> * The weightage of a graded component is used to determine its contribution to a student’s overall score, and is calculated
* The weightage of a graded component is used to determine its contribution to a student’s overall score, and is calculated
**relative to the sum of all other component weightages**. <br> For instance, if there are only 2 components in the system currently,
and component A has weightage 30, and component B weightage 20, then component A currently represents 20/(20+30) = 60% of
the student’s overall score. This is modified as components are added and removed. <br> Note that the **total weightage of all graded components should be less than or equal to 100**.
> * If a graded component has a maximum mark of 0, the relative score for any associated student scores will be 0.
> * If a student or graded component has no associated student scores, the average mark will be listed as 0.
* If a graded component has a maximum mark of 0, the relative score for any associated student scores will be 0.
* If a student or graded component has no associated student scores, the average mark will be listed as 0.

</box>

Expand Down Expand Up @@ -344,9 +344,16 @@ Sorts students' data by the given criteria.

Format: `sortStu [o/SORTING_ORDER] [r/REVERSE_ORDER]`

* The sorting order keyword must be one of the acceptable description given below: <br> "n",
"name", "s", "studentId", "studentID", "e", "email", "g", "tutorial", "tut",
"tutGroup", "ts", "totalScore", "totalscore", "score".
* The sorting order keyword must be one of the acceptable description given below: <br>

| Accepted keywords | Field to be sorted | Description |
|------------------------------------|--------------------|-----------------------------------------------------|
| `n`, `name` | `n/` | Name of the student by alphabetical order |
| `s`, `studentId`, `studentID` | `s/` | Student ID of the student by alphabetical order |
| `e`, `email` | `e/` | Email of the student by alphabetical order |
| `g`, `tutorial`, `tut`, `tutGroup` | `g/` | Tutorial group of the student by alphabetical order |
| `ts`, `totalScore`, `score` | NIL | Total score of the student by numerical value |

* The reverse order keyword must be one of the acceptable description given below: <br>
"decreasing", "0", "false", "f" (These 4 keywords have the same effect), "increasing", "1", "true", "t" (These 4
keywords have the same effect).
Expand Down Expand Up @@ -421,7 +428,7 @@ Format: `stats [st/STATS] [g/TUTORIAL_GRP]`
* It is allowed to omit `[st/STATS]`. In this case, it will return a summary of all statistics that are currently
supported.
* For stats keywords, it must be currently supported. Here is an exhaustive list of currently supported statistical
measures: mean, standardDeviation, upperQuartile, lowerQuartile, max, min, skewness.
measures: `mean`, `standardDeviation`, `upperQuartile`, `lowerQuartile`, `max`, `min`, `skewness`.
* For the calculation of upper and lower quartile, we use Method 4 introduced in [Wikipedia](https://en.wikipedia.org/wiki/Quartile).
* If there is only valid score matching the criteria, skewness will be displayed as `NaN` because skewness for one data
is meaningless.
Expand All @@ -441,7 +448,7 @@ Format: `compStats c/COMP_NAME [st/STATS] [g/TUTORIAL_GRP]`
* It is allowed to omit `[st/STATS]`. In this case, it will return a summary of all statistics that are currently
supported.
* For stats keywords, it must be currently supported. Here is an exhaustive list of currently supported statistical
measures: mean, standardDeviation, upperQuartile, lowerQuartile, max, min, skewness.
measures: `mean`, `standardDeviation`, `upperQuartile`, `lowerQuartile`, `max`, `min`, `skewness`.
* For the calculation of upper and lower quartile, we use Method 4 introduced
in [Wikipedia](https://en.wikipedia.org/wiki/Quartile).
* If there is only valid score matching the criteria, skewness will be displayed as `NaN` because skewness for one data
Expand Down
Binary file added docs/diagrams/CompStatsAcitivityDiagram.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
17 changes: 17 additions & 0 deletions docs/diagrams/CompStatsAcitivityDiagram.puml
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
@startuml
'https://plantuml.com/activity-diagram-beta

start
:User executes compStats command;
if () then ([given graded component exists\nand there is at least a valid score])
:all relevant statistics calculated;
:a summary of all statistics displayed;
else ([else])
:a error message shows up;
endif

:Execution completed;

stop

@enduml
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
73 changes: 73 additions & 0 deletions docs/diagrams/CompStatsCommandSequenceDiagram.puml
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
@startuml
!include style.puml

box Logic LOGIC_COLOR_T1
participant ":LogicManager" as LogicManager LOGIC_COLOR
participant ":ModuLightParser" as ModuLightParser LOGIC_COLOR
participant ":CompStatsCommandParser" as CompStatsCommandParser LOGIC_COLOR
participant "a:CompStatsCommand" as CompStatsCommand LOGIC_COLOR
participant ":StatsCalculator" as StatsCalculator LOGIC_COLOR
end box

box Model MODEL_COLOR_T1
participant ":Model" as Model MODEL_COLOR
end box
[-> LogicManager : execute(compStats c/Midterm)
activate LogicManager

LogicManager -> ModuLightParser : parseCommand(compStats c/Midterm)
activate ModuLightParser

create CompStatsCommandParser
ModuLightParser -> CompStatsCommandParser :CompStatsCommandParser()
activate CompStatsCommandParser

CompStatsCommandParser --> ModuLightParser
deactivate CompStatsCommandParser

ModuLightParser -> CompStatsCommandParser : parse(" c/Midterm")
activate CompStatsCommandParser

create CompStatsCommand
CompStatsCommandParser -> CompStatsCommand
activate CompStatsCommand

CompStatsCommand --> CompStatsCommandParser : c
deactivate CompStatsCommand

CompStatsCommandParser --> ModuLightParser : c
deactivate CompStatsCommandParser
'Hidden arrow to position the destroy marker below the end of the activation bar.
CompStatsCommandParser -[hidden]-> ModuLightParser
destroy CompStatsCommandParser

ModuLightParser --> LogicManager : c
deactivate ModuLightParser

LogicManager -> CompStatsCommand : execute()
activate CompStatsCommand

CompStatsCommand -> Model : getStudentList()
activate Model

Model --> CompStatsCommand
deactivate Model

create StatsCalculator
CompStatsCommand ->StatsCalculator : generateOverallStatsSummary(List<Student> students)
activate StatsCalculator


StatsCalculator --> CompStatsCommand
deactivate StatsCalculator
StatsCalculator -[hidden]-> CompStatsCommand
destroy StatsCalculator

CompStatsCommand --> LogicManager : result
deactivate CompStatsCommand
CompStatsCommand -[hidden]-> LogicManager : result
destroy CompStatsCommand

[<--LogicManager
deactivate LogicManager
@enduml
Binary file modified docs/diagrams/SortScoreAcitivityDiagram.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 2 additions & 1 deletion docs/diagrams/SortScoreAcitivityDiagram.puml
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,13 @@ start
if () then ([given graded component exists])
:student scores filtered and sorted;
:students sorted accordingly;
:Updated students and student scores list saved to ModuLight;
else ([else])
:a error message shows up;
:user retypes the command;
endif

:Updated students and student scores list saved to ModuLight;
: execution completed;

stop

Expand Down
Loading

0 comments on commit ac297a1

Please sign in to comment.