README.md

In ConverTier2: Conversion of Tiered Assessment Responses to Polytomous Scores

ConverTier2

Conversion of Tiered Assessment Responses to Polytomous Scores

Overview

ConverTier2 is an R package for converting binary responses from tiered assessment instruments into polytomous item scores based on user-defined scoring rules.

The package is designed for tiered assessment data in which each item consists of multiple binary response components, such as a response tier and a reasoning or justification tier. ConverTier2 combines the binary responses within each item and assigns an item score according to predefined scoring rules.

The package provides functions for scoring-rule parsing, data validation, tiered response conversion, Excel file processing, and a Shiny-based graphical user interface.

Features

ConverTier2 provides the following main features:

• Define scoring rules using simple text-based syntax.
• Convert binary tier responses into polytomous item scores.
• Validate input data before conversion.
• Process tiered assessment data directly from Excel files.
• Export converted scores to Excel.
• Use a graphical Shiny application for users who prefer an interactive interface.

Installation

ConverTier2 can currently be installed from the local package source.

# Install the package from the source directory
devtools::install("path/to/ConverTier2")

After installation, load the package with:

library(ConverTier2)

Usage

1. Define scoring rules

Scoring rules are specified as a text string, with one rule per line.

For example, for a two-tier assessment:

rules <- parse_rules("
11 = 4
10 = 3
01 = 2
00 = 1
")

The resulting object is a named numeric vector:

rules

Each binary response pattern is associated with a corresponding polytomous score.

For example:

| Response Pattern | Score | |:---:|---:| | 11 | 4 | | 10 | 3 | | 01 | 2 | | 00 | 1 |

2. Convert tiered responses

Suppose the data contain two binary tiers for each item:

data <- data.frame(
  Jwb_1 = c(1, 1, 0),
  Als_1 = c(1, 0, 0),
  Jwb_2 = c(0, 1, 1),
  Als_2 = c(1, 0, 1)
)

The data can be converted using:

scores <- convert_tier(
  data = data,
  rules = rules,
  n_tier = 2
)

scores

The resulting data frame contains one score for each item:

  Score_Item_1 Score_Item_2
1            4            2
2            3            4
3            1            2

3. Validate assessment data

Before conversion, the input data can be checked using:

validate_data(
  data = data,
  n_tier = 2
)

The validation checks include:

• Input must be a data frame.
• The number of tiers must be a positive integer.
• The number of columns must be divisible by the number of tiers.
• The data must not contain missing values.
• Responses must contain only binary values (0 or 1).

If the data are valid, the function returns TRUE invisibly.

4. Convert an Excel file

ConverTier2 can also process an Excel file directly:

scores <- convert_file(
  input = "data/input.xlsx",
  output = "data/scored_output.xlsx",
  rules = rules,
  n_tier = 2
)

The function:

1. Reads the Excel file.
2. Validates the input data.
3. Converts the tiered responses into item scores.
4. Optionally writes the results to a new Excel file.

If no output path is specified, the converted scores are returned without creating a new file:

scores <- convert_file(
  input = "data/input.xlsx",
  rules = rules,
  n_tier = 2
)

Input Data Format

The input data should contain binary responses (0 and 1) arranged sequentially by item and tier.

For example, a two-tier instrument with two items can be structured as:

| Jwb_1 | Als_1 | Jwb_2 | Als_2 | |---:|---:|---:|---:| | 1 | 1 | 0 | 1 | | 1 | 0 | 1 | 0 | | 0 | 0 | 1 | 1 |

The columns are interpreted sequentially:

Item 1 → Jwb_1 + Als_1
Item 2 → Jwb_2 + Als_2

For an assessment with n tiers, the columns should follow the same sequential structure:

Item 1 → Tier 1 + Tier 2 + ... + Tier n
Item 2 → Tier 1 + Tier 2 + ... + Tier n
...

Scoring Rules

The scoring rules determine how combinations of binary tier responses are converted into polytomous scores.

For a two-tier assessment:

11 = 4
10 = 3
01 = 2
00 = 1

For a three-tier assessment, for example:

111 = 4
110 = 3
101 = 3
100 = 2
011 = 2
010 = 2
001 = 1
000 = 1

The scoring rules are fully user-defined. Therefore, researchers can adapt the scoring scheme to the characteristics and theoretical framework of their assessment instrument.

Shiny Application

ConverTier2 also includes a graphical user interface built with Shiny.

The application provides an interactive workflow for:

1. Selecting the number of tiers.
2. Defining scoring rules.
3. Uploading an Excel dataset.
4. Validating and converting the data.
5. Previewing the resulting item scores.
6. Downloading the converted results as an Excel file.

The Shiny application is intended to make ConverTier2 accessible to users who do not want to work directly with R functions.

The application can be launched from the installed package using the package's Shiny application interface.

Output

The conversion produces a data frame in which each item is represented by a polytomous score.

For example:

Score_Item_1
Score_Item_2
Score_Item_3
...

When the Excel workflow is used, the resulting scores can be exported to an Excel file for further analysis.

The resulting polytomous scores can subsequently be used in statistical and psychometric analyses, depending on the design and measurement model of the assessment.

Main Functions

| Function | Purpose | |---|---| | parse_rules() | Parses text-based scoring rules into a named numeric vector. | | validate_data() | Validates binary tiered assessment data. | | convert_tier() | Converts tiered binary responses into item scores. | | convert_file() | Reads, validates, converts, and optionally exports Excel data. |

Authors

Bhilan Rhiyu Antama Maintainer and creator

Heni Setiyaningsih Author

Edi Istiyono Author

License

ConverTier2 is released under the MIT License.

See the LICENSE file for the complete license text.

ConverTier2 documentation built on Nov. 12, 2026, 1:07 a.m.