[FINAL] Update README.md

[yuujinleee]

지금 내 브랜치 로컬에서 수정 중이라 혹 궁금할까봐 중간중간 여기에 복붙해놓을게

ㅇㅅㅇ 💻

CSE364 Group11

Table of Contents

• About the Project
  • Built with
  • Repository Structure
• Getting Started
  • Prerequisites
  • Installation
• Milestone 1
  • Explanation of the Algorithm
  • Running the Tests
  • Examples
  • Supported Inputs
  • Rules for the Inputs
  • Combination of Multiple Genres as an Input
  • Error Codes
  • Examples for the Error Codes
  • About JUnit Test
  • Contribution by Area
• Milestone 2
  • Explanation of the Algorithm
  • 1) Bayesian Estimate
  • 2) Priority rule for including similar users
  • Running the Tests
  • Examples
  • Supported Inputs
  • Error Codes
  • Examples for the Error Codes
  • About JUnit Test
  • Contribution by Area
• Milestone 3 (Upcoming)
• Milestone 4 (Upcoming)
• Team members
• License & Acknowledgements

About the Project

This project is for the capstone project in SW Engineering (CSE364) at UNIST, developed by Yeongjun Kwak, Sanghun Lee and Yujin Lee. This will be further inplemented as a movie recommendation system. Currently under the development···

Built with

• Ubuntu 20.04
• Oracle JDK 11
• Apache Maven 3.6.3
  • Maven dependency tree
• IntelliJ IDEA (for the developers)

Repository Structure

CSE364_Project/
├── data/                             # Source data
├── scripts/                          # Documentation files
├── src/                              # Source files
│   ├── main/
│   │   └── java/
│   │       └── group11/
│   │           └── project.java
│   └── test/
│       ├── java/
│       │   └── group11/
│       │       └── projectTest.java
│       └── resources/   
├── target                            # Generated when mvn install
│   └── jacoco-report/
│   │       └── index.html            # JaCoCo Code Coverage Report                
├── pom.xml                           # Maven configuration
└── README.md

Getting Started

Instructions for setting up the project locally.

Prerequisites

• Docker should be installed and ready to use.
• For the git clone, the user should be registered as a Contributo or Collaborator of this git project. (Unless you have the OAuth access token.)

Installation

1. Download dockerfile and run.sh in the same directory.
2. (In the terminal) Build Docker Image and Container by running the following commands.

   $ docker build -t new_image_name /path/to/dockerfile

   $ docker run -it new_image_name

3. (In the Docker Container) Run . run.sh

   root@containerID:~/project# . run.sh

---

Milestone 1

Goal : Environment setup, data loading, data preprocessing

Explanation of the Algorithm

On Milestone 1, the code calculates and returns the average rating from ratings data for specified occupation and genre.

Running the Test

Continued from Installation steps.

1. (In the Docker Container) Run Java command with 2 arguments (InputStr1 InputStr2), accordingly Genre and Occupation input.

   root@containerID:~/project# java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project InputStr1 InputStr2

Examples

When valid inputs are passed, the output message will look like this :

// Input
java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project Adventure Educator
// Output
3.42

// Input
java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project Animation Doctor
// Output
3.68

Supported Inputs

• Genre (InputStr1) List

Genre			total:18
Action	Crime	Horror	Thriller
Adventure	Documentary	Musical	War
Animation	Drama	Mystery	Western
Children's	Fantasy	Romance
Comedy	Film-Noir	Sci-Fi

• Occupation (InputStr2) List
  • The words in parentheses can be used as a replacement for the one outside.

Occupation			total : 21
Academic (Educator)	Executive (Managerial)	Programmer	Technician (Engineer)
Artist	Farmer	Retired	Tradesman (Craftsman)
Clerical (Admin)	Homemaker	Sales (Marketing)	Unemployed
Collegestudent (College, Grad, Gradstudent)	K-12student	Scientist	Writer
Customerservice	Lawyer	Self-employed	Other
Doctor (Healthcare)

Rules for the Inputs

• The spelling of the inputs must be correct.

  Action    // Supported
  Accion    // X

• Both upper and lowercase letters are accepted.

  Action    // Supported
  action    // Supported
  ACTION    // Supported
  aCtIOn    // Supported

• The spacings must be omitted.

  Gradstudent   // Supported
  Grad student  // X

• The hyphens('-') must not be omitted.

  Sci-Fi    // Supported
  SciFi     // X

Combination of Multiple Genres as an Input

• In order to get the average rating of the movies that fall into a combination of multiple genres, connect the words with the pipeline('|') and enclosed by double quotation marks(" ").

  Action|Adventure               // X
  "Action|Adventure|"              // X (Pipeline should be between words)
  "Action|Adventure"             // Supported
  "Action|Adventure|Animation"   // Supported

  • In case of "Action|Adventure", the movies that fall into both Action and Adventure category are used for the calculation.
  • Combination of multiple occupations are not supported.

Error Codes

Possible errors thrown by invalid user input.

Table 1 Invalid input errors

Error	Code	Message	Description
InputEmptyError	1	No argument has passed. 2 arguments are required. (InputStr1 InputStr2)	Thrown when no input has entered.
InputNumError	2	Only 1 input has passed. 2 arguments are required.	Thrown when only 1 input has entered.
InputNumError	3	More than 2 arguments have passed. 2 arguments are required.	Thrown when more than 2 inputs have entered.
InputInvalidError	4	Entered genre input is invalid	Thrown when the entered genre (combination) is invalid.
InputInvalidError	5	Entered genre (inputString) doesn't exist. ( Invalid word : input_string )	Thrown when the word in the entered genre (OR the word in genre combination) is invalid.

Table 2 Invalid input warning

Warning	Code	Message	Description
InputInvalidWarning	6	Entered occupation doesn't exist. Rating by 'other' is shown instead.	Thrown when the 2nd input is invalid.

Table 3 No data exist error

Error	Code	Message	Description
NoDBError	7	Rating data matching the input pair doesn't exist.	Thrown when there's no available Rating data for the genre-occupation pair OR When there's no Movie data matching the entered genre (combination).

• If the system is terminated with the error code listed above, the system exit status is 1.

Examples for the Error Codes

Error code : 1~3

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project 

InputEmptyError : No argument has passed. 2 arguments are required. (InputStr1 InputStr2)
Error code: 1

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project Drama

InputNumError : Only 1 input has passed. 2 arguments are required.
Error code: 2

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project Drama Scientist Scientist

InputNumError : More than 2 arguments have passed. 2 arguments are required.
Error code: 3

Error code: 4

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project "|Adventure|Action" Scientist          

InputInvalidError : Entered genre input is invalid.
Error code: 4

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project "Adventure|Action|" Scientist 

InputInvalidError : Entered genre input is invalid.
Error code: 4

Error code: 5

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project "Adventure|Action|Horrrror" Scientist

InputInvalidError : Entered genre (horrrror) doesn't exist.
Error code: 5

Error code: 6

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project Adventure Librarian                  

InputInvalidWarning : Entered occupation doesn't exist. Rating by 'other' is shown instead.

The rating of adventure rated by other : 3.43

Error code: 7

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project "War|Crime" Academic  

NoDBError : Rating data matching the input pair doesn't exist.
Error code: 7

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project "Action|Animation|Children's|Sci-Fi|Thriller|War" retired

NoDBError : Rating data matching the input pair doesn't exist.
Error code: 7

• "War|Crime" Academic : Example for No Movie data matching the entered genre (combination).
• "Action|Animation|Children's|Sci-Fi|Thriller|War" retired : Example for No available Rating data for the genre-occupation input pair.

About Junit Test

The Junit test (and regarding csv test resources) for Milestone 1 has been moved to scripts/. For more information, please refer to this issue #20

Contribution by Area

Area	Contribution
Setting up a Git Repository	Yeongjun Kwak
Environment Setup	dockerfile, pom.xml Yujin Lee
Java Implementation	Models and Data Structures 👑 Yeongjun Kwak Exception Handling 👑 Sanghun Lee, Yeongjun Kwak Unit Test Building Yujin Lee Final Reviewer Sanghun Lee, Yeongjun Kwak
Documentation	README.md 👑 Yujin Lee, Sanghun Lee

---

Milestone 2

Goal : Implement Top 10 Movies Recommendation Features

Explanation of the Algorithm

On Milestone 2, the code returns the recommendation of Top 10 movies for specified gender, age, occupation or genre(s). First, to recommend 'relevant' movies, the code makes use of 1) Bayesian Estimate, which is used to calculate Top 250 movies by IMDB as well, when calculating and comparing the ratings of movies. Also, to set the 'similar' users (in case there aren't enough ratings that match gender, age and occupation), we have set 2) Priority rule for including similar users.

1) Bayesian Estimate

Bayesian Estimate is an estimator that can help minimizing the risk of including that minimizes the posterior expected value of a loss function. By making use of Bayesian Estimate, the algorithm calculates Weighted Rating (W) and arranges movies with W. In this way, the movies with very few ratings or below-average ratings will have comparably light weight.

In Detail, the calculation of Weighted Rating(W) is implemented by

• Making an ArrayList (classified_table) by selecting the object with more than m votes from movie_rating_table.
• Sorting the ArrayList with descending-weighted-rating-order and printing Top 10 movies from it.

The original reference for Baysian Estimate can be found here. However, in this project, the estimation method and variables has been set differently to adjust the differences in requirements.

W = (vR+mC)/(v+m)

Variables	Explanation
W	Weighted rating
v	Total number of ratings for the movie = (votes)
m	Minimum number of ratings required to be listed in the Top 10
R	Average rating for the movie as a number from 0 to 5 (mean)
C	Average rating across all the movies

• v and R

  • The value of v and R are obtained by making use of Movie_data_node.

• m : Minimum Number of Ratings

  • The value of m is obtained by the Percentile function. The function returns the number of votes of the movie that corresponds to (1-p)*100 % .

    static int Percentile(ArrayList<Movie_data_node> movie_rating_matrix, double p)

  • The value of p is differently set for number of movies by set_p function ; so that the validity of the weighted rating can be enhanced.

    static double set_p(int size){
    if(size<100){
        return 0.5;
    }
    else if(size<200){
        return 0.6;
    }
    else if(size<500){
        return 0.7;
    }
    else{
        return 0.8;
    }
    } 

    e.g If there are 1000 movies with average ratings, the function will return the number of ratings of 200th-highest movie.

• C : Average rating across all the movies

  • The value of C is obtained by the total_average_rating function.

    static double total_average_rating(ArrayList<Movie_data_node> movie_rating_matrix)

2) Priority rule for including similar users

The algorithm firstly makes the ArrayList(valid_user_list) of users that matches the inputs from users.dat. And then, this list is used to extract the ratings information and movie data from ratings.dat and movies.dat.

However, when there aren't sufficient amount of movie candidates to be ranked (On here, it is set to 100 movies) for specified user data, the 'similar' users will also be added to valid_user_list in order of precedence (priority) by function make_intersection_list_macro, until the number of movie candidates gets bigger than 100.

The similar users with priority are the users with :

1. Same Gender, Occupation and Gender
2. Same Gender and Occupation
3. Same Age range and Occupation
4. Same Occupation
5. Same Gender and Age range
6. Same Gender
7. Same Age range
8. All the users

The priority has set as above to give a more weighting on Occupation, and less on Gender and Age Range.

Running the Test

Continued from Installation steps.

1. (In the Docker Container) Run Java command with 3 or 4 arguments. The Arguments(InputStr1 InputStr2 InputStr3 InputStr4) are accordingly Gender, Age, Occupation, (and Genre).

   root@containerID:~/project# java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.milestone2 InputStr1 InputStr2 InputStr3 InputStr4

Examples

When valid inputs are passed, the output message will look like this :

Testing with 3 inputs

// Input
java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.milestone2 "F" "25" "Gradstudent"

// Output
Sixth Sense, The (1999) (http://www.imdb.com/title/tt0167404)
Matrix, The (1999) (http://www.imdb.com/title/tt0133093)
Shawshank Redemption, The (1994) (http://www.imdb.com/title/tt0111161)
Usual Suspects, The (1995) (http://www.imdb.com/title/tt0114814)
Silence of the Lambs, The (1991) (http://www.imdb.com/title/tt0102926)
Close Shave, A (1995) (http://www.imdb.com/title/tt0112691)
Wrong Trousers, The (1993) (http://www.imdb.com/title/tt0108598)
Cinema Paradiso (1988) (http://www.imdb.com/title/tt0095765)
American Beauty (1999) (http://www.imdb.com/title/tt0169547)
Raiders of the Lost Ark (1981) (http://www.imdb.com/title/tt0082971)

Testing with 4 inputs

// Input
java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.milestone2 "F" "25" "Gradstudent" "Action|Comedy"

// Output
Matrix, The (1999) (http://www.imdb.com/title/tt0133093)
Close Shave, A (1995) (http://www.imdb.com/title/tt0112691)
Wrong Trousers, The (1993) (http://www.imdb.com/title/tt0108598)
American Beauty (1999) (http://www.imdb.com/title/tt0169547)
Shakespeare in Love (1998) (http://www.imdb.com/title/tt0138097)
Raiders of the Lost Ark (1981) (http://www.imdb.com/title/tt0082971)
Cinema Paradiso (1988) (http://www.imdb.com/title/tt0095765)
Eat Drink Man Woman (1994) (http://www.imdb.com/title/tt0111797)
Raising Arizona (1987) (http://www.imdb.com/title/tt0093822)
Breakfast Club, The (1985) (http://www.imdb.com/title/tt0088847)

Supported Inputs

InputStr1	InputStr2	InputStr3	(InputStr4)
Gender	Age	Occupation	(Genre)

• Common Rules for the inputs

  • All the inputs must be enclosed with double quotation marks("").
  • The inputs are not case-sensitive, therefore both "Action", "action" and "AcTiOn" are allowed.

• Gender

  • Must be one letter and is not case-sensitive. i.e. one of those ; "F", "f", "M", "m".
  • Can be left empty when replaced by paired double quotation marks. i.e. ""
  • Examples

    "F"       // Supported
    "Female"  // X
    (nothing) // X (must be replaced by "")
    ""        // Supported

• Age

  • Must be an integer value bigger than 0.
  • Can be left empty when replaced by paired double quotation marks. i.e. ""
  • Examples

    "35"          // Supported
    "35.5"        // X
    "-23"         // X
    "Thirty-five" // X
    (nothing)     // X (must be replaced by "")
    ""            // Supported

• Occupation

  • For Occupation, the same rules from Milestone1 are applied here as well.
  • Can be left empty when replaced by paired double quotation marks. i.e. ""
  • Examples

    "k-12student"   // Supported
    "K12student"    // X (The hyphens must not be omitted.)
    (nothing)       // X (must be replaced by "")
    ""              // Supported

• Genre (When testing with 4 inputs)

  • For Genre, the same rules from Milestone1 are applied here as well.
  • For the combination of genre inputs, the formatting rules from Milestone 1 (Combination of multiple genres as an input) applies here as well.
    However, the pipeline(|) here is uesd to link OR conditions, not AND.
  • e.g. Adventure|Animation includes all the movies that are categorized as Adventure OR Animation to candidates for Top 10 movies.
  • Must NOT be left empty.
  • Examples

    "Film-noir"         // Supported
    "Filmnoir"          // X (The hyphens must not be omitted.)
    Action|Adventure    // X (Must be enclosed by pipeline)
    "Action|Adventure|" // X (Pipeline should be between words)
    ""                  // The genre must not be left empty.

Testing with 3 inputs

// Examples of Supported Inputs
“F” “25” “Gradstudent”
“M” “30” “Athletes”
“F” “” “retired”
“” “15” “”
“” “” “”

// Examples of Wrong Inputs
"F" "25"           // Empty part must be explicitly specified by ""
"25" "Gradstudent" // Empty part must be explicitly specified by ""

Testing with 4 inputs

// Examples of Supported Inputs
“F” “25” “Grad student” “Action|Comedy”
“M” “30” “Athletes” “Children’s”
“F” “” “retired” “Animation|Drama|Fantasy”
“” “15” “” “Sci-Fi”
“” “” “” “Romance|Comedy”

// Examples of Wrong Inputs
“F” “25” “Grad student” “”  // The genre must not be left empty.
“F” “25” “Grad student” “Action|Comedy” "Drama" // Extra arguments are not allowed.

Error Codes

Possible errors thrown by invalid input.

Table 1 Invalid input errors

Error	Message	Description
InputNumError	The input must be in this format : "gender" "age" "occupation" "genre" (genre is optional).	Thrown when the number of argument is not 3 or 4.
InputInvalidError	Entered gender input is invalid.	Thrown when the entered gender is invalid.
InputInvalidError	Entered age input is invalid. Age must be a natural number.	Thrown when the entered age is invalid.
InputInvalidError	Entered occupation (inputString) doesn't exist.	Thrown when the entered occupation is invalid.
InputInvalidError	Entered genre input is invalid.	Thrown when the entered genre is invalid.
InputInvalidError	Entered genre (inputString) doesn't exist.	Thrown when the entered genre is invalid.
InputEmptyError	Genre input hasn't passed. Genre must not be empty	Thrown when the "" is passed for the genre input.

Table 2 No data exist error

Error	Message	Description
NoDBError	There are no movie available for more than m votes	Thrown when there's no available movie list. This error is not likely to happen but implemented to prevent any error.
NoDBError	There are no movie available for specified inputs.	Thrown when there's no available movie list or there exist movie(s) with no votes only. This error is not likely to happen but implemented to prevent any error.

• If the system is terminated with the error code listed above, the system exit status is 1.

Examples for the Error Codes

여 기 수 정 ! !! ! !

Error code : 1~3

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project 

InputEmptyError : No argument has passed. 2 arguments are required. (InputStr1 InputStr2)
Error code: 1

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project Drama

InputNumError : Only 1 input has passed. 2 arguments are required.
Error code: 2

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project Drama Scientist Scientist

InputNumError : More than 2 arguments have passed. 2 arguments are required.
Error code: 3

Junit 추가 !! ! ! ! !

Contribution by Area

Area	Contribution
Java Implementation	Models and Data Structures 👑 Yeongjun Kwak Exception Handling 👑 Sanghun Lee, Yeongjun Kwak Unit Test Building Yujin Lee
Environment Setup	Maven Dependancy Yujin Lee
Documentation	README.md 👑 Yujin Lee

---

Milestone 3 (Upcoming)

Milestone 4 (Upcoming)

Team Members

• 20171012 Yeongjun Kwak (@sirin05137 ) - kyj05137@unist.ac.kr
• 20171183 Sanghun Lee (@sanghun17) - sanghun17@unist.ac.kr
• 20171194 Yujin Lee (@yuujinleee) - yujinlee@unist.ac.kr

License & Acknowledgements

• F. Maxwell Harper and Joseph A. Konstan. 2015. The MovieLens Datasets: History and Context. ACM Transactions on Interactive Intelligent Systems (TiiS) 5, 4, Article 19 (December 2015), 19 pages. DOI=http://dx.doi.org/10.1145/282787

[yuujinleee]

"F” Must be enclosed with double quotation mark 공백은 " " "" 둘다 허용

[yuujinleee]

For README, please include the followings in this milestone:

1. A short description of how your recommendation algorithm works. In case you are using an existing algorithm, describe what algorithm you used and how it works.

2. A description of how to run your program. An example of java command line will be good.

3. A description of supported inputs and expected outputs when inputs are not supported.

4. Roles of each member (i.e. who did what?)

[yuujinleee]

junit system exit 관련 외부 소스 사용 출처 쓰기

https://github.com/tginsberg/junit5-system-exit

[yuujinleee]

Error code 넘버링은 이제 제외

[yuujinleee]

Final Review on yujin branch by @sirin05137 and @sanghun17

최종 결과

• Pull request -> 합치고 Readme.md 1시간 🔥 🔥