selectedFields: The "selected" fields of a humdrumR object

In Computational-Cognitive-Musicology-Lab/humdrumR: humdrumR

The "selected" fields of a humdrumR object

Description

Every humdrumR object will have, at any given time, one or more of its fields "selected." The selected fields are the fields that are shown when a humdrumR object prints on the console. (At the bottom of the printout, the selected fields are also marked by a *.) The selected fields can also be queried directly using the selectedFields() function, or by inspecting the output of fields(). The selected fields also play other important roles in humdrumR (see details).

Usage

selectedFields(humdrumR)

## S3 method for class 'humdrumR'
select(.data, ..., fieldTypes = "any")

Arguments

humdrumR, .data	HumdrumR data. Must be a humdrumR data object.
...	Which fields to output. If no arguments are provided, the Token field is selected. These arguments can be any combination of character strings, numbers, or symbols used to match fields in the humdrumR input using tidyverse semantics. Unlike in tidyverse select(), field names can be partially matched. You can also include character strings partially matching "Data", "Structure", "Interpretation", "Formal", "Reference" or "Grouping", which will select all fields of those types (see fields() for further explanation).
fieldTypes	Which field types are available for numeric selecting? Defaults to "any", so all fields are counted for numeric selection. Must be a character vector. Legal options are "Data", "Structure", "Interpretation", "Formal", "Reference", "Grouping", and "any", corresponding to the Type column in the output of fields(). Types can be partially matched—for example, "S" for "Structure".

Details

The "selected" fields play an important role in humdrumR. In addition to controlling what fields() you "see" in the console printout, the select fields are the fields that many humdrumR functions will automatically apply themselves to. For example, if you call ditto(), timecount(), or kern() on a humdrumR data object, these functions will be applied the selected field(s). (However, most such functions are only applied to the first selected field, if there is more than one; see their own manuals for details.) The first selected field is also passed as the hidden . variable in calls to with()/within()/, mutate()/summarize()/reframe()—so if you don't remember what fields are selected you can just put a .!

The selected fields also have a role in identifying "null" data. Whenever new fields are selected, their data tokens are checked for NA values or null tokens ("."). Anywhere where all the selected fields are null, the Type field is updated to "d"; wherever any field is not null, the Type field is updated to "D". Many functions ignore d (null data) tokens by default, so selecting fields can be a way controlling which data you want to analyze and which you don't.

Selecting fields

Fields can be selected using the tidyverse select() function, and can use any of select()'s special select features. If you call select() with no argument, the original Token field is selected by default.

If you use select() with a numeric selections or, like select(1:3), fields are numbered in the (row) order shown in call to fields(). Fields are always sorted first by Type (Data first), then by name. If you provide a fieldTypes argument, the numeric selection is reduced to only those fields you choose, matching with the row-numbers you'd see if you call fields(humData, fieldTypes = ...). So, for example, select(humData, 1:3, fieldTypes = 'Structure') will select the first three structural fields. You can also simply provide the keywords "Data", "Structure", "Interpretation", "Reference", or "Formal" to select all fields of each field type.

Note that when you call select() on humdrumR data, the selected field(s) change in place, meaning that the selection changes even if you don't (re)assign the output!

See Also

Use fields() to see what fields are available, and how they are ordered. To actually extract fields, see pullFields().

Examples

humData <- readHumdrum(humdrumRroot, "HumdrumData/BachChorales/chor00[1-4].krn")

# see what is selected
selectedFields(humData)

# change selection
humData |> select(Spine, Record, Token) |> selectedFields()

humData |> select(Structure)

humData |> select(4)
humData |> select(1:3, fieldTypes = 'Structure')

# effect of selection

humData |> select(Token) |> count()
humData |> select(Spine) |> count()

Computational-Cognitive-Musicology-Lab/humdrumR documentation built on Oct. 22, 2024, 9:28 a.m.