store worldArray character layers as levels

[achubaty]

Closes #49.

The problem

An array holds a single type. Stacking a character worldMatrix next to a numeric one therefore turned every layer into character, and the character values were then coerced back to NA on the way out:

w1 <- createWorld(minPxcor = 0, maxPxcor = 4, minPycor = 0, maxPycor = 4, data = 1:25)
w2 <- createWorld(minPxcor = 0, maxPxcor = 4, minPycor = 0, maxPycor = 4, data = rep("sea", 25))
w3 <- stackWorlds(w1, w2)

of(world = w3, agents = cbind(pxcor = 1, pycor = 1), var = "w2")
#> NA
#> Warning: NAs introduced by coercion

plot(w3)
#> Warning: NAs introduced by coercion

The numeric layer was collateral damage too — of(w3, var = "w1") returned the string "17" rather than 17.

The fix

worldArray gains a levels slot. Character layers are stored as integer codes with their categories recorded there, exactly as agentMatrix already does for its character columns, so the array itself stays numeric.

Accessors report the characters, never the codes:

	before	after
of(w3, var = "w2")	NA + warning	"sea"
of(w3, var = "w1")	"17" (character)	17 (numeric)
of(w3, var = c("w1","w2"))	coerced matrix	data.frame
plot(w3)	warns, layer all NA	categorical layer
w3[["w2"]]	numeric worldMatrix	character worldMatrix

NLwith() compares against the characters, NLset() encodes them and extends the levels when it meets a new category, and [[<- re-encodes so swapping layers cannot leave the array and the levels inconsistent. world2spatRast() hands terra the characters and lets terra build the categorical layer — which is exactly what a standalone character worldMatrix has always produced, so the two paths now agree.

An all-numeric worldArray is untouched by any of this: empty levels, matrix returns, same types.

One deliberate restriction

Turning some patches of a numeric layer into characters is rejected:

NLset(world = w, agents = cbind(pxcor = 0, pycor = 0), var = "num", val = "oops")
#> Error: cannot assign character values to only some patches of the numeric worldArray layer 'num'.
#> Assign the whole layer instead, e.g. world[['num']] <- aCharacterWorld.

The numbers left in the unassigned patches would silently be reinterpreted as codes. Assigning the whole layer is allowed, as is world[["num"]] <- aCharacterWorld.

Note that cbind(num = 1, hab = "ice") is already a character matrix before NLset() ever sees it, so numbers arrive at a numeric layer as strings. Those are converted back when they parse cleanly, rather than being treated as new categories. Pass a data.frame to keep the column types distinct.

Rebased onto #57 and #58

Both prerequisites are merged, and this branch has been rebased onto them. Conflicts resolved:

• R/world-functions.R — kept drop the quickPlot dependency #57's ncols=/nrows= fix and this PR's decoded vals, in the same terra::rast() call.
• NEWS.md and tests/testthat/test-NetLogoR-classes.R — both PRs' entries and test blocks retained.

With #57 in the base, plot(w3) is now completely silent: its nrow/ncol partial-match warnings are gone and the NAs introduced by coercion warning this PR removes is gone, so the two fixes compose as intended.

Verification

• R CMD check --as-cran: 0 errors, 0 warnings, 0 notes
• devtools::test(): 0 failures, 1225 passing (rebased onto drop the quickPlot dependency #57, which replaced the quickPlot plotting tests)
• The reproducer from Error with plot() and of() when the world contains a layer with character values #49 verified directly: of() returns "sea", and plot(w3) emits no warnings at all

🤖 Generated with Claude Code