| Type: | Package |
| Title: | Interactive Text Annotation Tool with 'shiny' GUI |
| Version: | 0.1.4 |
| Date: | 2024-10-25 |
| Description: | A comprehensive text annotation tool built with 'shiny'. Provides an interactive graphical user interface for coding text documents, managing code hierarchies, creating memos, and analyzing coding patterns. Features include code co-occurrence analysis, visualization of coding patterns, comparison of multiple coding sets, and export capabilities. Supports collaborative qualitative research through standardized annotation formats and analysis tools. |
| License: | GPL-3 |
| Encoding: | UTF-8 |
| Depends: | R (≥ 3.5.0) |
| Imports: | shiny (≥ 1.7.0), shinydashboard, shinyjs, shinyFiles, data.tree, jsonlite, DT, readtext, magrittr, tools, utils, stats, grDevices, graphics |
| Suggests: | testthat (≥ 3.0.0), knitr, rmarkdown, covr, mockery |
| URL: | https://github.com/chaoliu-cl/textAnnotatoR, http://liu-chao.site/textAnnotatoR/ |
| BugReports: | https://github.com/chaoliu-cl/textAnnotatoR/issues |
| Config/testthat/edition: | 3 |
| Language: | en-US |
| RoxygenNote: | 7.3.2 |
| VignetteBuilder: | knitr |
| NeedsCompilation: | no |
| Packaged: | 2024-11-11 19:23:25 UTC; chaoliu |
| Author: | Chao Liu  [aut,
cre, cph] |
| Maintainer: | Chao Liu <chaoliu@cedarville.edu> |
| Repository: | CRAN |
| Date/Publication: | 2024-11-12 14:40:01 UTC |
textAnnotatoR: Interactive Text Annotation Tool with 'shiny' GUI
Description
A comprehensive text annotation tool built with 'shiny'. Provides an interactive graphical user interface for coding text documents, managing code hierarchies, creating memos, and analyzing coding patterns. Features include code co-occurrence analysis, visualization of coding patterns, comparison of multiple coding sets, and export capabilities. Supports collaborative qualitative research through standardized annotation formats and analysis tools.
Author(s)
Maintainer: Chao Liu chaoliu@cedarville.edu (ORCID) [copyright holder]
See Also
Useful links:
Report bugs at https://github.com/chaoliu-cl/textAnnotatoR/issues
JavaScript code for handling text selection and UI interactions
Description
This internal JavaScript code provides functionality for text selection, popup menus, and interactive UI elements in the text annotation interface. It manages mouse events for text selection, highlighting, and code application.
Format
A character string containing JavaScript code
Details
The JavaScript code implements the following functionality:
Creation and management of popup menus for code operations
Text selection handling with mouse events
Highlighting of selected text
Communication with Shiny server through custom message handlers
Event handling for code replacement, renaming, and deletion
Event Handlers
Text selection events (mousedown, mousemove, mouseup)
Popup menu events for code operations
Custom Shiny message handlers for selection state
Note
This is an internal function used by the textAnnotatoR package and should not be called directly by users.
Add action to history
Description
Add action to history
Usage
add_action(rv, action)
Arguments
rv |
Reactive values object |
action |
Action to add |
Add code to theme in hierarchy
Description
Adds a new code to a specific theme in the code hierarchy. The code can be added to the root level or nested within existing themes.
Usage
add_code_to_theme(node, code_name, theme_path, description = "")
Arguments
node |
Root node of the hierarchy tree |
code_name |
Character string specifying the name of the code to add |
theme_path |
Character vector specifying the path to the target theme |
description |
Optional character string providing a description of the code |
Value
Updated node with new code added
Add theme to code hierarchy
Description
Adds a new theme to the code hierarchy tree. Themes can be used to organize and group related codes in a hierarchical structure.
Usage
add_theme(node, theme_name, description = "")
Arguments
node |
Root node of the hierarchy tree |
theme_name |
Character string specifying the name of the new theme |
description |
Optional character string providing a description of the theme |
Value
Updated node with new theme added
Analyze code co-occurrence patterns
Description
Analyzes how different codes co-occur within the annotated text by examining overlapping annotations and calculating various metrics of co-occurrence strength.
Usage
analyze_co_occurrences(annotations)
Arguments
annotations |
A data frame containing text annotations with columns:
|
Value
A list containing co-occurrence analysis results:
combinations: list containing frequency table of code co-occurrences
characteristics: list with average overlap length and total overlap count
Analyze combinations of code pairs
Description
Analyzes the frequency of different code combinations by counting how often different pairs of codes appear together in overlapping annotations.
Usage
analyze_code_combinations(overlaps)
Arguments
overlaps |
List of overlap information, where each element contains:
|
Details
The function processes overlapping code pairs and creates a frequency table of their combinations. Code pairs are sorted alphabetically before counting to ensure consistent ordering (e.g., "A-B" and "B-A" are counted as the same combination). Returns an empty list if no overlaps are provided.
Value
List containing:
frequencies: Table object containing counts of each code pair combination, where row names are formatted as "code1-code2" with codes sorted alphabetically
Analyze context around code applications
Description
Examines the surrounding context where codes are applied by looking at preceding and following annotations to understand code relationships.
Usage
analyze_code_context(code_anns, all_anns)
Arguments
code_anns |
Data frame containing annotations for specific code:
|
all_anns |
Data frame containing all annotations in the text |
Value
List of contexts for each code instance:
before: Preceding annotation if exists
after: Following annotation if exists
Analyze coding density across text
Description
Analyzes the density of code applications across the text by calculating overall density metrics and identifying regions of dense coding activity.
Usage
analyze_code_distribution(annotations)
Arguments
annotations |
Data frame containing annotations with columns:
|
Value
List containing:
overall_density: Numeric value representing the proportion of text covered by codes
dense_regions: List of vector pairs indicating start and end positions of dense regions
Analyze code application patterns
Description
Analyzes patterns in how codes are applied in the annotations.
Usage
analyze_code_patterns(annotations)
Arguments
annotations |
Data frame containing code annotations with columns:
|
Value
List containing:
patterns: List of code patterns
summary: Summary statistics
Analyze coding density in text
Description
Calculates metrics related to coding density in the text, including overall density and identification of densely coded regions.
Usage
analyze_coding_density(annotations)
Arguments
annotations |
Data frame containing annotations with columns:
|
Details
Density is calculated as the ratio of coded text to total text length. Dense regions are identified where consecutive annotations are close together (within 20 characters by default).
Value
List containing:
overall_density: Numeric value representing proportion of text covered by codes
dense_regions: List of vectors, each containing start and end positions of identified dense coding regions
Analyze coverage patterns in annotations
Description
Analyzes how codes are distributed throughout the text, including clustering patterns and coding density.
Usage
analyze_coverage(annotations)
Arguments
annotations |
Data frame containing text annotations with columns:
|
Value
List containing:
clusters: List of annotation clusters
density: List containing overall density metrics
distribution: List containing code frequencies and positions
Analyze memo usage patterns
Description
Examines how memos are used with codes by analyzing memo frequency, content, and patterns in memo application across code instances.
Usage
analyze_memo_patterns(code_anns)
Arguments
code_anns |
Data frame containing code annotations with columns:
|
Value
List containing:
memo_frequency: Proportion of annotations with memos
has_memos: Logical vector indicating memo presence
Analyze characteristics of code overlaps
Description
Analyzes the characteristics of overlapping code applications by calculating various metrics about overlap patterns.
Usage
analyze_overlap_characteristics(overlaps)
Arguments
overlaps |
List of overlap information, where each element contains:
|
Details
Calculates metrics about code overlaps including the average length of overlapping regions and the total number of overlaps. Returns empty list for empty input.
Value
List containing:
avg_length: Numeric value of average overlap length
total_overlaps: Integer count of total overlapping instances
Analyze sequences and transitions between codes
Description
Analyzes how codes are sequenced in the text by examining transitions between consecutive codes and identifying repeated patterns.
Usage
analyze_sequences(annotations)
Arguments
annotations |
Data frame of text annotations with columns:
|
Value
List containing:
transitions: List of transitions between consecutive codes
patterns: List of identified repeated code sequences
Text Annotation GUI
Description
Launch an interactive Shiny application for text annotation and analysis. The GUI provides tools for importing text, applying codes, creating memos, and analyzing annotations through various visualizations.
Usage
annotate_gui()
Details
Interactive Text Annotation Interface
The annotation interface includes the following features:
Text import and display
Code application and management
Memo creation and linking
Project management (save/load)
Annotation analysis tools
Export capabilities
Value
Launches a Shiny application in the default web browser
Note
This package provides functionality for users to interactively save files through the Shiny interface. All file operations are explicitly initiated by users through file dialogs, and no files are written automatically to the user's system without their direct action and consent.
Examples
if(interactive()) {
annotate_gui()
}
Apply or reverse an action
Description
Applies or reverses an action in the undo/redo system. Handles different types of actions including adding/removing annotations and merging/unmerging codes.
Applies or reverses an action in the undo/redo system. Handles different types of actions including adding/removing annotations and merging/unmerging codes.
Usage
apply_action(rv, action, reverse = FALSE)
apply_action(rv, action, reverse = FALSE)
Arguments
rv |
ReactiveValues object containing application state |
action |
List containing action information |
reverse |
Logical indicating whether to reverse the action |
Value
Invisible rv (ReactiveValues object)
Invisible rv (ReactiveValues object)
Calculate code co-occurrences in annotations
Description
Analyzes text annotations to identify and count instances where different codes overlap or co-occur in the same text regions. Handles edge cases and provides error-safe operation.
Usage
calculate_co_occurrences(annotations)
Arguments
annotations |
Data frame containing annotations with columns:
|
Details
Co-occurrences are identified by finding overlapping text regions between different code annotations. The function sorts annotations by position and checks for overlaps between each pair of annotations.
Value
Table object containing frequencies of code pairs that co-occur, with code pair names as "code1 & code2"
Calculate hierarchy statistics
Description
Calculates various statistics about the code hierarchy including the total number of themes and codes, maximum depth, and distribution of codes across themes.
Usage
calculate_hierarchy_stats(node)
Arguments
node |
Root node of the hierarchy tree |
Value
A list containing hierarchy statistics:
total_themes: Total number of themes in the hierarchy
total_codes: Total number of codes in the hierarchy
max_depth: Maximum depth of the hierarchy tree
codes_per_theme: List showing number of codes in each theme
average_codes_per_theme: Average number of codes per theme
Calculate transitions between consecutive codes
Description
Analyzes the sequence of code applications to identify transitions between consecutive codes in the text. Creates a list of code pairs representing each transition from one code to another.
Usage
calculate_transitions(annotations)
Arguments
annotations |
Data frame containing annotations with columns:
|
Details
Transitions are identified by sorting annotations by position and then analyzing consecutive pairs of codes. The function handles edge cases and provides error-safe operation.
Value
List where each element is a named vector containing:
from: Character string of the source code
to: Character string of the target code
Clean directory paths for export
Description
Sanitizes directory paths for file export operations. This function ensures that export paths are valid, accessible, and secure before files are written. It handles path normalization and security checks for export operations.
Usage
clean_export_path(dir_path, create = FALSE)
Arguments
dir_path |
Character string containing the directory path to clean |
create |
Logical indicating whether to create the directory if it doesn't exist |
Value
Cleaned and validated directory path
Clean project path
Description
Ensures project paths are valid and secure by removing potentially harmful characters and preventing directory traversal attempts. This function sanitizes file paths to prevent security issues and ensure consistent file naming across different operating systems.
Usage
clean_project_path(path)
Arguments
path |
Character string containing the project path to be cleaned |
Value
Sanitized path string that is safe to use for file operations
Compare code co-occurrence patterns between coders
Description
Analyzes how different coders overlap in their code applications by comparing the frequency and patterns of code co-occurrences.
Usage
compare_co_occurrences(overlaps_list)
Arguments
overlaps_list |
List of overlap patterns from different coders, where each entry contains:
|
Value
List containing:
overlap_variation: Numeric value indicating range of overlap counts
summary: Character string describing variation in overlapping pairs
Compare code application patterns between coders
Description
Analyzes and compares how different coders apply codes by examining code segment lengths and memo usage patterns across coding strategies.
Usage
compare_code_patterns(patterns_list)
Arguments
patterns_list |
List of coding patterns from different coders, where each pattern contains:
|
Value
List containing:
length_variation: Character string describing variation in code segment lengths
memo_usage_summary: Character string describing differences in memo usage
Compare code usage between coders
Description
Compares how different coders use codes by analyzing shared codes and their usage patterns across coding strategies.
Usage
compare_codes(coding_strategies)
Arguments
coding_strategies |
List of coding strategies, where each strategy contains code frequency information |
Value
List containing:
shared_codes: Character vector of codes used across strategies
usage_matrix: Matrix showing code usage across strategies
Compare coverage patterns between coding strategies
Description
Analyzes and compares the coverage patterns between different coding strategies, including total codes used and unique code counts.
Usage
compare_coverage(coding_strategies)
Arguments
coding_strategies |
List of coding strategies, where each strategy contains:
|
Value
List containing:
total_codes_range: Numeric vector with min and max total codes
unique_codes_range: Numeric vector with min and max unique codes
Compare overlap patterns between coders
Description
Analyzes how different coders overlap in their code applications by comparing overlap patterns and frequencies across coding strategies.
Usage
compare_overlaps(coding_strategies)
Arguments
coding_strategies |
List of coding strategies, where each strategy contains overlap information |
Value
List containing:
total_overlaps_range: Range of total overlaps across strategies
unique_pairs_range: Range of unique code pairs across strategies
Compare coding patterns between different coders
Description
Analyzes and compares coding patterns between different coders by examining various aspects including coverage, code application patterns, combinations, and sequences.
Usage
compare_patterns(coding_strategies)
Arguments
coding_strategies |
List of coding strategies, where each strategy contains:
|
Details
The function performs multiple comparisons with error handling for each aspect of coding patterns. Returns descriptive messages when analysis cannot be performed due to insufficient data.
Value
List containing comparison results:
coverage_differences: Analysis of coding density variations
code_differences: Analysis of code application differences
combination_differences: Analysis of code combination patterns
sequence_differences: Analysis of code sequence patterns
Compare code sequence patterns between coders
Description
Analyzes how different coders sequence their codes by comparing the patterns and frequency of code transitions.
Usage
compare_sequences(sequences_list)
Arguments
sequences_list |
List of sequence patterns from different coders, where each entry contains:
|
Value
List containing:
sequence_variation: Numeric value indicating range of transition counts
summary: Character string describing variation in code transitions
Concatenate memo texts
Description
Combines existing and new memo texts with proper separators, handling empty memos appropriately.
Combines existing and new memo texts with proper separators, handling empty memos appropriately.
Usage
concatenate_memos(existing_memo, new_memo)
concatenate_memos(existing_memo, new_memo)
Arguments
existing_memo |
Character string containing current memo text |
new_memo |
Character string containing memo text to append |
Value
Character string of combined memo text
Character string of combined memo text
Create and manage undo/redo action
Description
Creates an action object for the undo/redo system, containing information about the type of action, the data involved, and how to reverse the action.
Creates an action object for the undo/redo system, containing information about the type of action, the data involved, and how to reverse the action.
Usage
create_action(type, data, reverse_data = NULL)
create_action(type, data, reverse_data = NULL)
Arguments
type |
Character string specifying the type of action |
data |
List containing the action data |
reverse_data |
Optional list containing data for reversing the action |
Value
List containing:
type: Action type identifier
data: Action data
reverse_data: Data for reversing the action
timestamp: Time the action was created
List containing:
type: Action type identifier
data: Action data
reverse_data: Data for reversing the action
timestamp: Time the action was created
Create backup directory
Description
Creates and manages a backup directory for project files. This function ensures that automatic backups have a designated storage location that is properly managed and cleaned up when needed.
Usage
create_backup_dir(max_backups = 3)
Arguments
max_backups |
Integer specifying maximum number of backups to keep |
Value
Character string containing the path to the backup directory
Initialize new project
Description
Creates new project by resetting all reactive values to defaults and clearing UI elements.
Creates new project by resetting all reactive values to defaults and clearing UI elements.
Usage
create_new_project(rv, session)
create_new_project(rv, session)
Arguments
rv |
ReactiveValues object to reset containing:
|
session |
Shiny session object |
Value
Invisible NULL, called for side effect
Invisible NULL, called for side effect
Create plain text version of annotations
Description
Converts annotated text to plain text format with code markers. Each annotation is represented as a code identifier and annotated text wrapped in square brackets. Multiple annotations are preserved and shown in order of appearance in the text.
Converts annotated text to plain text format with code markers. Each annotation is represented as a code identifier and annotated text wrapped in square brackets. Multiple annotations are preserved and shown in order of appearance in the text.
Usage
create_plain_text_annotations(text, annotations)
create_plain_text_annotations(text, annotations)
Arguments
text |
Character string containing the original text |
annotations |
Data frame of annotations with columns:
|
Value
Character string containing formatted text with code markers
Character string containing formatted text with code markers
Export code hierarchy to JSON format
Description
Converts the code hierarchy tree structure into a JSON string representation that can be saved or transmitted while preserving all node properties and relationships.
Usage
export_hierarchy(node)
Arguments
node |
Root node of the hierarchy tree |
Value
JSON string representation of the hierarchy
Find clusters of annotations in text
Description
Identifies clusters of annotations that are close together in the text, helping to identify dense coding regions.
Usage
find_annotation_clusters(annotations)
Arguments
annotations |
Data frame containing sorted text annotations with columns:
|
Value
List of annotation clusters, where each cluster contains annotations that are within a specified distance of each other
Find transitions between codes
Description
Identifies and analyzes transitions between consecutive code applications to understand coding sequence patterns.
Usage
find_code_transitions(annotations)
Arguments
annotations |
Data frame of sorted annotations with columns:
|
Value
List of code transitions, each containing:
from: Source code
to: Target code
Find node by name in a tree structure
Description
Recursively searches through a tree structure to find a node with a specific name. The search is performed depth-first and returns the first matching node found.
Usage
find_node_by_name(node, target_name)
Arguments
node |
Node object representing the current position in the tree. Should have:
|
target_name |
Character string specifying the name to search for |
Details
The function handles NULL inputs safely and performs a recursive depth-first search through the tree structure. It checks node names and recursively searches through child nodes.
Value
Node object if found, NULL otherwise
Find overlapping code annotations
Description
Identifies pairs of annotations that overlap in the text and returns their intersection points and associated codes.
Usage
find_overlapping_codes(annotations)
Arguments
annotations |
A data frame containing text annotations with columns:
|
Value
A list of overlapping code pairs, each containing:
code1: first code in the overlap
code2: second code in the overlap
overlap_start: starting position of overlap
overlap_end: ending position of overlap
Find repeated patterns in code sequences
Description
Identifies repeating patterns of 2-3 codes in sequence to uncover recurring coding structures.
Usage
find_repeated_sequences(annotations)
Arguments
annotations |
Data frame of sorted annotations with columns:
|
Value
Named list of pattern frequencies where:
names: Code patterns (e.g. "code1-code2")
values: Number of occurrences
Format code difference analysis results
Description
Formats the results of code difference analysis into a human-readable string, handling both character and list inputs appropriately.
Usage
format_code_differences(differences)
Arguments
differences |
Either a character string containing direct analysis results or a list containing:
|
Value
Character string containing formatted code analysis results
Format coverage difference analysis results
Description
Formats the results of coverage difference analysis into a human-readable string, handling both character and list inputs appropriately.
Usage
format_coverage_differences(differences)
Arguments
differences |
Either a character string containing direct analysis results or a list containing:
|
Value
Character string containing formatted coverage analysis results
Format overlap difference analysis results
Description
Formats the results of overlap difference analysis into a human-readable string, processing both character and complex input types.
Usage
format_overlap_differences(differences)
Arguments
differences |
Either a character string containing direct analysis results or a complex analysis object |
Value
Character string containing formatted overlap analysis results
Format sequence difference analysis results
Description
Formats the results of sequence difference analysis into a human-readable string, processing both character and complex input types.
Usage
format_sequence_differences(differences)
Arguments
differences |
Either a character string containing direct analysis results or a complex analysis object |
Value
Character string containing formatted sequence analysis results
Generate code co-occurrence statistics and visualization
Description
Performs a comprehensive analysis of code co-occurrences in the text, including calculation of various similarity metrics and generation of network and heatmap visualizations.
Usage
generate_code_co_occurrence_analysis(annotations)
Arguments
annotations |
Data frame containing text annotations with columns:
|
Value
List containing:
co_occurrence: Matrix of raw co-occurrence counts
jaccard_similarity: Matrix of Jaccard similarity coefficients
phi_coefficient: Matrix of Phi coefficients
network_plot: Network visualization of code relationships
heatmap_plot: Heatmap visualization of code co-occurrences
summary: List of summary statistics
Generate code frequency visualization
Description
Creates a barplot visualization showing the frequency of each code in the annotations. The plot displays codes on the x-axis and their frequency counts on the y-axis.
Usage
generate_code_frequency_plot(annotations)
Arguments
annotations |
Data frame containing text annotations with columns:
|
Value
A recordedplot object containing the code frequency visualization
Compare coding patterns between different documents or coders
Description
Performs a comprehensive comparison of coding patterns between different sets of annotations, analyzing differences in coverage, code application, overlaps, and code sequences.
Usage
generate_comparison_analysis(annotations_list)
Arguments
annotations_list |
A list of data frames, where each data frame contains annotations with columns:
|
Value
A list containing comparison results and analysis:
coding_strategies: list of analyzed coding patterns for each input
comparison: list of comparative analyses between coding patterns
Generate comparison visualizations
Description
Creates a set of visualizations for comparing coding patterns between different coders, including distribution comparisons, overlap patterns, and sequence patterns.
Usage
generate_comparison_plots(comparison_results)
Arguments
comparison_results |
List containing results from generate_comparison_analysis:
|
Value
List containing plot objects:
distribution: Plot comparing code distribution patterns
overlap: Plot showing code overlap patterns
sequence: Plot displaying code sequence patterns
Generate text summary statistics
Description
Calculates basic summary statistics for the annotated text, including word counts, character counts, annotation counts, and unique code counts.
Usage
generate_text_summary(text, annotations)
Arguments
text |
Character string containing the text being analyzed |
annotations |
Data frame of annotations with columns:
|
Value
A list containing summary statistics:
total_words: total number of words in the text
total_characters: total number of characters
total_sentences: number of sentences (approximated by punctuation)
total_paragraphs: number of paragraphs (non-empty lines)
total_annotations: number of annotations
unique_codes: number of unique codes used
Generate word cloud visualization
Description
Creates a simple word cloud visualization from the input text, showing the most frequent words with size proportional to their frequency.
Usage
generate_word_cloud(text)
Arguments
text |
Character string containing the text to visualize |
Value
A plot object containing the word cloud visualization
Get available storage volumes on Windows
Description
Creates a closure that returns a named vector of available Windows drive letters and their corresponding paths. Checks for the existence of drives from A: to Z: (excluding C: which is handled separately).
Usage
getVolumes()
Value
Function that returns named character vector of available drives
Get all code names from hierarchy
Description
Recursively extracts all code names from a code hierarchy tree structure, traversing through all nodes and collecting their names.
Usage
get_code_names(node)
Arguments
node |
Root node of the code hierarchy (data.tree Node object) |
Value
Character vector containing all code names in the hierarchy
Get export directory
Description
Returns the path to the exports directory, creating it if necessary. This directory is used for storing exported annotation data, visualizations, and analysis results. The function ensures the directory exists and is accessible before returning its path.
Usage
get_export_dir()
Value
Character string containing the path to the exports directory
Get project directory path
Description
Retrieves or creates the project directory path where all project files will be stored. Creates the directory if it doesn't exist.
Retrieves or creates the project directory path where all project files will be stored. Creates the directory if it doesn't exist.
Retrieves or creates the project directory path where all project files will be stored. Creates the directory if it doesn't exist.
Usage
get_project_dir()
get_project_dir()
get_project_dir()
Value
Character string containing the project directory path, or NULL if creation fails
Character string containing the project directory path, or NULL if creation fails
Character string containing the project directory path, or NULL if creation fails
Null coalescing operator
Description
Provides null coalescing functionality, returning the first non-NULL argument
Provides null coalescing functionality, returning the first non-NULL argument
Usage
a %||% b
a %||% b
Arguments
a |
First value to check |
b |
Second value (default) to use if first is NULL |
Details
\
\
Value
Returns a if not NULL, otherwise returns b
Returns a if not NULL, otherwise returns b
Handle directory creation confirmation
Description
Creates the data directory after receiving user confirmation
Usage
handle_dir_confirmation(input, rv, session)
Arguments
input |
Shiny input object |
rv |
ReactiveValues object containing application state |
session |
Shiny session object |
Handle errors with custom messages
Description
Provides error handling with customizable success, error, and completion messages. Wraps expressions in a tryCatch block and displays appropriate notifications.
Provides error handling with customizable success, error, and completion messages. Wraps expressions in a tryCatch block and displays appropriate notifications.
Provides error handling with customizable success, error, and completion messages. Wraps expressions in a tryCatch block and displays appropriate notifications.
Usage
handle_error(expr, success_msg = NULL, error_msg = NULL, finally_msg = NULL)
handle_error(expr, success_msg = NULL, error_msg = NULL, finally_msg = NULL)
handle_error(expr, success_msg = NULL, error_msg = NULL, finally_msg = NULL)
Arguments
expr |
Expression to evaluate |
success_msg |
Optional character string for success notification |
error_msg |
Optional character string for error notification |
finally_msg |
Optional character string for completion notification |
Value
Result of the expression or NULL if error occurs
Result of the expression or NULL if error occurs
Result of the expression or NULL if error occurs
Import code hierarchy from JSON format
Description
Reconstructs a code hierarchy tree structure from its JSON string representation, restoring all node properties and relationships.
Usage
import_hierarchy(json_string)
Arguments
json_string |
JSON string representation of the hierarchy |
Value
Node object representing the reconstructed hierarchy
Initialize data directory with user confirmation
Description
Creates and initializes the package data directory after obtaining explicit user confirmation. Uses R_user_dir to create directory in user's home space only after approval.
Usage
init_data_dir(session)
Arguments
session |
Shiny session object for displaying confirmation dialog |
Value
Character string containing the path to the data directory, or NULL if declined
Check if one node is an ancestor of another
Description
Helper function to check if a node is an ancestor of another node in the code hierarchy, preventing circular references when moving items.
Usage
is_ancestor(potential_ancestor, node)
Arguments
potential_ancestor |
Node object to check as potential ancestor |
node |
Node object to check ancestry against |
Value
Logical indicating whether potential_ancestor is an ancestor of node
Display interactive project load dialog
Description
Shows modal dialog for loading project with file selection functionality.
Shows modal dialog for loading project with file selection functionality.
Usage
load_project_interactive(rv, input, session, roots)
load_project_interactive(rv, input, session, roots)
Arguments
rv |
ReactiveValues object for project state |
input |
Shiny input values |
session |
Shiny session object |
roots |
List of root directories for file selection |
Value
Invisible NULL, called for side effect
Invisible NULL, called for side effect
Load project state from file
Description
Loads a previously saved project state from an RDS file. Performs version checking and data structure validation during the loading process.
Loads a previously saved project state from an RDS file. Performs version checking and data structure validation during the loading process.
Usage
load_project_state(filename)
load_project_state(filename)
Arguments
filename |
Character string specifying the filename to load |
Value
List containing the loaded project state, or NULL if loading fails
List containing the loaded project state, or NULL if loading fails
Load selected project state
Description
Loads a previously saved project state and updates all reactive values.
Usage
load_selected_project(rv, input, session, project_name)
Arguments
rv |
Reactive values object to update |
input |
Shiny input object |
session |
The current Shiny session |
Value
Invisible NULL
Move item in code hierarchy
Description
Moves a code or theme to a new location in the hierarchy while preserving its properties and child nodes. Checks for circular references and maintains the integrity of the hierarchy structure.
Usage
move_item(node, item_path, new_parent_path)
Arguments
node |
Root node of the hierarchy tree |
item_path |
Character vector specifying the current path to the item |
new_parent_path |
Character vector specifying the path to the new parent |
Value
Updated node hierarchy with item moved to new location
Plot code distribution visualization
Description
Creates a barplot visualization showing the distribution of codes in the annotations. The plot includes rotated labels for better readability and handles empty or NULL input data gracefully.
Usage
plot_code_distribution(distribution, main = "", ...)
Arguments
distribution |
List containing code distribution information:
|
main |
Character string specifying the plot title |
... |
Additional arguments passed to barplot() |
Value
Invisible NULL, called for side effect of creating plot
Plot code overlap patterns
Description
Creates a barplot visualization of code overlap patterns, showing the frequency of different code co-occurrences with rotated labels for better readability.
Usage
plot_overlap_patterns(overlaps, main = "", ...)
Arguments
overlaps |
List containing overlap information:
|
main |
Character string for plot title |
... |
Additional arguments passed to barplot() |
Value
Invisible NULL, called for side effect of creating plot
Plot code sequence patterns
Description
Creates a barplot visualization of code sequence patterns, showing the frequency of different code transitions with rotated labels for better readability.
Usage
plot_sequence_patterns(sequences, main = "", ...)
Arguments
sequences |
List containing sequence information:
|
main |
Character string for plot title |
... |
Additional arguments passed to barplot() |
Value
Invisible NULL, called for side effect of creating plot
Process comparison file
Description
Processes uploaded comparison files, handling different file formats (CSV, JSON) and ensuring proper data structure and types for comparison analysis.
Usage
process_comparison_file(filepath)
Arguments
filepath |
Character string specifying the path to the comparison file |
Value
Data frame containing processed annotations with columns:
start: numeric, starting position of annotation
end: numeric, ending position of annotation
code: character, code applied to the annotation
Restore a node and its children in the hierarchy
Description
Helper function to recursively restore a node and all its children when moving items in the code hierarchy.
Usage
restore_node(parent, node_data)
Arguments
parent |
Parent Node object where the node will be restored |
node_data |
List containing node data to restore:
|
Value
New Node object with restored data and children
Display interactive dialog for saving annotated text
Description
Creates and displays a modal dialog that allows users to save their annotated text in either HTML or plain text format. Provides options for filename and directory selection.
Usage
save_annotated_text_interactive(rv, input, session, volumes)
Arguments
rv |
ReactiveValues object containing the application state |
input |
Shiny input object |
session |
Shiny session object |
volumes |
List of available storage volumes for directory selection |
Value
Invisible NULL, called for side effects
Save annotated text as HTML document
Description
Creates an HTML document containing the annotated text with proper styling for code highlights and formatting.
Creates an HTML document containing the annotated text with proper styling for code highlights and formatting.
Usage
save_as_html(filename, rv)
save_as_html(filename, rv)
Arguments
filename |
Character string specifying output file path |
rv |
ReactiveValues object containing:
|
Value
Invisible NULL, called for side effect
Invisible NULL, called for side effect
Save annotated text as plain text
Description
Creates a plain text file containing the annotated text with code markers.
Creates a plain text file containing the annotated text with code markers.
Usage
save_as_text(filename, rv)
save_as_text(filename, rv)
Arguments
filename |
Character string specifying output file path |
rv |
ReactiveValues object containing:
|
Value
Invisible NULL, called for side effect
Invisible NULL, called for side effect
Display interactive project save dialog
Description
Shows modal dialog for saving project with directory selection and project name input.
Shows modal dialog for saving project with directory selection and project name input.
Usage
save_project_interactive(rv, input, session, volumes)
save_project_interactive(rv, input, session, volumes)
Arguments
rv |
ReactiveValues object containing project state |
input |
Shiny input values |
session |
Shiny session object |
volumes |
List of available storage volumes |
Value
Invisible NULL, called for side effect
Invisible NULL, called for side effect
Save and manage project state
Description
Saves the current state of a text annotation project, including annotations, codes, and memos. Creates necessary directories and handles file operations safely.
Saves the current project state including text, annotations, codes, code tree, and other metadata to an RDS file. Creates the projects directory if it doesn't exist.
Usage
save_project_state(state, filename)
save_project_state(state, filename)
Arguments
state |
List containing project state elements:
|
filename |
Character string specifying the filename for saving |
Value
Invisible NULL, called for side effect of saving project state
Invisible NULL. Called for side effect of saving project state.
Display interactive dialog for saving annotation records
Description
Creates and displays a modal dialog that allows users to save their annotation records in either CSV or JSON format. Provides options for filename and directory selection.
Usage
save_records_interactive(rv, input, session, volumes)
Arguments
rv |
ReactiveValues object containing the application state |
input |
Shiny input object |
session |
Shiny session object |
volumes |
List of available storage volumes for directory selection |
Value
Invisible NULL, called for side effects
Text Annotation Tool for R
Description
A Shiny application for interactive text annotation and analysis
Provides an interactive graphical user interface for qualitative text analysis, allowing users to annotate text, manage codes, create memos, and visualize coding patterns.
Details
The package includes tools for:
Text annotation and coding
Code management and organization
Memo creation and linking
Project management
Visualization of coding patterns
Export of annotations and analyses
Dependencies
This package requires the following packages:
shiny
data.tree
jsonlite
shinydashboard
DT
readtext
magrittr
Note
This package provides functionality for users to interactively save files through the Shiny interface. All file operations are explicitly initiated by users through file dialogs, and no files are written automatically to the user's system without their direct action and consent.
Author(s)
Chao Liu
See Also
Useful links:
Report bugs at https://github.com/chaoliu-cl/textAnnotatoR/issues
Update text display with annotations
Description
Creates an HTML representation of the text with annotations, highlighting codes with their assigned colors.
Usage
update_text_display(rv)
Arguments
rv |
Reactive values object containing text and annotations |
Value
HTML string containing the formatted text with annotations
Validate directory access
Description
Checks if a directory exists and is accessible for reading and writing. This function performs comprehensive checks to ensure the directory can be used for file operations.
Usage
validate_directory(dir_path)
Arguments
dir_path |
Character string containing the directory path to validate |
Value
Logical indicating whether the directory is valid and accessible
Generate visual representation of code hierarchy
Description
Creates an HTML tree visualization of the code hierarchy with proper indentation, icons, and interactive elements.
Usage
visualize_hierarchy(node)
Arguments
node |
Root node of hierarchy tree with attributes:
|
Value
Character string containing HTML markup for tree visualization