9 Discussion Forum Dashboard Functions
9.1 Wrangling Functions
9.1.1 get_activity_levels
9.1.1.1 Main Documentation
Convert sum_dt to activity_level.
Description:
Convert sum_dt to activity_level.
Usage:
get_activity_levels(forum)
Arguments:
forum: A forum dataframe.
Value:
The same dataframe with a new column for activity_level.
Examples:
get_activity_levels(forum)
9.1.2 get_discussion_vars_json
9.1.2.1 Main Documentation
Get the variables associated with each forum element in the JSON file.
(for use in 'prepare_json').
Description:
Get the variables associated with each forum element in the JSON
file. (for use in 'prepare_json').
Usage:
get_discussion_vars_json(i, all_elements)
Arguments:
i: An iterator.
all_elements: A nested list containing attributes for each course
element.
Value:
A vector containing the 'commentable_id', 'display_name',
'discussion_category', and 'discussion_target' of a course
element.
Examples:
get_discussion_vars_json(i, all_elements)
9.1.3 get_discussion_vars_xml
9.1.3.1 Main Documentation
Get the variables associated with each forum element in the XML file
(for use in 'prepare_xml').
Description:
Get the variables associated with each forum element in the XML
file (for use in 'prepare_xml').
Usage:
get_discussion_vars_xml(i, all_parameters)
Arguments:
i: An iterator.
all_parameters: An XML tree containing all the parameters associated
with each discussion node.
Value:
A vector containing the 'display_name', 'discussion_category', and
'discussion_target' of a course element.
Examples:
get_discussion_vars_xml(i, all_parameters)
9.1.4 infer_post_subcategories
9.1.4.1 Main Documentation
Infer the subcategories of each post, even if it's a response post or a
comment.
Description:
Infer the subcategories of each post, even if it's a response post
or a comment.
Usage:
infer_post_subcategories(forum)
Arguments:
forum: A forum dataframe.
Value:
The same dataframe with commentable_id filled in for everything.
Examples:
infer_post_subcategories(forum)
9.1.5 prepare_json
9.1.5.1 Main Documentation
Prepare the JSON file for joining with the XML file.
Description:
Prepare the JSON file for joining with the XML file.
Usage:
prepare_json(json)
Arguments:
json: A JSON file containing information about the course elements.
Value:
A dataframe with four columns: 'commentable_id', 'display_name',
'discussion_category', and 'discussion_target'.
Examples:
prepare_json(json)
9.1.6 prepare_posts
9.1.6.1 Main Documentation
Prepare the forum posts.
Description:
Prepare the forum posts.
Usage:
prepare_posts(forum)
Arguments:
forum: A dataframe with one post per row.
Value:
The prepared forum posts data.
Examples:
prepare_posts(forum)
9.1.7 prepare_searches
9.1.7.1 Main Documentation
Prepare the forum searches dataframe.
Description:
Prepare the forum searches dataframe.
Usage:
prepare_searches(forum)
Arguments:
forum: A dataframe with one search event per row.
Value:
The forum searches data with a new column for activity level.
Examples:
prepare_searches(forum)
9.1.8 prepare_views
9.1.8.1 Main Documentation
Prepare the forum views dataframe.
Description:
Prepare the forum views dataframe.
Usage:
prepare_views(forum)
Arguments:
forum: A dataframe with one read event per row.
Value:
The prepared forum views data.
Examples:
prepare_views(forum)
9.1.9 prepare_words
9.1.9.1 Main Documentation
Prepare the forum words.
Description:
Prepare the forum words.
Usage:
prepare_words(forum)
Arguments:
forum: A dataframe with one row per post.
Value:
The dataframe with each row containing a word, prepared for
joining with the forum elements.
Examples:
prepare_words(forum)
9.1.10 prepare_xml
9.1.10.1 Main Documentation
Prepare the XML file for joining with the JSON file.
Description:
Prepare the XML file for joining with the JSON file.
Usage:
prepare_xml(xml)
Arguments:
xml: An XML file containing information about the course elements.
Value:
A dataframe with three columns: 'display_name',
'discussion_category', and 'discussion_target'.
Examples:
prepare_xml(xml)
9.1.11 wrangle_forum
9.1.11.1 Main Documentation
Write the forum posts and forum words to csv.
Description:
Write the forum posts and forum words to csv.
Usage:
wrangle_forum(posts_input_path, views_input_path, searches_input_path,
json_input_path, xml_input_path, posts_output_path, words_output_path,
views_output_path, searches_output_path, elements_output_path)
Arguments:
posts_input_path: The path to the CSV file containing the forum posts
data.
views_input_path: The path to the CSV file containing the forum reads
data.
searches_input_path: The path to the CSV file containing the forum
searches data.
json_input_path: The path to the JSON file containing data on all
course elements.
xml_input_path: The path to the XML file containing data on the course
structure.
posts_output_path: The desired path to which to write the prepared
forum posts dataframe.
words_output_path: The desired path to which to write the prepared
forum words dataframe.
views_output_path: The desired path to which to write the prepared
forum views dataframe.
searches_output_path: The desired path to which to write the prepared
forum searches dataframe.
elements_output_path: The desired path to which to write the prepared
forum elements dataframe.
Value:
None.
Examples:
wrangle_forum(csv_path, json_path, xml_path)
9.2 Server Functions
9.2.1 apply_forum_filters
9.2.1.1 Main Documentation
Apply the selected filter settings to the forum data.
Description:
Apply the selected filter settings to the forum data.
Usage:
apply_forum_filters(input_df, forum_elements, activity_level = "All",
gender = "All", registration_status = "All", category = "All")
Arguments:
input_df: The input dataframe.
forum_elements: The forum elements dataframe.
activity_level: One of 'under_30_min', '30_min_to_5_hr', 'over_5_hr',
or (default) 'All'.
gender: One of 'male', 'female', 'other', or (default) 'All'.
registration_status: One of 'audit', 'verified', or (default) 'All'.
category: One of the forum categories.
Value:
'filtered_df' A dataframe filtered by the selected settings.
Examples:
apply_forum_filters(forum_posts, forum_elements, "All", "All", "All")
9.2.2 calculate_forum_searches
9.2.2.1 Main Documentation
Calculates the number of unique users who searched for each search
query, given the selected filters.
Description:
Calculates the number of unique users who searched for each search
query, given the selected filters.
Usage:
calculate_forum_searches(forum_searches = wrangled_forum_searches,
forum_elements, activity_level, gender, registration_status, category)
Arguments:
forum_searches: The wrangled forum searches dataframe.
forum_elements: The forum elements dataframe.
activity_level: The activity level of the students.
gender: The gender of the students.
registration_status: The registration status of the students.
category: The forum category.
Value:
'forum_searches' The filtered forum searches dataframe.
Examples:
calculate_forum_searches(wrangled_forum_searches, "under_30_min", "female", "verified", "Part 3")
9.2.4 count_posts
9.2.4.1 Main Documentation
Count the number of posts for each subcategory in an input forum.
Description:
Count the number of posts for each subcategory in an input forum.
Usage:
count_posts(input_forum, wrangled_forum_elements)
Arguments:
input_forum: The input dataframe containing a row for each post in the
forum.
wrangled_forum_elements: A dataframe containing information about each
of the forum subcategories.
Value:
'post_counts' A dataframe containing the post counts for each
subcategory in the forum.
Examples:
count_posts(wrangled_forum_posts)
9.2.5 count_views
9.2.5.1 Main Documentation
Count the number of view events for each subcategory in an input forum.
Description:
Count the number of view events for each subcategory in an input
forum.
Usage:
count_views(input_forum, wrangled_forum_elements)
Arguments:
input_forum: The input dataframe containing a row for each read event
in the forum.
wrangled_forum_elements: A dataframe containing information about each
of the forum subcategories.
Value:
'view_counts' A dataframe containing the read counts for each
subcategory in the forum.
Examples:
count_views(wrangled_forum_views)
9.2.6 filter_forum_elements
9.2.6.1 Main Documentation
Filter the forum elements by the selected filter variables.
Description:
Filter the forum elements by the selected filter variables.
Usage:
filter_forum_elements(forum_elements, category)
Arguments:
forum_elements: The forum elements dataframe that was passed in from
the wrangling script.
category: The forum category that the user has selected.
Details:
The forum elements dataframe only needs to be filtered by
category, since it doesn't include any variables related to
students.
Value:
'filtered_forum_elements' The same dataframe, filtered by category
if appropriate.
Examples:
filter_forum_elements(wrangled_forum_elements, "Part 1")
9.2.7 filter_wordcloud_data
9.2.7.1 Main Documentation
Filter the wordcloud data by the selected filters.
Description:
Filter the wordcloud data by the selected filters.
Usage:
filter_wordcloud_data(forum_words, forum_elements, activity_level, gender,
registration_status, category)
Arguments:
forum_words: The forum words dataframe passed in from the wrangling
script.
forum_elements: The forum elements dataframe.
activity_level: The activity level of the students.
gender: The gender of the students.
registration_status: The registration status of the students.
category: The forum category.
Value:
'filtered_wordcloud_data' The filtered forum words dataframe.
Examples:
filter_wordcloud_data(wrangled_forum_words, forum_elements, "30_min_to_5_hr", "female", "All", "General")
9.2.8 gather_post_types
9.2.8.1 Main Documentation
Gather the post types into a single column for easy plotting.
Description:
Gather the post types into a single column for easy plotting.
Usage:
gather_post_types(forum_data, grouping_var)
Arguments:
forum_data: The forum data for the main barplot.
grouping_var: grouping_var One of 'discussion_category' or
'display_name', depending on whether a category has been
selected.
Value:
'gathered' A dataframe with the post types gathered into a single
column.
Examples:
gather_post_types(forum_data, grouping_var = "discussion_category")
9.2.10 get_forum_threads
9.2.10.1 Main Documentation
Get the forum threads for the authors who match the filter settings.
Description:
Get the forum threads for the authors who match the filter
settings.
Usage:
get_forum_threads(forum_posts, forum_elements, activity_level, gender,
registration_status, category, selected_subcategory)
Arguments:
forum_posts: The forum posts dataframe that was passed in from the
wrangling script.
forum_elements: The forum elements dataframe.
activity_level: The activity level of the students.
gender: The gender of the students.
registration_status: The registration status of the students.
category: The selected forum category.
selected_subcategory: The selected forum subcategory.
Value:
'forum_threads' The forum threads that were authored by students
for which the filter settings apply.
Examples:
get_forum_threads(forum_posts = wrangled_forum_posts, forum_elements, "over_5_hr", "female", "audit", "All", "All")
9.2.11 get_label_lengths
9.2.11.1 Main Documentation
Get the lengths of the labels on the main barplot (either the
categories or the subcategories).
Description:
Get the lengths of the labels on the main barplot (either the
categories or the subcategories).
Usage:
get_label_lengths(forum_data, category)
Arguments:
forum_data: The forum data for the main barplot.
category: The selected category.
Value:
'label_lengths' A list with the lengths (in characters) of each
label on the main plot.
Examples:
get_label_lengths(forum_data, "Technical Questions")
9.2.12 get_post_types
9.2.12.1 Main Documentation
Get the post types.
Description:
Get the post types.
Usage:
get_post_types(forum)
Arguments:
forum: A forum dataframe.
Value:
The same dataframe with a new column for post_type.
Examples:
get_post_types(forum)
9.2.13 get_subcategory_options
9.2.13.1 Main Documentation
Get the options for the subcategory options, given the selected
category.
Description:
Get the options for the subcategory options, given the selected
category.
Usage:
get_subcategory_options(category, filtered_forum_elements)
Arguments:
category: The selected category.
filtered_forum_elements: The forum elements dataframe, filtered by the
selected category.
Value:
'subcategory_options' A list of options for the user to select
from.
Examples:
get_subcategory_options("Part 1", filtered_forum_elements)
9.2.14 get_target_word_counts
9.2.14.1 Main Documentation
Get the top words for each subcategory.
Description:
Get the top words for each subcategory.
Usage:
get_target_word_counts(input_forum)
Arguments:
input_forum: The input dataframe containing a row for each word in the
forum.
Value:
'word_counts' A dataframe containing the counts for each word in
each subcategory.
Examples:
get_target_word_counts(wrangled_forum_words)
9.2.15 get_wordcloud_data
9.2.15.1 Main Documentation
Get the counts of each word in the selected subcategories.
Description:
Get the counts of each word in the selected subcategories.
Usage:
get_wordcloud_data(filtered_wordcloud_data, filtered_forum_elements, category,
selected_subcategory)
Arguments:
filtered_wordcloud_data: The filtered forum words dataframe.
filtered_forum_elements: The filtered forum elements dataframe.
category: The selected category.
selected_subcategory: The selected subcategory.
Value:
'wordcloud_data' A dataframe with the counts of each word in the
selected subcategory(ies).
Examples:
get_wordcloud_data(filtered_wordcloud_data, filtered_forum_elements, "Part 1", "Part 1 Lecture 1 Discussion")
9.2.16 make_forum_barplot
9.2.16.1 Main Documentation
Make the main barplot for displaying the forum data.
Description:
Make the main barplot for displaying the forum data.
Usage:
make_forum_barplot(forum_data, xvar_string, plot_variable, fill_value,
axis_limit, category, ylabel, breakdown)
Arguments:
forum_data: The forum data for the main barplot.
xvar_string: A string that matches the function to call for the x value
of aes_string().
plot_variable: One of (default) 'posts', 'authors', or 'views'.
fill_value: A hex value representing the color for the bar fill.
axis_limit: The maximum axis limit for the horizontal axis in the main
barplot.
category: The selected category.
ylabel: The label of the y-axis in the main barplot.
breakdown: One of 'TRUE' or 'FALSE'; determines whether the post types
breakdown is shown.
Value:
'forum_barplot' A ggplot2 object to be rendered as the main forum
barplot.
Examples:
make_forum_barplot(forum_data, xvar_string = "fct_reorder(discussion_category, course_order, .desc = TRUE)", plot_variable = "authors", fill_value = "red", axis_limit = 100, category = "All", ylabel = "Category", breakdown = FALSE)
9.2.17 make_forum_breakdown_barplot
9.2.17.1 Main Documentation
Make the main forum barplot with the post types breakdown.
Description:
Make the main forum barplot with the post types breakdown.
Usage:
make_forum_breakdown_barplot(gathered, xvar_string, grouping_var, axis_limit,
xlabel)
Arguments:
xvar_string: A string that matches the function to call for the x value
of aes_string().
grouping_var: grouping_var One of 'discussion_category' or
'display_name', depending on whether a category has been
selected.
axis_limit: The maximum axis limit for the horizontal axis in the main
barplot.
xlabel: The label of the x-axis in the main barplot.
forum_data: The forum data for the main barplot.
Value:
'forum_breakdown_barplot' A ggplot2 object to be rendered as the
main forum barplot.
Examples:
make_forum_breakdown_barplot(forum_data = forum_data, xvar_string = "fct_reorder(discussion_category, course_order, .desc = TRUE)", axis_limit = 100, grouping_var = "discussion_category", xlabel = "Category")
9.2.18 make_wordcloud
9.2.18.1 Main Documentation
Make the wordcloud.
Description:
Make the wordcloud.
Usage:
make_wordcloud(wordcloud_data, max_words = 20, scale = c(3.5, 1))
Arguments:
wordcloud_data: A dataframe showing the counts of the top words in the
selected subcategory.
max_words: The maximum number of words to show in the wordcloud.
Default is 20.
scale: A list giving the range of sizes to for the display of words
in the wordcloud. Default is c(3.5,1).
Value:
A wordcloud object.
Examples:
make_wordcloud(wordcloud_data, max_words = 30, scale = c(4,1.5))
9.2.19 set_axis_limit
9.2.19.1 Main Documentation
Warning in parse_Rd("../../r-package/man/set_axis_limit.Rd", encoding =
"unknown", : ../../r-package/man/set_axis_limit.Rd:21: unexpected section
header '\value'Warning in parse_Rd("../../r-package/man/set_axis_limit.Rd", encoding =
"unknown", : ../../r-package/man/set_axis_limit.Rd:24: unexpected section
header '\description'Warning in parse_Rd("../../r-package/man/set_axis_limit.Rd", encoding =
"unknown", : ../../r-package/man/set_axis_limit.Rd:27: unexpected section
header '\details'Warning in parse_Rd("../../r-package/man/set_axis_limit.Rd", encoding =
"unknown", : ../../r-package/man/set_axis_limit.Rd:33: unexpected section
header '\examples'Warning in parse_Rd("../../r-package/man/set_axis_limit.Rd", encoding = "unknown", : ../../r-package/man/set_axis_limit.Rd:36: unexpected END_OF_INPUT '
'Set the horizontal axis limit of the main barplot.
Usage:
set_axis_limit(forum_data, plot_variable, label_lengths,
min_axis_length = 0.1, percent_addition_per_char = 0.023)
Arguments:
forum_data: The forum data for the main barplot.
plot_variable: One of (default) 'posts', 'authors', or 'views'.
label_lengths: A list containing the lengths (in characters) of each
label on the barplot.
min_axis_length: The axis length to set if all the values are set to
zero (i.e. all students have been filtered out). Default is
0.1 so that the axis is minimally affected when values are
small.
percent_addition_per_char: The percentage by which to expand the axis
per character in the label of the longest bar. Default is
0.023, i.e. 2.3
'axis_limit' The maximum axis limit for the horizontal axis in the
main barplot.
Set the horizontal axis limit of the main barplot.
Usually, the variance in bar lengths is greater than the variance
in label lengths. If this is not the case, it is possible that the
axis limit will need to be expanded further. For example, the
second-longest bar may have a label that is twice as long as the
label of the longest bar. In the future, it will be desirable to
account for these cases.
set_axis_limit(forum_data, "views", c(15,12,14,7))9.2.20 set_breakdown
9.2.20.1 Main Documentation
Determines whether the plot types breakdown will be shown.
Description:
Determines whether the plot types breakdown will be shown.
Usage:
set_breakdown(plot_variable, breakdown)
Arguments:
plot_variable: One of (default) 'posts', 'authors', or 'views'.
breakdown: One of 'TRUE' or (default) 'FALSE'.
Details:
This option only comes into play if the plot variable is 'posts'.
Value:
'TRUE' or 'FALSE'
Examples:
set_breakdown(plot_variable = "posts", breakdown = FALSE)
9.2.21 set_forum_plot_title
9.2.21.1 Main Documentation
Set the title of the main barplot, according to the relevant variable
and category.
Description:
Set the title of the main barplot, according to the relevant
variable and category.
Usage:
set_forum_plot_title(plot_variable, category)
Arguments:
plot_variable: One of (default) 'posts', 'authors', or 'views'.
Value:
'forum_plot_title' A string for the plot title.
Examples:
set_forum_plot_title("views", "Part 1")
9.2.22 set_forum_plot_ylabel
9.2.22.1 Main Documentation
Set the label of the y-axis in the main barplot.
Description:
Set the label of the y-axis in the main barplot.
Usage:
set_forum_plot_ylabel(plot_variable)
Arguments:
plot_variable: One of (default) 'posts', 'authors', or 'views'.
Value:
'forum_plot_ylabe' The label of the y-axis in the main barplot.
Examples:
set_forum_plot_ylabel("authors")
9.2.23 set_forum_threads_title
9.2.23.1 Main Documentation
Set the title of the forum threads table.
Description:
Set the title of the forum threads table.
Usage:
set_forum_threads_title(category, selected_subcategory)
Arguments:
category: The selected category.
selected_subcategory: The selected subcategory.
Value:
'forum_threads_title' A string for the title of the forum threads
table.
Examples:
set_forum_threads_title("Part 3", "All")
9.2.24 set_wordcloud_title
9.2.24.1 Main Documentation
Set the title of the wordcloud.
Description:
Set the title of the wordcloud.
Usage:
set_wordcloud_title(category, selected_subcategory)
Arguments:
category: The selected category.
selected_subcategory: The selected subcategory.
Value:
'wordcloud_title' A string for the wordcloud title.
Examples:
set_wordcloud_title("Part 3", "All")
9.2.25 specify_forum_data_selection
9.2.25.1 Main Documentation
Specify which subcategory has been selected.
Description:
Specify which subcategory has been selected.
Usage:
specify_forum_data_selection(updated_forum_data, category, selected_subcategory)
Arguments:
updated_forum_data: The dataframe containing the counts for each
(sub)category.
category: The selected category.
selected_subcategory: The selected subcategory.
Value:
'forum_w_selection' The same dataframe with a new column,
'selected'.
Examples:
specify_forum_data_selection(updated_forum_data, "Part 1", "Part 1 Video Discussion")
9.2.26 update_forum_data
9.2.26.1 Main Documentation
Update the post, view, and author counts for the selected filters.
Description:
Update the post, view, and author counts for the selected filters.
Usage:
update_forum_data(forum_posts, forum_views, forum_elements, activity_level,
gender, registration_status, category)
Arguments:
forum_posts: The forum posts dataframe passed in from the wrangling
script.
forum_views: The forum views dataframe passed in from the wrangling
script.
forum_elements: The forum elements dataframe passed in from the
wrangling script.
activity_level: The activity level of the students.
gender: The gender of the students.
registration_status: The registration status of the students.
category: The forum category.
Value:
'filtered_forum_data' A dataframe with one row per subcategory (or
category), and counts for each variable.
Examples:
update_forum_data(wrangled_forum_posts, wrangled_forum_views, filtered_forum_elements(), "over_5_hr", "other", "audit", "All")