rankSwap(): documentation says P is a percentage, but implementation appears to treat it as a proportion

[MuellerRoman]

Dear sdcMicro-Team,

The documentation for rankSwap() describes P as a percentage of the sample size. However, the current C++ implementation appears to use P directly as a proportion/fraction when computing the rank-swap window.

This means that a documented call such as P = 10 for a 10% rank window may instead be interpreted as a multiplier of 10, i.e. a 1000% rank window, rather than as 0.10. The implementation-consistent value for a 10% window appears to be P = 0.10.

Documentation mismatch

The documentation describes P as:

Rank range as percentage of total sample size

and the Details section describes the candidate condition as: $|i - j| \leq P * N / 100$

This suggests that users should pass P = 10 to get a 10% rank window.

However, the implementation appears to require P = 0.10 for that behavior.

This may cause users following the documentation to apply much stronger perturbation than intended.

Location

R wrapper:

R/rankSwap.R

C++ implementation:

src/RankSwapping.h

In the C++ code, P appears to be assigned directly from the user-supplied value:

P = g_P;

and later used as:

int r = Min(NbNotSwapped, (int) (j + NbNotSwapped * P)),

followed by candidate selection over:

for (k = j + 1; k < r; ++k)

So the effective candidate interval is approximately:

j < k < j + P * NbNotSwapped

rather than:

j < k < j + (P / 100) * N

Additional detail: N vs NbNotSwapped

The documentation refers to total sample size N, but the implementation uses NbNotSwapped, which excludes values already marked as unavailable/swapped, including missing values and values affected by TopPercent or BottomPercent.

So the implemented window is based on the number of remaining swappable records, not necessarily the full number of rows.

Suggested fixes

There seem to be two possible ways to resolve this.

Option 1: keep implementation, update documentation

If the current implementation is intended, the documentation could say that P is a proportion, not a percentage. For example:

P: rank-swap window as a proportion of the number of swappable records. Use P = 0.10 for a 10% rank window. For a record at sorted rank j, candidate swap partners are selected from later unswapped ranks k satisfying approximately j < k < j + P * N_s, where N_s is the number of swappable records after missing-value handling and top/bottom coding.

Option 2: keep documentation, change implementation or wrapper

If the documentation is intended, then the R wrapper or C++ code could convert the user-supplied percentage to a proportion before using it.

For example, direct user-supplied P could be converted using:

P <- P / 100

or equivalently in C++:

P = g_P / 100.0;

This would make P = 10 behave as a 10% rank window, consistent with the documentation.