CS 314 Specification 3 - Using Multiple Classes - Baby Names

Programming Assignment 3: Individual Assignment. You must complete this assignment on your own. You may not acquire from any source (e.g. another student, an internet site, generative AI / chatbot / LLM such as chatGPT) a partial or complete solution to a problem or project that has been assigned. You may not show another student your solution to the assignment. You may not have another person (current student, former student, tutor, friend, anyone) “walk you through” how to solve an assignment. You may get help from the instructional staff. You may discuss general ideas and approaches with other students but you may not develop or debug code together. Review the class policy on collaboration from the syllabus.

• Placed online: Tuesday, September 9
• Due: no later than 11 pm, Thursday, September 19
• General Assignment Requirements

The purposes of this assignment are

1. to practice using Java ArrayLists
2. to implement a program that uses multiple classes. (object based programming, encapsulation)
3. to practice implementing individual classes based on a given specification

CAUTION: Take care to ensure your IDE does not add any non standard Java imports for other Java classes called Name or Names. In the past students submitted code with bad imports and lost all correctness points due to compile errors. Compile your .java files on the lab machines from the command line if you want to be sure you do not have any non standard Java imports. 

Files:

Description: This assignment is based on an assignment created by Nick Parlante and Stuart Reges' version of that assignment..

For this assignment you may not share your tests, but you CAN share your results when using different data files such as names2.txt and / or names4.txt

Complete a program that allows a user to query a data base of the 1000 most popular baby names in the United States per decade for a given number of decades under the constraints of the General Assignment Requirements and as described below.

As always, you may add helper methods and should do so to provide structure to the program and reduce redundancy.

One additional constraint: You must use the ArrayList class in your solution as discussed below.

Your program processes a file with data obtained from the Social Security Administration.  SSA has a web site showing the distribution of names chosen for children over the last 100 years in the US (https://www.ssa.gov/OACT/babynames/decades/).

Nick Parlante got the idea for this assignment from an article by Peggy Orenstein of the New York Times, Where have all the Lisas Gone?

Recently there was an article on predicting a someone's age based on their  name.

And some names that surge in popularity in a given decade turn out to be very old names. For instance, Tiffany. (Link to a CGP Grey video on YouTube that covers the history of the name Tiffany.)

The first example data file you are given is based on the 1000 most popular male and female names for kids born in the US going back to 1900.

The first two lines of the file are the base decade and the number of decades. The base decade indicates the decade for the first rank. The second line is an integer than indicates the  number of decades each name is ranked. This value shall be greater than or equal to 2. The given file starts

        1900
        11

The rest of the data file are names and there ranks. There is no indication in the data I give you whether a name is a female or male name. On each line there is  a name, followed by the rank of that name in the decades 1900, 1910, 1920, ..., 2000 (11 numbers), for the example file. Your program must handle different starting decades and number of ranks correctly.

Of course the starting decade and number of decades can vary. Look at the other example data files, names2.txt and names4.txt.

If a line does not have the correct number of ranks based on the the integer at the top of the file, your program shall ignore that line. (In other words do NOT include a NameRecord for this data in the Names object for lines in the data file without the correct number of ranks.)

Likewise, if a name has all zeros for ranks then do NOT  include a NameRecords object for that line in the Names object.

You may assume a given String never appears more than once as a name in a file. You may assume each line starts with a token representing a name and any tokens that follow this can be read as non negative ints in the range [0, 1000].

A rank of 1 indicates the name was the most popular name that year, while a rank of 997 was not very popular. A 0 in the data file means the name did not appear in the top 1000 that decade. 

...
Sam 58 69 99 131 168 236 278 380 467 408 466
Samantha 0 0 0 0 0 0 272 107 26 5 7
Samara 0 0 0 0 0 0 0 0 0 0 886
Samir 0 0 0 0 0 0 0 0 920 0 798
Sammie 537 545 351 325 333 396 565 772 930 0 0
Sammy 0 887 544 299 202 262 321 395 575 639 755
Samson 0 0 0 0 0 0 0 0 0 0 915
Samuel 31 41 46 60 61 71 83 61 52 35 28
Sandi 0 0 0 0 704 864 621 695 0 0 0
Sandra 0 942 606 50 6 12 11 39 94 168 257
...

Note,  a 0 in the data file means the name was NOT RANKED  in the top 1000 during the corresponding decade. It has some unknown rank greater than 1000. When you store a 0 from the data file in your NameRecord objects you may use something other than 0 if you think it will make your algorithms easier to implement. This is a suggestion, not a requirement. There are some trade offs involved. (Recall altering the way data is stored to fit our needs is part of the power of encapsulation.)

Also note the data does not indicate if a name was a girl's name or a boy's name. If a name appeared on the list of boys and girls names for a given decade the rank closest to one was used.

We see that “Sam” was #58 in 1900 and is slowly moving down. “Samantha” popped on the scene in 1960 and is moving up strong to #7. “Samir” barely appears in 1980, but by 2000 is up to #798.

You are given one one partial class, NameSurfer.java. This is the main driver class. After creating the database of names encapsulated in a class called Names.java the program displays a menu and allows the user to make various queries of the database.

Important. Do not hard code or assume every file will start with 1900 and / or have 11 ranks per name. Your program must read those values from the file and work correctly. I recommend you create your own results with names2.txt and names4.txt, then post the results to Ed discussion to compare with your classmates.

Suggested steps for implementing the program.

0. These suggested steps describe implementing the requirements. You may add more helper methods  if you want. You may store data in a different form than the input file. For example, the files uses a 0 to indicate the name had a rank greater than 1000 for a given decade. You can store a value other than 0 if you want. (The value for "not ranked in a given decade" is on the other side of the wall of abstraction.)

1. Implement and test a class called NameRecord. Each NameRecord object stores the data for an individual name, including the name itself (a String), the base decade (decade of the first rank), and the rank of the name for each decade. The ranks for each decade must be stored in an ArrayList of Integers. (this is to give you practice using ArrayList.) The class must have the following properties:

• A constructor with appropriate parameters to create a new NameRecord.
   
• a method to get the name for this NameRecord.
   
• a method that returns the base decade (decade of the first rank) for this NameRecord.

• a method that returns the total number of decades for this NameRecord, including the decades it is unranked.
   
• a method that returns the NameRecords rank for a given decade. You can use the convention that 0 is the start decade (1900 in the example file)), 1is the next decade (1910 in the example file), and so forth. In other words the parameter will be between 0 to (max number of ranks - 1) for given data set inclusive. In other words [0, num decades) or [0, num decades - 1]. This method returns 0 if the name is unranked in the given decade regardless of how you choose to store the unranked status for the NameRecord class.
   
• a method that returns an int for this NameRecord's best decade. In other words it returns the decade this name was most popular, using the most recent decade in the event of a tie. Return the actual decade based on the initial decade for this NameRecord's ranks. Looking at the data above, Samir's was most popular in 2000  while Sandra's best decade was 1940 . Johns's best rank was number 1 and it occurred in 1900 and 1910. The method shall return, the most recent decade, 1910.
   
• a method that returns the number of decades this name has been ranked in the top 1000.
   
• a method that returns true if this name has been ranked in the top 1000 in every decade
   
• a method that returns true if this name has been ranked in the top 1000 in only one decade
   
• a method that returns true if this name has been getting more popular every decade in the time period covered. This will be true if every decades rank is better (closer to 1) than the previous decade. The rank must improve every decade, it cannot be equal to the previous decade. [the integers representing ranks must be monotonically decreasing] So for example if the ranks were 0 950 900 875 850 800 750 700 650 600 500 400 are always improving. The ranks 0 0 0 800 850 800 750 700 650 600 500 400 are not always improving. Recall a 0 means the name did not appear in the top 1000 names for that decade. (When the rank is 0 indicating a name wasn't in the top 1000 in two consecutive decades we can't really decide one way or another if it improved from one decade to the next. So we assume it was not getting more popular.)
   
• a method that returns true if this name has been getting less popular [the integers representing ranks must be monotonically increasing] every decade in the time period covered. This will be true if every decades rank is worse than the previous decade. The rank must get worse, it cannot be equal to the previous decade. So for example the ranks 100 150 200 202 250 300 350 400 450 460 0 are always getting worse. The ranks  100 150 200 202 250 300 350 400 0 0 0 are not always getting worse.
   
• override the toString from Object. The format of the returned String must be:
  <NAME>
<BASE DECADE>: <RANK IN BASE DECADE>
<BASE DECADE+ 10>: <RANK IN BASE DECADE + 10>
...
<LAST DECADE>: <RANK IN LAST DECADE>
  
  Each line in the returned String has a newline at the end. If a name is not ranked in a given decade the Rank shall be a zero.
  
  
• The methods in the Names class that return lists of NameRecord objects require the names be is sorted ascending order. The easiest way to meet this requirement is to have the NameRecord class implement the Comparable interface.
  
  To do so, add the following implements clause to the class header:
  
  public class NameRecord implements Comparable<NameRecord>
  
  Now, you must implement the compareTo method from the Comparable interface. This will be an instance method in the NameRecord class.
  
  public int compareTo(NameRecord other) {
  
  This method is simple to implement as we want to compare NameRecord objects based on the String that represents the actual name. The String class also implement the Comparable interface so you can simply call compare to on the calling objects name, passing the name for the explicit parameter to the compareTo method, other, and return that result.
  
  Once the NameRecord class implements the Comparable interface you can then call the static Collections.sort() method on lists of NameRecord objects to sort the list.
  

After completing all these methods you shall thoroughly test the NameRecord class using individual lines from the names.txt file or with your own data. Include your testing code in a method in your NameSurfer class even though it will not be called when the program is run. Part of the assignment grade will be based on the tests you write for the NameRecord class. For this assignment you may not share tests.

2. Implement and test the Names class. This class stores all of the NameRecord objects in an ArrayList. (private ArrayList<NameRecord> names) This class must have the following methods. All methods that return an ArrayList of NameRecords or an  ArrayList of  Strings must be in sorted ascending order based on the names. Do not change the method headers provided in the Names.java file.

• A constructor that takes in a Scanner object. The Scanner object will already be hooked up to the names.txt file. The constructor must read in the base decade and number of ranks per name and then use the Scanner to go through all the names in the file and create a NameRecord object for each one. This can be done with the following code:
  
while( fileScanner.hasNextLine() ){
    String line = fileScanner.nextLine();
    /* create a NameRecord object based on line and add it to the ArrayList of NameRecord objects */
}
  
  How do you parse the String into the name and the years? Use the split method from the String class or a Scanner object. If you use the split method from the String class the statement would be:
  
  String[] parsedData = data.split("\\s+"); //data is the input String
  
  This parses the String into its individual components using whitespace as delimiters. The name itself will be the first element of the resulting array and the ranks will be in the remaining elements, although they will be Strings. You must convert them to ints using the Integer.parseInt method..
  
  The other approach for parsing the input is to use a Scanner object.
  
  Scanner lineScanner = new Scanner(data);  //data is the input String
  
  Once the Scanner object is created you can use the next method to pull out the name and then the nextInt method to pull out the ranks. See the Java documentation for more details on the split method from the String class and Scanner objects.
  
  Recall if a line does not have the correct number of ranks or all the ranks are 0 (unranked) you do not add a NameRecord for that line to the list of NameRecords stored in Names object.
  
  After constructing the ArrayList of NameRecord objects you may find it useful to sort it by calling the Collections.sort(List) method.
  
  Do not alter the method headers of the methods given in Names.java. Implement the following methods:
   
• A method name getName that returns the NameRecord whose name is equal to a given String ignoring case. If there is no NameRecord that matches the given String ignoring case, return null.
   
• A method that returns an ArrayList of NameRecord objects that contain a given substring, ignoring case.  The names must be in sorted order based on name.
  public ArrayList<NameRecord> getMatches(String partialName)
   
• A method that returns an ArrayList of Strings of names that have been ranked in the top 1000 or better in every decade. The Strings  must be in sorted order based on name.
  public ArrayList<String> rankedEveryDecade()
   
• A method that returns an ArrayList of Strings of names that have been ranked in the top 1000 or better in exactly one decade. The Strings  must be in sorted order based on name.
  public ArrayList<String> rankedOnlyOneDecade()
   
• A method that returns an ArrayList of Strings of names that have been getting more popular every decade. The Strings  must be in sorted order based on name.
  public ArrayList<String> alwaysMorePopular()
   
• A method that returns an ArrayList of Strings of names that have been getting less popular every decade. The Strings  must be in sorted order based on name.
  public ArrayList<String> alwaysLessPopular()
   
• implement a method of your own that checks for names that meet some criteria of your own design. You must thoroughly document what your criteria is in the method comments. Part of your grade will be based on how original and creative this method is. Do not share this method with others or on the class discussion group. I don't consider finding names that are palindromes very interesting. Nor is finding the top 10 or X names in a given decade very original.

3. Complete the methods in the NameSurfer class and add your method the missing  menu option, your interesting search or processing.

The menu choices must be:

1 to search for names.
2 to display data for one name.
3 to display all names that appear in only one decade.
4 to display all names that appear in all decades.
5 to display all names that are more popular in every decade.
6 to display all names that are less popular in every decade.
7 to perform the method of your own design from your Names class
8 to quit

For expected program behavior review the sample run log. Your output should match that of the sample run log for the various operations, except that you will not trim the output for operations that results in a large number of names and your output shall include the description of the search you developed. Also, we will not grade based on the output of NameSurfer, rather we will call methods from your Names class and check those results. So there can be minor differences in the output of your NameSurfer and what is shown in the log.

4. Neat searches. This is an interesting application because when your program is finished you can investigate various trends in naming children. In a comment at the top of the file discuss one interesting trend you found and back it up with data / results. Here are some examples. (You may not use these as your interesting trend. Do not share your interesting trend on the discussion group.)

• Why do you think Rock was popular in the 1950s and Trinity in the 2000s?
• Type in your grandparents names. Mildred, Earl, and Clem sound old fashioned (my grandparents' names, then there is my maternal grandmother who was named Catherine which has been solid for a long time, but is starting to slip.). But wait long enough and some names stage a come back. Emma. Hannah. Isabelle. Anna.
• Try historical names like Sigmund, Adolf, and Ike. What about variations such as Adolph?
• Why are some letters listed as names. A? M? J? (In a more recent version of the database single letter names are not included.)

Submission: Fill in the header for NameSurfer.java and copy it into NameRecord.java and Names.java. Replace <NAME> with your name. Note, you are stating, on your honor, that you did the assignment on your own. Submit NameSurfer.java, NameRecord.java, and Names.java to assignment 3 on Gradescope.

Checklist: Did you remember to:

1. review and follow the general assignment requirements including the program hygiene requirements?
2. ensure you classes are part of the default package? (in other words, no package statements in your source code)
3. ensure you do not have any extraneous imports for Name or Names classes?
4. work on the assignment individually? This includes making your own tests (this assignment only)
5. fill in the header in NameSurfer.java and Names.java and copy it to your NameRecord.java file?
6. complete the NameRecord class?
7. include your tests of the NameRecord class in the NameSurfer class? Do not share your tests on this assignment. You can share the results of calls to the Names method with data files other than names.txt on Piazza.
8. complete the Names class with the required methods?
9. complete the NameSurfer class?
10. add your own menu option for an interesting search and document it at the top the NameSurfer class?
11. use an ArrayList of Integers to store the ranks in the NameRecord class and an ArrayList of NameRecords in the Names class to store all the NameRecords?
12. comment on an interesting trend or pattern you found using your completed program at the top the NameSurfer class?
13. turn in your files (NameSurfer.java, Names.java, and NameRecord.java) to Assignment 3 on Gradescope by Thursday, September 19?