Add alpha argument for CI width calculation

[erex]

Workshop participant asked how to set $\alpha$ for confidence interval widths other than 95%. Checking the arguments and description of ds() there does not appear to be a way to specify $\alpha$.

In mrds confidence interval calculations occur via dht.se and in the control list for dht there is an entry ci.width. But no way to access this via ds()

This from documentation for mrds::dht

Some dht_options are set by ds() in lines following 731

Perhaps $\alpha$ could be added as an argument to ds() and set around line 731 to be passed to dht

[lenthomas]

I created a branch for this request - branch Issue_215. In that, I added an argument conf_level to the ds function. I used this argument name as it's what's used in other packages that produce confidence intervals such as PropCIs (well, they use conf.level but our convention is to use an underscore). Here's some code that exercises that argument:

library(Distance)
data(book.tee.data)
tee.data <- subset(book.tee.data$book.tee.dataframe, observer==1)
ds.model <- ds(tee.data, 4)
summary(ds.model)

region <- book.tee.data$book.tee.region
samples <- book.tee.data$book.tee.samples
obs <- book.tee.data$book.tee.obs

ds.dht.model <- ds(tee.data, 4, region_table=region,
                   sample_table=samples, obs_table=obs, conf_level=0.8)
summary(ds.dht.model)

@erex Let me know what you think and if okay I'll merge with the main branch. Thanks for making it so easy to work out what to do!

[erex]

yes, this all looks good; argument is even added to documentation.

Vaguely related to this is how user specifies CI desires for bootdht. The function summary.dht_bootstrap (note interesting coding convention use of . and _) asks the user to specify $\alpha$ rather than $1-\alpha$ as is done with dht. But that might be for another day.

[lenthomas]

Thanks for pointing that out. How about I create an alpha argument for ds that has no default, so has no effect if you don't use it, but if you do it takes precidence over conf_level? That way the user can use either. (I could also create a conf_level argument for summary.dht_bootstrap.)

The mixture of dot and underscore in summary.dht_bootstrap is because we're using S3 classes in the Distance package and the dot is how you tell R that this function is a summary function for the dht_bootstrap class. Clunky, but S3 has been around for yonks and that's how it works.

[erex]

I'm relaxed about what you do with alpha and conf_level. Would be nice if there was consistency between functions within our packages.

[lenthomas]

Indeed, with this in mind I added an alpha argument to ds, tested, and merged in with the main branch. I didn't add conf_level to dht_bootstrap as that's complicated enough as is, so I thought I'd leave it. I'll close this issue now - please can you pass back info about the new feature to your workshop participant.

[erex]

Don't think this is closed yet, see my comment in pull request #217 #217

Something not quite right about roxygen I'm guessing. You changed ds.R, but those changes did not propagate into ds.Rd in the documentation. Github actions noticed this and complained the two files are inconsistent.

[lenthomas]

Thanks, clearly I am out of date with this stuff. I ran devtools::document() and pushed the new .Rd. Should all be fine now.