# Introduction to osum

## Motivation

Before R became available, I was a heavy user of the S-PLUS™ software, a commercial declination of R’s ancestor S. It had a very practical function called `objects.summary()`, which would list objects from an environment in a tabular form (basically as a `data.frame`) with some interesting attributes including class, mode, dimensions, and size. I couldn’t find its equivalent in R, so I wrote one 😊

## Installation

### Stable version

You can install the current stable version of `osum` from CRAN:

    install.packages("osum")

Windows and macOS binary packages are available from here.

### Development version

You can install the development version of `osum` including latest features from GitHub:

    require(remotes)
    install_github("zivankaraman/osum")

## Basic Usage

First, we need to populate the session environment with a few objects.

    a <- month.name
    b <- sample(c("FALSE", "TRUE"), size = 5, replace = TRUE)
    cars <- mtcars
    .hidden <- -1L
    .secret <- "Shhht!"
    x1 <- rnorm(n = 10)
    x2 <- runif(n = 20)
    x3 <- rbinom(n = 30, size = 10, prob = 0.5)
    lst <- list(first = x1, second = x2, third = x3)
    fun <- function(x) {sqrt(x)}

By default, the environment of the call to `objects.summary` is used, here `.GlobalEnv`.

    objects.summary()
    #>      data.class storage.mode      mode    typeof  extent object.size
    #> a     character    character character character      12         880
    #> b     character    character character character       5         152
    #> cars data.frame         list      list      list 32 x 11        7208
    #> fun    function     function  function   closure       1        4552
    #> lst        list         list      list      list       3        1000
    #> x1      numeric       double   numeric    double      10         176
    #> x2      numeric       double   numeric    double      20         208
    #> x3      numeric      integer   numeric   integer      30         176

The hidden objects are not shown by default. One has to provide argument `all.objects=TRUE` to see them (not unlike the `all.names` argument to the `ls` function)

    objects.summary(all.objects = TRUE)
    #>              data.class storage.mode      mode    typeof  extent object.size
    #> .Random.seed    numeric      integer   numeric   integer     626        2552
    #> .hidden         numeric      integer   numeric   integer       1          56
    #> .secret       character    character character character       1         112
    #> a             character    character character character      12         880
    #> b             character    character character character       5         152
    #> cars         data.frame         list      list      list 32 x 11        7208
    #> fun            function     function  function   closure       1        4552
    #> lst                list         list      list      list       3        1000
    #> x1              numeric       double   numeric    double      10         176
    #> x2              numeric       double   numeric    double      20         208
    #> x3              numeric      integer   numeric   integer      30         176

If the `objects.summary` is called inside the function, it is the calling function’s environment that is used by default.

    # shows an empty list because inside myfunc no variables are defined
    myfunc <- function() {objects.summary()}
    myfunc()
    #> [1] data.class   storage.mode mode         typeof       extent
    #> [6] object.size
    #> <0 rows> (or 0-length row.names)
    # define a local variable inside myfunc
    myfunc <- function() {y <- 1; objects.summary()}
    myfunc()
    #>   data.class storage.mode    mode typeof extent object.size
    #> y    numeric       double numeric double      1          56

### Restricting the Objects List

We can limit the output to objects with names matching the regular expression provided as the `pattern` argument. Alternatively, we can provide a character vector naming objects to summarize in the `names` argument.

    objects.summary(pattern = "^x")
    #>    data.class storage.mode    mode  typeof extent object.size
    #> x1    numeric       double numeric  double     10         176
    #> x2    numeric       double numeric  double     20         208
    #> x3    numeric      integer numeric integer     30         176
    objects.summary(names = c("a", "b"))
    #>   data.class storage.mode      mode    typeof extent object.size
    #> a  character    character character character     12         880
    #> b  character    character character character      5         152

## Where to Look for Objects?

We can list the objects from any environment, not just the current environment. The environment can be provided as an integer indicating the position in the search list or a character giving the name of an environment in the search list.

    idx <- grep("package:graphics", search())
    objects.summary(idx, pattern = "^plot")
    #>               data.class storage.mode     mode  typeof extent object.size
    #> plot            function     function function closure      1        1408
    #> plot.default    function     function function closure      1      127632
    #> plot.design     function     function function closure      1      479960
    #> plot.function   function     function function closure      1       64880
    #> plot.new        function     function function closure      1       17880
    #> plot.window     function     function function closure      1       11136
    #> plot.xy         function     function function closure      1       75352
    objects.summary("package:graphics", pattern = "^plot")
    #>               data.class storage.mode     mode  typeof extent object.size
    #> plot            function     function function closure      1        1408
    #> plot.default    function     function function closure      1      127632
    #> plot.design     function     function function closure      1      479960
    #> plot.function   function     function function closure      1       64880
    #> plot.new        function     function function closure      1       17880
    #> plot.window     function     function function closure      1       11136
    #> plot.xy         function     function function closure      1       75352

We can also explicitly provide an environment.

    e <- new.env()
    e$a <- 1:10
    e$b <- rnorm(25)
    e$df <- iris
    e$arr <- iris3
    objects.summary(e)
    #>     data.class storage.mode    mode  typeof     extent object.size
    #> a      numeric      integer numeric integer         10          96
    #> arr      array       double numeric  double 50 x 4 x 3        5816
    #> b      numeric       double numeric  double         25         248
    #> df  data.frame         list    list    list    150 x 5        7256

Unless an explicit environment is provided, `where` argument should designate an element of the search list. However, if it is a character of the form “package:pkg_name” and if the package named “pkg_name” is installed, it is silently loaded, its objects retrieved, and then it is unloaded when the function exits. Depending on the time it takes to load the package, the execution might be slower than getting the information about an attached package.

    # check if the package foreign is attached
    length(grep("package:foreign", search())) > 0L
    #> [1] FALSE
    objects.summary("package:foreign", pattern = "^write")
    #>               data.class storage.mode     mode  typeof extent object.size
    #> write.arff      function     function function closure      1      234168
    #> write.dbf       function     function function closure      1      308496
    #> write.dta       function     function function closure      1      224872
    #> write.foreign   function     function function closure      1       12720
    # check if the package foreign is attached
    length(grep("package:foreign", search())) > 0L
    #> [1] FALSE

## Selecting Information to Display

We don’t need to display all the attributes, the `what` argument controls which information is returned. Partial matching is used, so only enough initial letters of each string element are needed to guarantee unique recognition. For example, “`data[.class]`”, “`stor[age.mode]`”, “`ext[ent]`”, “`obj[ect.size]`”.

    objects.summary(what = c("data.class", "storage.mode", "extent", "object.size"))
    #>      data.class storage.mode  extent object.size
    #> a     character    character      12         880
    #> b     character    character       5         152
    #> cars data.frame         list 32 x 11        7208
    #> fun    function     function       1        4552
    #> idx     numeric      integer       1          56
    #> lst        list         list       3        1000
    #> x1      numeric       double      10         176
    #> x2      numeric       double      20         208
    #> x3      numeric      integer      30         176
    objects.summary(what = c("data", "stor", "ext", "obj"))
    #>      data.class storage.mode  extent object.size
    #> a     character    character      12         880
    #> b     character    character       5         152
    #> cars data.frame         list 32 x 11        7208
    #> fun    function     function       1        4552
    #> idx     numeric      integer       1          56
    #> lst        list         list       3        1000
    #> x1      numeric       double      10         176
    #> x2      numeric       double      20         208
    #> x3      numeric      integer      30         176

In fact, just providing the first letter is sufficient, since all the possible values start with a different letter. The order of columns in the summary respects the order in which their names are listed in the `what` argument.

    objects.summary(what = c("m", "s", "t", "o", "d", "e"))
    #>           mode storage.mode    typeof object.size data.class  extent
    #> a    character    character character         880  character      12
    #> b    character    character character         152  character       5
    #> cars      list         list      list        7208 data.frame 32 x 11
    #> fun   function     function   closure        4552   function       1
    #> idx    numeric      integer   integer          56    numeric       1
    #> lst       list         list      list        1000       list       3
    #> x1     numeric       double    double         176    numeric      10
    #> x2     numeric       double    double         208    numeric      20
    #> x3     numeric      integer   integer         176    numeric      30

It should be noted that attributes `storage.mode`, `mode`, and `typeof` are somewhat redundant, so you can select only those that are relevant to you. You can set your personal preferences using the `osum.options` function, as explained in Options.

## Filtering Objects

The subset of objects from the environment `where` which should be selected for summary is specified with either an explicit vector of names provided in argument `names`, or with some combination of the subsetting criteria `pattern` (as seen in Restricting the Objects List), `data.class`, `storage.mode`, `mode`, and `typeof`. If argument `names` is given, the other criteria are ignored. If more than one criterion is given, only objects which satisfy all of them are selected. In the absence of both `names` and criteria, all objects in `where` are selected.

    objects.summary("package:datasets", pattern = "^[sU]", what = c("dat", "typ", "ext", "obj"),
                    data.class = c("data.frame", "matrix"))
    #>                       data.class typeof  extent object.size
    #> USArrests             data.frame   list  50 x 4        5736
    #> USJudgeRatings        data.frame   list 43 x 12        9328
    #> USPersonalExpenditure     matrix double   5 x 5        1448
    #> sleep                 data.frame   list  20 x 3        2984
    #> stack.x                   matrix double  21 x 3        1168
    #> stackloss             data.frame   list  21 x 4        1792
    #> state.x77                 matrix double  50 x 8        7672
    #> swiss                 data.frame   list  47 x 6        6464

Objects can have more than one class, but only the first class element is used by default. Specifying `all.classes=TRUE` allows to consider the entire class vector of an object, both in selection based on argument `data.class` and in the returned summary.

    objects.summary("package:datasets", what = c("dat", "typ", "ext", "obj"), data.class = "array")
    #>       data.class typeof     extent object.size
    #> iris3      array double 50 x 4 x 3        5816
    objects.summary("package:datasets", what = c("dat", "typ", "ext", "obj"),
                    all.classes = TRUE, data.class = "array")
    #>                         data.class typeof     extent object.size
    #> EuStockMarkets        mts, ts,.... double   1860 x 4       60824
    #> Seatbelts             mts, ts,.... double    192 x 8       13872
    #> USPersonalExpenditure matrix, .... double      5 x 5        1448
    #> VADeaths              matrix, .... double      5 x 4        1264
    #> WorldPhones           matrix, .... double      7 x 7        1800
    #> euro.cross            matrix, .... double    11 x 11        2944
    #> freeny.x              matrix, .... double     39 x 4        2008
    #> iris3                        array double 50 x 4 x 3        5816
    #> stack.x               matrix, .... double     21 x 3        1168
    #> state.x77             matrix, .... double     50 x 8        7672
    #> volcano               matrix, .... double    87 x 61       42672

Besides simple filtering criteria by values of attributes, we can also filter on logical expression indicating elements (rows) to keep. The expression is evaluated in the data frame with object attributes, so columns should be referred to (by unquoted attribute name) as variables in the expression (not unlike the `select` argument of the base `subset` function). This can be particularly helpful when we want to exclude some values, avoiding explicit listing of all other (possible) values, as shown in the example below.

    objects.summary("package:grDevices", filter = mode != "function")
    #>             data.class storage.mode      mode    typeof extent object.size
    #> Hershey           list         list      list      list      3        2024
    #> blues9       character    character character character      9         680
    #> colorspaces       list         list      list      list      6      478024

The filter expression can involve more than one attribute.

    objects.summary("package:datasets", filter = mode != storage.mode)[1:10, ]
    #>                data.class storage.mode    mode typeof        extent object.size
    #> AirPassengers          ts       double numeric double           144        1616
    #> BJsales                ts       double numeric double           150        1664
    #> BJsales.lead           ts       double numeric double           150        1664
    #> EuStockMarkets        mts       double numeric double      1860 x 4       60824
    #> HairEyeColor        table       double numeric double     4 x 4 x 2        2040
    #> JohnsonJohnson         ts       double numeric double            84        1136
    #> LakeHuron              ts       double numeric double            98        1248
    #> Nile                   ts       double numeric double           100        1264
    #> Seatbelts             mts       double numeric double       192 x 8       13872
    #> Titanic             table       double numeric double 4 x 2 x 2 x 2        2152

It can also be quite complex, as long as it yields a logical value for every object (row).

    objects.summary("package:datasets", all.classes = TRUE,
                    filter = sapply(data.class, length) > 2L)
    #>                  data.class storage.mode    mode typeof   extent object.size
    #> CO2            nfnGroup....         list    list   list   84 x 5        9976
    #> ChickWeight    nfnGroup....         list    list   list  578 x 4       22696
    #> DNase          nfnGroup....         list    list   list  176 x 3        8256
    #> EuStockMarkets mts, ts,....       double numeric double 1860 x 4       60824
    #> Indometh       nfnGroup....         list    list   list   66 x 3        5904
    #> Loblolly       nfnGroup....         list    list   list   84 x 3       12120
    #> Orange         nfnGroup....         list    list   list   35 x 3        5232
    #> Seatbelts      mts, ts,....       double numeric double  192 x 8       13872
    #> Theoph         nfnGroup....         list    list   list  132 x 5       10000

## Sorting Objects

By default, the object entries (printed as rows) in the summary are sorted alphabetically by object name. By providing the `order` argument, they can be sorted on any other column(s). The `order` argument should be (unquoted) column names. For numeric columns, one can precede the name by “-” to sort in descending order, with the expression enclosed in parentheses (see examples). To sort on more than one column, the expression must be provided as a vector `c(., .)` (again see examples). Feature inspired by the standard R `order` function.

    # filter on 'mode' and sort on 'data.class'
    objects.summary("package:datasets", what = c("dat", "typ", "ext", "obj"), mode = "numeric",
                    order = data.class)[1:10, ]
    #>                       data.class  typeof     extent object.size
    #> iris3                      array  double 50 x 4 x 3        5816
    #> UScitiesD                   dist integer         45        2392
    #> eurodist                    dist  double        210        3688
    #> state.region              factor integer         50         904
    #> state.division            factor integer         50        1392
    #> USPersonalExpenditure     matrix  double      5 x 5        1448
    #> WorldPhones               matrix  double      7 x 7        1800
    #> volcano                   matrix  double    87 x 61       42672
    #> VADeaths                  matrix  double      5 x 4        1264
    #> euro.cross                matrix  double    11 x 11        2944
    # filter on 'mode' and sort (descending) on 'object.size'
    objects.summary("package:datasets", what = c("dat", "typ", "ext", "obj"), mode = "numeric",
                    order = (-object.size))[1:10, ]
    #>                data.class  typeof     extent object.size
    #> treering               ts  double       7980       64304
    #> EuStockMarkets        mts  double   1860 x 4       60824
    #> volcano            matrix  double    87 x 61       42672
    #> sunspot.month          ts  double       3177       25880
    #> sunspots               ts  double       2820       23024
    #> Seatbelts             mts  double    192 x 8       13872
    #> crimtab             table integer    42 x 22        8504
    #> state.x77          matrix  double     50 x 8        7672
    #> iris3               array  double 50 x 4 x 3        5816
    #> precip            numeric  double         70        5560
    objects.summary("package:datasets", what = c("dat", "typ", "ext", "obj"),
                    order = c(data.class, -object.size))[1:10, ]
    #>                data.class    typeof     extent object.size
    #> iris3               array    double 50 x 4 x 3        5816
    #> state.name      character character         50        3496
    #> state.abb       character character         50        3248
    #> quakes         data.frame      list   1000 x 5       33232
    #> infert         data.frame      list    248 x 8       16064
    #> attenu         data.frame      list    182 x 5       15648
    #> randu          data.frame      list    400 x 3       10584
    #> USJudgeRatings data.frame      list    43 x 12        9328
    #> morley         data.frame      list    100 x 3        8576
    #> iris           data.frame      list    150 x 5        7256

It should be noted that although the `extent` is by default printed (by the specific print method for objects of class `objects.summary`) as a product of dimensions (d1 x d2), it is internally stored as a list, which allows sorting on a number of rows or columns, for example.

    # get all two-dimensional objects of from the datasets package, with more than 7 columns,
    # sorted by number on columns (ascending) and then on number of rows (descending)
    objects.summary("package:datasets", what = c("dat", "typ", "ext", "obj"),
                    filter = sapply(extent, length) == 2L & sapply(extent, "[", 2L) > 7L,
                    order = c(sapply(extent, "[", 2L), -sapply(extent, "[", 1L)))
    #>                    data.class  typeof  extent object.size
    #> infert             data.frame    list 248 x 8       16064
    #> Seatbelts                 mts  double 192 x 8       13872
    #> state.x77              matrix  double  50 x 8        7672
    #> anscombe           data.frame    list  11 x 8        2592
    #> occupationalStatus      table integer   8 x 8        2288
    #> mtcars             data.frame    list 32 x 11        7208
    #> euro.cross             matrix  double 11 x 11        2944
    #> USJudgeRatings     data.frame    list 43 x 12        9328
    #> crimtab                 table integer 42 x 22        8504
    #> volcano                matrix  double 87 x 61       42672

The entries are sorted in ascending order by default. They can be sorted in descending order by specifying `reverse=TRUE`.

    # get five biggest objects from package datasets
    objects.summary("package:datasets", what = c("dat", "typ", "ext", "obj"),
                    reverse=TRUE)[1:10, ]
    #>               data.class typeof  extent object.size
    #> women         data.frame   list  15 x 2        1104
    #> warpbreaks    data.frame   list  54 x 3        2944
    #> volcano           matrix double 87 x 61       42672
    #> uspop                 ts double      19         616
    #> trees         data.frame   list  31 x 3        1728
    #> treering              ts double    7980       64304
    #> swiss         data.frame   list  47 x 6        6464
    #> sunspots              ts double    2820       23024
    #> sunspot.year          ts double     289        2776
    #> sunspot.month         ts double    3177       25880

It should be noted that the objects in the summary can be filtered and/or sorted by the columns that will not be part of the summary (i.e. are not listed in the `what` argument).

    objects.summary("package:datasets", what = c("dat", "typ", "ext"), pattern = "st",
                    filter = mode %in% c("list", "numeric"), order = object.size)
    #>                data.class  typeof extent
    #> stack.loss        numeric  double     21
    #> state.area        numeric  double     50
    #> state.region       factor integer     50
    #> stack.x            matrix  double 21 x 3
    #> austres                ts  double     89
    #> state.center         list    list      2
    #> state.division     factor integer     50
    #> stackloss      data.frame    list 21 x 4
    #> eurodist             dist  double    210
    #> USArrests      data.frame    list 50 x 4
    #> state.x77          matrix  double 50 x 8

## Printing and Summarizing

The `objects.summary` function creates an object of class `objects.summary`, which is an extension of the `data.frame` class. The purpose of this class is being able to propose custom `print` and `summary` methods.

The number of rows printed can be limited by the `max.rows` argument, which allows more straightforward control than the `max` argument of the `print.data.frame`.

When `all.classes` argument is set to `TRUE`, the entire class vector is returned, and the `data.class` column is a list of character vectors. When such data is printed, the output is limited to a fixed number of characters (12 by default), longer strings being shown as e.g. “matrix, …” or “nfnGroup….”. The `data.class.width` argument to the `print` method allows users to change this value (probably to increase it), in order to see (almost) all the classes.

    os <- objects.summary("package:datasets", what = c("dat", "ext", "obj"),
                          all.classes = TRUE, order = object.size, reverse = TRUE)
    print(os, data.class.width = 25, max.rows = 12)
    #>                               data.class   extent object.size
    #> treering                              ts     7980       64304
    #> EuStockMarkets    mts, ts, matrix, array 1860 x 4       60824
    #> volcano                    matrix, array  87 x 61       42672
    #> quakes                        data.frame 1000 x 5       33232
    #> sunspot.month                         ts     3177       25880
    #> sunspots                              ts     2820       23024
    #> ChickWeight    nfnGroupedData, nfGro....  578 x 4       22696
    #> infert                        data.frame  248 x 8       16064
    #> attenu                        data.frame  182 x 5       15648
    #> Seatbelts         mts, ts, matrix, array  192 x 8       13872
    #> Loblolly       nfnGroupedData, nfGro....   84 x 3       12120
    #> randu                         data.frame  400 x 3       10584
    #>  [ reached 'max' / getOption("max.print") -- omitted 92 rows ]

    multi_class_objects <- row.names(objects.summary("package:datasets", all.classes = TRUE,
                                                     filter =  sapply(data.class, length) > 1L))
    os <- objects.summary("package:datasets", names = multi_class_objects, all.classes = TRUE,
                          what = c("dat", "ext", "obj"))
    print(os, data.class.width = 32, max.rows = 12)
    #>                                             data.class   extent object.size
    #> CO2                   nfnGroupedData, nfGroupedDat....   84 x 5        9976
    #> ChickWeight           nfnGroupedData, nfGroupedDat....  578 x 4       22696
    #> DNase                 nfnGroupedData, nfGroupedDat....  176 x 3        8256
    #> EuStockMarkets                  mts, ts, matrix, array 1860 x 4       60824
    #> Indometh              nfnGroupedData, nfGroupedDat....   66 x 3        5904
    #> Loblolly              nfnGroupedData, nfGroupedDat....   84 x 3       12120
    #> Orange                nfnGroupedData, nfGroupedDat....   35 x 3        5232
    #> Seatbelts                       mts, ts, matrix, array  192 x 8       13872
    #> Theoph                nfnGroupedData, nfGroupedDat....  132 x 5       10000
    #> USPersonalExpenditure                    matrix, array    5 x 5        1448
    #> VADeaths                                 matrix, array    5 x 4        1264
    #> WorldPhones                              matrix, array    7 x 7        1800
    #>  [ reached 'max' / getOption("max.print") -- omitted 5 rows ]

As already mentioned in Sorting Objects, the `extent` column is internally stored as a list, and we can explicitly control how it is printed by the `format.extent` argument.

    multi_dim_objects <- row.names(objects.summary("package:datasets", all.classes = TRUE,
                                                   data.class = c("array", "table")))
    os <- objects.summary("package:datasets", names = multi_dim_objects,
                          what = c("dat", "ext", "obj"))
    print(os[rev(order(sapply(os$extent, length))), ],
          format.extent = TRUE, max.rows = 12) # default
    #>                    data.class        extent object.size
    #> Titanic                 table 4 x 2 x 2 x 2        2152
    #> iris3                   array    50 x 4 x 3        5816
    #> UCBAdmissions           table     2 x 2 x 6        1992
    #> HairEyeColor            table     4 x 4 x 2        2040
    #> volcano                matrix       87 x 61       42672
    #> state.x77              matrix        50 x 8        7672
    #> stack.x                matrix        21 x 3        1168
    #> occupationalStatus      table         8 x 8        2288
    #> freeny.x               matrix        39 x 4        2008
    #> euro.cross             matrix       11 x 11        2944
    #> crimtab                 table       42 x 22        8504
    #> WorldPhones            matrix         7 x 7        1800
    #>  [ reached 'max' / getOption("max.print") -- omitted 4 rows ]
    print(os[rev(order(sapply(os$extent, length))), ],
          format.extent = FALSE, max.rows = 12)
    #>                    data.class     extent object.size
    #> Titanic                 table 4, 2, 2, 2        2152
    #> iris3                   array   50, 4, 3        5816
    #> UCBAdmissions           table    2, 2, 6        1992
    #> HairEyeColor            table    4, 4, 2        2040
    #> volcano                matrix     87, 61       42672
    #> state.x77              matrix      50, 8        7672
    #> stack.x                matrix      21, 3        1168
    #> occupationalStatus      table       8, 8        2288
    #> freeny.x               matrix      39, 4        2008
    #> euro.cross             matrix     11, 11        2944
    #> crimtab                 table     42, 22        8504
    #> WorldPhones            matrix       7, 7        1800
    #>  [ reached 'max' / getOption("max.print") -- omitted 4 rows ]

Other options can be passed down to the `print.data.frame` function (not necessarily very useful).

    print(objects.summary("package:datasets", what = c("dat", "typ", "ext", "obj")),
          format.extent = TRUE, max.rows = 12, right = FALSE, quote = TRUE)
    #>                data.class       typeof   extent      object.size
    #> AirPassengers  "ts"             "double" "144"       " 1616"
    #> BJsales        "ts"             "double" "150"       " 1664"
    #> BJsales.lead   "ts"             "double" "150"       " 1664"
    #> BOD            "data.frame"     "list"   "6 x 2"     " 1176"
    #> CO2            "nfnGroupedData" "list"   "84 x 5"    " 9976"
    #> ChickWeight    "nfnGroupedData" "list"   "578 x 4"   "22696"
    #> DNase          "nfnGroupedData" "list"   "176 x 3"   " 8256"
    #> EuStockMarkets "mts"            "double" "1860 x 4"  "60824"
    #> Formaldehyde   "data.frame"     "list"   "6 x 2"     " 1320"
    #> HairEyeColor   "table"          "double" "4 x 4 x 2" " 2040"
    #> Harman23.cor   "list"           "list"   "3"         " 2712"
    #> Harman74.cor   "list"           "list"   "3"         " 9624"
    #>  [ reached 'max' / getOption("max.print") -- omitted 92 rows ]

The `summary` method shares the same specific arguments as the `print` except for `max.rows`.

    os <- objects.summary("package:datasets", all.classes = TRUE, what = c("dat", "ext", "obj"),
                          filter = sapply(data.class, length) > 1L)
    summary(os, data.class.width = 32, format.extent = FALSE)
    #>                             data.class     extent    object.size
    #>                     matrix, array:8       5, 4: 1   Min.   : 1168
    #>            mts, ts, matrix, array:2       5, 5: 1   1st Qu.: 2008
    #>  nfnGroupedData, nfGroupedDat....:7       7, 7: 1   Median : 7672
    #>                                          21, 3: 1   Mean   :12344
    #>                                          35, 3: 1   3rd Qu.:12120
    #>                                          39, 4: 1   Max.   :60824
    #>                                        (Other):11

Again, other options can be passed down to the `summary.data.frame` function.

    summary(os, data.class.width = 32, maxsum = 10, quantile.type = 5)
    #>                             data.class      extent   object.size
    #>                     matrix, array:8    11 x 11 :1   Min.   : 1168
    #>            mts, ts, matrix, array:2    132 x 5 :1   1st Qu.: 1956
    #>  nfnGroupedData, nfGroupedDat....:7    176 x 3 :1   Median : 7672
    #>                                        1860 x 4:1   Mean   :12344
    #>                                        192 x 8 :1   3rd Qu.:12558
    #>                                        21 x 3  :1   Max.   :60824
    #>                                        35 x 3  :1
    #>                                        39 x 4  :1
    #>                                        5 x 4   :1
    #>                                        (Other) :8

## Options

There are a few custom options dedicated to the package. The function `osum.options`, crafted after the `base` package `options`, allows the user to set and examine them. The custom options mainly allow for providing the default values for the specific arguments to the `print` and `summary` methods (`data.class.width`, `format.extent`, and `max.rows`), as seen in Printing and Summarizing.

    # see all current options
    osum.options()
    #> $osum.format.extent
    #> [1] TRUE
    #>
    #> $osum.information
    #> [1] "data.class"   "storage.mode" "mode"         "typeof"       "extent"
    #> [6] "object.size"

    # set some values
    old_opt <- osum.options(osum.data.class.width = 12, osum.max.rows = 25)
    # previous values of the changed 'osum' options
    old_opt
    #> $osum.data.class.width
    #> NULL
    #>
    #> $osum.max.rows
    #> NULL

It is also possible to select what information will be returned by default by the function `objects.summary`. It must be a subset of `c("data.class", "storage.mode", "mode", "typeof", "extent", "object.size")`, partial matching is allowed.

    # set which attributes are retrieved by default
    osum.options(osum.information = c("dat", "mod", "ext", "obj"))
    # get the current value of the option
    osum.options("osum.information")
    #> $osum.information
    #> [1] "data.class"  "mode"        "extent"      "object.size"
    # if the argument 'what' is not specified, the new default values are used
    objects.summary("package:base", filter = data.class != "function")
    #>                   data.class      mode extent object.size
    #> F                    logical   logical      1          56
    #> LETTERS            character character     26        1712
    #> R.version        simple.list      list     14        3168
    #> R.version.string   character character      1         136
    #> T                    logical   logical      1          56
    #> letters            character character     26        1712
    #> month.abb          character character     12         848
    #> month.name         character character     12         880
    #> pi                   numeric   numeric      1          56
    #> version          simple.list      list     14        3168

Created on 2024-08-21.