---
title: "PA 8.1: The Twelve Days of Christmas"
subtitle: "Starter Functions"
format: 
  html:
    embed-resources: true
    code-tools: true
    toc: true
    number-sections: true
editor: source
execute: 
  error: true
  echo: true
  message: false
  warning: false
---

```{r setup}
#| include: false
library(tidyverse)
library(glue)
```

[Download starter .qmd template](../student-versions/pas/pa8-1.qmd)

[Download xmas.csv data](_data/xmas.csv)

## Introduction {-}

The song *The Twelve Days of Christmas*, written around 1780, tells the tale of the many gifts one person receives in the days after Christmas ([link to lyrics](https://en.wikipedia.org/wiki/The_Twelve_Days_of_Christmas_(song))).

::: callout-note

You can watch a video of *The Twelve Days of Christmas* being performed at the [Cambria Christmas Market](https://www.youtube.com/watch?v=_N9UeQRf_aQ&ab_channel=SanLuisObispoCountyVisitorsGuide).

:::

The gifts in this song repeat and compound. For example, on the first day, the narrator receives:

    A partridge in a pear tree.

On the twelfth day, they receive:

    Twelve Drummers Drumming
    Eleven Pipers Piping
    Ten Lords a Leaping
    Nine Ladies Waiting
    Eight Maids a Milking
    Seven Swans a Swimming
    Six Geese a Laying
    Five Golden Rings
    Four Calling Birds
    Three French Hens
    Two Turtle Doves
    And a Partridge in a Pear Tree

This week, your task is to write functions that will automatically sing this very repetitive song. In the practice activity, we will start by writing **two helper functions**. 

## Dataset {-}

Save the `xmas.csv` on your computer (in a place that makes sense!) and edit the provided code to load a dataset called `xmas`. This dataset contains the crucial information about each gift in the song. We will use this dataset to test our functions as we work on them.

```{r}
xmas <- read.csv("xmas.csv")
```

::: callout-tip
### Advice

##### Workflow {-}

+ Make smaller versions of the `xmas` dataset (e.g., the first two days) to test your functions *before* testing them on the full data set.
+ Your functions should reference each other. That is, don't duplicate code; use earlier, smaller functions inside your larger functions.

##### Build from small pieces {-}

+ If you have some trouble getting started, I recommend writing a function that works in one case (e.g., for day 3), and then trying to generalize it.

##### Don't sweat the small stuff {-}

+ There's a lot you can do to polish the way the song prints, but we're going to leave that be.
+ At this point, don't get bogged down in details like how the song displays, or small grammar rules (like commas!). 
:::

## Plurals -- `pluralize_gift()`

In the `xmas` dataset, the gifts are listed as singular. For example, on day 5, the narrator in the song receives "five golden rings", but the entry in the dataset for gift 5 simply says "ring".

::: callout-tip

# Hint 
The gifts on days six and nine have unusual pluralization (not just adding an "s"). You may assume that in any other dataset we might apply this function to, there will be **no** additional special cases beyond these two types.

:::

::: callout-caution

#### Important!

You should **absolutely not** hard-code anything into this function. It should work in general, not just for the items in the traditional version of *The Twelve Days of Christmas*.

For example, the word "ring" should not appear anywhere in the function. I should be able to give your function **any gift** and get back the plural of that gift.

:::

Complete the `pluralize_gift()` function below. This function should take in a gift (or a vector of gifts) and return the appropriate plural(s).

```{r pluralize-function}
# Function that takes a noun and makes it plural
# Arguments: gift -- a string or vector of strings
# Return:    a string or vector of strings with the pluralized words

pluralize_gift <- function(gift){

  
  

  return(gift)
}
```

::: callout-note

### Test Your Function

Try your function on a smaller and then on the full gift dataset.

```{r pluralize-test}
# If your function is vectorized:
pluralize_gift(xmas$Gift.Item)

# If your function is not vectorized:
map_chr(xmas$Gift.Item, pluralize_gift)
```

:::

## Creating Sentences -- `make_phrase()`

Write a function called `make_phrase()` that takes in the necessary information and returns a phrase. For example:

    make_phrase(num       = 10,
                item      = "lord", 
                verb      = "a-leaping", 
                adjective = "", 
                location  = "")

should return

    "ten lords a-leaping"

::: callout-tip

The `Day.in.Words` variable isn't quite what you want. You want `12` to say `"twelve"` **not** `"twelfth"`. I suggest using the `english` package to create number words from number digits.

If you get a frustrating error from the `english` package, try wrapping `as.character()` around your new number word.

:::
    
```{r phrase-function}
make_phrase <- function(num, item, verb, adjective, location) {
  
  ## Step 1: Replace NAs with blank strings.
  verb <- str_replace_na(verb, "")
  
  
  ## Step 2: If the day number is larger than 1, the gift must be plural.
  ### Hint: call the function you created above!
  
  
  ## Step 3: Figure out if the gift starts with a vowel.
  
  
  ## Step 4: For day 1, if the gift starts with a vowel, make day_word be "an" and if the gift does not start with a vowel, make the day_word be "a" (e.g. a partridge in a pear tree).
  ### For the other days, make day_word be the number word (e.g. ten lords a-leaping).
  ### See the tip above about turning numbers into words (e.g. 10 into ten).
  day_word
  
  ## Step 5: Glue all of the pieces together into one string and return!
  
  return(phrase)
}
```

::: callout-note
### Test Your Function

Try your function out on the `xmas` data by making a new variable containing the daily phrases. I've provided you with skeleton code to iterate through each row of the dataset -- all you need to do is provide the necessary inputs.

```{r}
xmas2 <- xmas |> 
  mutate(full_phrase = pmap_chr(.l = list(num       = ______,
                                          item      = ______, 
                                          verb      = ______, 
                                          adjective = ______, 
                                          location  = ______), 
                                .f = make_phrase))
xmas2
```
:::

## Canvas Submission {-}

> Your `full_phrase` column is the answer to this week's practice activity.
>
> Take a screenshot of your `full_phrase` column to show me the phrases you made!
