A quick start to the spectacles package
Author: Pierre Roudier
Date: 2025-10-20

# A quick start to the `spectacles` package

#### Pierre Roudier

#### 2025-10-20

    library(spectacles)

# Converting data to a `SpectraDataFrame`

    data("australia")
    class(australia)
    #> [1] "data.frame"
    big.head(australia)
    #>   sr_no carbon  ph clay       X350 ...     X2496     X2497     X2498     X2499
    #> 1    28   0.63 7.3 30.0 0.08173233 ... 0.3888433 0.3942973 0.3934600 0.3889097
    #> 2    36   0.69 9.4 45.0 0.10344727 ... 0.3035470 0.3016855 0.3077460 0.3116423
    #> 3   136   1.44 8.9 33.3 0.11363971 ... 0.3524803 0.3526042 0.3598545 0.3576893
    #> 4   194   0.33 7.2  3.5 0.16374375 ... 0.7547905 0.7552416 0.7525422 0.7513548
    #> 5   215   1.12 8.1 17.1 0.09693917 ... 0.4397273 0.4433315 0.4389216 0.4340123
    #>       X2500
    #> 1 0.3864646
    #> 2 0.3036998
    #> 3 0.3460697
    #> 4 0.7567009
    #> 5 0.4373087

    spectra(australia) <- sr_no ~ ... ~ 350:2500
    #> Wavelength range: 350 to 2500 nm
    #> Spectral resolution: 1 nm
    summary(australia)
    #> Object of class SpectraDataFrame
    #> Set of 100 spectra
    #> Wavelength range: 350 to 2500 nm
    #> Spectral resolution: 1 nm
    #> Data attributes:
    #>      carbon            ph             clay
    #>  Min.   :0.050   Min.   :5.000   Min.   : 2.80
    #>  1st Qu.:0.780   1st Qu.:6.200   1st Qu.:18.15
    #>  Median :1.365   Median :7.300   Median :33.65
    #>  Mean   :2.305   Mean   :7.196   Mean   :35.80
    #>  3rd Qu.:3.135   3rd Qu.:8.025   3rd Qu.:50.98
    #>  Max.   :9.530   Max.   :9.500   Max.   :69.00

# Accessing the different elements of the `SpectraDataFrame` object

## General information about the `SpectraDataFrame`

`nrow` returns the number of samples in the object:

    nrow(australia)
    #> [1] 100

`ncol` returns the number of attributes in the data slot of the object, and returns `NULL` if the object does not have associated data:

    ncol(australia)
    #> [1] 2151

`length` returns the number of wavelengths in the object:

    length(australia)
    #> [1] 2151

`dim` returns a numeric vector of these three dimensions:

    dim(australia)
    #> [1]  100 2151    3

## Subsetting

    sub <- australia[1:5,]
    summary(sub)
    #> Object of class SpectraDataFrame
    #> Set of 5 spectra
    #> Wavelength range: 350 to 2500 nm
    #> Spectral resolution: 1 nm
    #> Data attributes:
    #>      carbon            ph            clay
    #>  Min.   :0.330   Min.   :7.20   Min.   : 3.50
    #>  1st Qu.:0.630   1st Qu.:7.30   1st Qu.:17.10
    #>  Median :0.690   Median :8.10   Median :30.00
    #>  Mean   :0.842   Mean   :8.18   Mean   :25.78
    #>  3rd Qu.:1.120   3rd Qu.:8.90   3rd Qu.:33.30
    #>  Max.   :1.440   Max.   :9.40   Max.   :45.00

## Accessing specific properties of Spectra objects

Specific functions are available to access the various properties of Spectra objects:

`ids` is returning a vector containing the IDs of the object. It has a `as.vector` option. When turned to `FALSE`, the function returns a `data.frame` instead of a vector. This is particularly useful to retrieve the original column name of the IDs:

    # Just printing the first 5
    ids(australia)[1:5]
    #> [1]  28  36 136 194 215

`wl` is returning the wavelengths of the object in a numeric vector:

    # Just printing the first 10
    wl(australia)[1:10]
    #>  [1] 350 351 352 353 354 355 356 357 358 359

`spectra` is returning the spectra matrix:

    s <- spectra(australia)
    class(s)
    #> [1] "matrix" "array"
    dim(s)
    #> [1]  100 2151
    big.head(s)
    #>           X350       X351       X352       X353       X354 ...     X2496
    #> 28  0.08173233 0.08074037 0.08312159 0.08690414 0.08761925 ... 0.3888433
    #> 36  0.10344727 0.09767456 0.09267905 0.09155867 0.10600654 ... 0.3035470
    #> 136 0.11363971 0.13762568 0.14234437 0.13608806 0.13451828 ... 0.3524803
    #> 194 0.16374375 0.16650400 0.16646151 0.16540240 0.16768558 ... 0.7547905
    #> 215 0.09693917 0.10563760 0.10342025 0.09727478 0.10408881 ... 0.4397273
    #>         X2497     X2498     X2499     X2500
    #> 28  0.3942973 0.3934600 0.3889097 0.3864646
    #> 36  0.3016855 0.3077460 0.3116423 0.3036998
    #> 136 0.3526042 0.3598545 0.3576893 0.3460697
    #> 194 0.7552416 0.7525422 0.7513548 0.7567009
    #> 215 0.4433315 0.4389216 0.4340123 0.4373087

`wl_units` is returning the wavelength units:

    wl_units(australia)
    #> [1] "nm"

`features` is returning associated data into a `data.frame`:

    df <- features(australia)
    class(df)
    #> [1] "data.frame"
    head(df)
    #>     carbon  ph clay
    #> 28    0.63 7.3 30.0
    #> 36    0.69 9.4 45.0
    #> 136   1.44 8.9 33.3
    #> 194   0.33 7.2  3.5
    #> 215   1.12 8.1 17.1
    #> 244   1.14 8.1 34.0

# Basic plotting

    plot(australia)

    plot(australia, col = "royalblue")