Rfactor

Rfactor is an R package for calculating rainfall erosivity from timestamped precipitation records.

The package identifies independent rainfall events, calculates maximum rolling rainfall intensities, rainfall kinetic energy, and event EI30 erosivity, aggregates contributing event EI30 to monthly or yearly calendar totals, and calculates multi-year mean rainfall erosivity from those period totals.

These quantities support calculation of the rainfall-runoff erosivity factor (R-factor) used by USLE and RUSLE.

Rfactor focuses on rainfall erosivity calculations. It does not calculate the other USLE/RUSLE factors and does not perform spatial interpolation or mapping.

Main functions

The public workflow is built around:

• rf_settings() — configure rainfall-event separation, omission criteria, intensity durations, and kinetic-energy equation;
• rf_read_rainfall() — read timestamped precipitation data;
• rf_validate_rainfall() — validate rainfall structure and temporal alignment;
• rf_identify_storms() — identify independent rainfall events;
• rf_max_intensity() — calculate maximum rolling rainfall intensity;
• rf_calculate_energy() — calculate rainfall kinetic energy;
• rf_calculate_ei30() — calculate event energy, intensities, EI30, and erosive-event classification;
• rf_calculate_rfactor() — aggregate contributing erosive-event EI30 by month or year;
• rf_calculate_mean_rfactor() — calculate multi-year mean monthly or annual rainfall erosivity from monthly or yearly R-factor values.

Installation

Rfactor is available from CRAN:

install.packages("Rfactor")

You can install the development version from GitHub with:

install.packages("remotes")
remotes::install_github("adrianira/Rfactor")

If remotes is already installed, only the second command is needed.

The GitHub development version may contain changes that are not yet available in the CRAN release.

Quick start

A rainfall file needs a timestamp column and a precipitation column. For example:

datetime,precip_mm
2025-07-01 12:00:00,0.0
2025-07-01 12:01:00,0.4
2025-07-01 12:02:00,0.8
2025-07-01 12:03:00,0.3

Read and validate the rainfall data:

library(Rfactor)

rain <- rf_read_rainfall(
  "rainfall.csv",
  datetime_col = "datetime",
  precip_col = "precip_mm",
  tz = "UTC",
  expected_interval_min = 1
)

Identify rainfall events:

storms <- rf_identify_storms(
  rain
)

Calculate event rainfall erosivity:

events <- rf_calculate_ei30(
  storms
)

events[
  ,
  c(
    "event_start",
    "event_end",
    "precip_mm",
    "i30_mm_h",
    "energy_mj_ha",
    "ei30",
    "erosive"
  )
]

Aggregate erosive-event EI30 by calendar month or year:

monthly <- rf_calculate_rfactor(
  events,
  period = "monthly"
)

yearly <- rf_calculate_rfactor(
  events,
  period = "yearly"
)

Calculate multi-year mean monthly and annual rainfall erosivity:

monthly_mean <- rf_calculate_mean_rfactor(
  monthly,
  period = "monthly"
)

annual_mean <- rf_calculate_mean_rfactor(
  yearly,
  period = "yearly"
)

These calculations are meaningful as multi-year means when the supplied monthly or yearly R-factor table spans multiple years.

For monthly input, a separate mean is calculated for each available calendar month. For yearly input, the available yearly R-factor values are averaged directly.

Calculation settings

Calculation settings are created with rf_settings().

The principal defaults use:

• a 6-hour rainfall-event break;
• precipitation omission below 12.70 mm;
• maximum 15-minute intensity omission below 25.40 mm/h;
• "all" omission logic, so both enabled omission conditions must be satisfied;
• Brown and Foster (1987) rainfall kinetic energy;
• maximum intensities at 5, 10, 15, 20, 30, and 60 minutes.

The omission comparisons are strict. For example, an event with exactly 12.70 mm precipitation does not satisfy the default precipitation omission condition, and an event with exactly 25.40 mm/h maximum 15-minute intensity does not satisfy the default intensity omission condition.

The available kinetic-energy equations are Brown and Foster (1987), McGregor et al. (1995), and Laws and Parsons (1943).

For example:

settings <- rf_settings(
  energy_equation = "mcgregor_1995",
  omit_precip = FALSE,
  omit_intensity = FALSE
)

storms <- rf_identify_storms(
  rain,
  settings = settings
)

events <- rf_calculate_ei30(
  storms
)

Setting both omission switches to FALSE includes every identified rainfall event.

The RIST storm-break precipitation setting storm_break_precip_mm is retained as configuration metadata. Validation against RIST 3.99.10 fixed-interval input showed that changing this setting did not alter rainfall-event grouping in the tested cases. In the validated fixed-interval algorithm used by Rfactor, event separation is controlled by storm_break_hours, and any positive rainfall observation resets the storm-break clock.

Temporal resolution

Rainfall intensity calculations depend on the temporal resolution of the precipitation record.

A requested intensity duration must be an exact multiple of the source interval. For example, 10-minute rainfall data can be used to calculate 10-, 20-, 30-, and 60-minute intensities, but not a true 5- or 15-minute intensity.

EI30 additionally requires a genuine 30-minute intensity, so the source interval must divide 30 minutes exactly. Fixed-interval calculations have been validated against RIST 3.99.10 using 1-, 5-, 10-, 15-, and 30-minute rainfall data.

Rainfall records coarser than 30 minutes cannot provide a genuine I30 and therefore cannot be used to calculate genuine EI30.

Temporal aggregation can change maximum intensity, kinetic energy, and EI30 even when the total rainfall amount is preserved.

Sparse and incomplete rainfall records

Rfactor does not require every expected timestamp to be present in the input file.

Gaps are accepted when timestamps remain aligned with the declared base temporal resolution. The package does not interpolate missing precipitation and does not assess or correct the climatological completeness of the rainfall record.

During rainfall-event identification, a regular time grid is reconstructed only between the first and last positive-rainfall observation belonging to each event. Expected positions absent from the supplied record are assigned zero recorded rainfall for the calculation.

An inserted zero is a computational representation of an absent source position; it does not assert that the corresponding interval was observed and dry.

Completely absent months or years are not created or imputed.

Period totals and multi-year mean R-factor

rf_calculate_rfactor() sums the EI30 values of contributing erosive events within the requested calendar month or year.

A monthly or yearly value returned by this function is therefore an erosivity total calculated from the rainfall events available for that period.

A yearly value from rf_calculate_rfactor() is not automatically a climatological long-term mean annual R-factor.

Multi-year mean rainfall erosivity is calculated with rf_calculate_mean_rfactor().

For yearly input, the function calculates the arithmetic mean of the available yearly R-factor values:

$$ \bar{R} = \frac{1}{n} \sum_{y=1}^{n} R_y $$

For monthly input, a separate multi-year mean is calculated for each calendar month:

$$ \bar{R}m = \frac{1}{n_m} \sum{y=1}^{n_m} R_{y,m} $$

where n_years reports the number of non-missing R-factor values used in each mean.

Missing R values are excluded from the calculation. Genuine zero values are retained because R = 0 represents a valid period with no contributing erosive events.

For example, the yearly values

800, 900, NA, 700, 0

produce a mean based on

800, 900, 700, 0

so n_years = 4.

Calendar periods represented by rainfall events are retained by rf_calculate_rfactor() even when none of those events are erosive; such periods have R = 0 and n_events = 0. Completely absent calendar periods are not generated.

Similarly, rf_calculate_mean_rfactor() does not create missing years or month-year combinations. A calendar month that is completely absent from the supplied monthly table is not generated.

The mean annual R-factor is calculated directly from yearly R-factor values. It is not calculated by summing the twelve multi-year monthly means. This distinction matters when the number of available years differs among calendar months.

Rfactor does not determine whether an available monthly or yearly R-factor value was derived from a climatologically complete rainfall record. Assessment of completeness and representativeness remains the responsibility of the user.

Validation

Rfactor has been empirically compared with RIST (Rainfall Intensity Summarization Tool) 3.99.10 using fixed-interval rainfall input.

Validation includes synthetic tests of rainfall-event separation, continuous rolling intensities, strict omission thresholds, single-record events, three kinetic-energy equations, and temporal resolutions of 1, 5, 10, 15, and 30 minutes.

The package was also tested with real high-resolution and sparse historical precipitation records from Meteo Romania (National Meteorological Administration). The original Meteo Romania precipitation records are not distributed with the package or public repository.

For the synthetic temporal-resolution experiment, results were identical or very close to RIST. Small RIST-specific differences in reported precipitation and rolling intensity were observed for some 10- and 15-minute synthetic cases; Rfactor preserves the rainfall totals obtained directly from the supplied source data rather than reproducing those RIST-specific differences.

License

Rfactor is free software licensed under the GNU General Public License, version 3 or any later version (GPL-3.0-or-later).