BiodbMain {biodb} | R Documentation

## The central class of the biodb package.

### Description

The central class of the biodb package.

The central class of the biodb package.

### Details

The main class of the `biodb` package. In order to use the biodb package, you need first to create an instance of this class.

The constructor takes a single argument, `autoloadExtraPkgs`, to enable (`TRUE` or default) or disable (`FALSE`) autoloading of extra biodb packages.

Once the instance is created, some other important classes (`BiodbFactory`, `BiodbPersistentCache`, `BiodbConfig`, ...) are instantiated (just once) and their instances are later accessible through get*() methods.

### Methods

#### Public methods

- `BiodbMain$new()`

- `BiodbMain$terminate()`

- `BiodbMain$loadDefinitions()`

- `BiodbMain$getConfig()`

- `BiodbMain$getPersistentCache()`

- `BiodbMain$getDbsInfo()`

- `BiodbMain$getEntryFields()`

- `BiodbMain$getFactory()`

- `BiodbMain$getRequestScheduler()`

- `BiodbMain$addObservers()`

- `BiodbMain$getObservers()`

- `BiodbMain$convertEntryIdFieldToDbClass()`

- `BiodbMain$entriesFieldToVctOrLst()`

- `BiodbMain$entriesToDataframe()`

- `BiodbMain$entryIdsToDataframe()`

- `BiodbMain$addColsToDataframe()`

- `BiodbMain$entriesToJson()`

- `BiodbMain$collapseRows()`

- `BiodbMain$entriesToSingleFieldValues()`

- `BiodbMain$entryIdsToSingleFieldValues()`

- `BiodbMain$computeFields()`

- `BiodbMain$saveEntriesAsJson()`

- `BiodbMain$copyDb()`

- `BiodbMain$print()`

- `BiodbMain$fieldIsAtomic()`

- `BiodbMain$getFieldClass()`

- `BiodbMain$clone()`

#### Method `new()`

New instance initializer. The BiodbMain must not be instantiated directly. Instead use the newInst() global method.

##### Usage

    BiodbMain$new(autoloadExtraPkgs = NULL)

##### Arguments

`autoloadExtraPkgs`

  Set to TRUE to allow automatic loading of extension packages. Set to FALSE to forbid it. If left to NULL, the default, autoload.extra.pkgs configuration value will be used.

##### Returns

Nothing.

#### Method `terminate()`

Closes \codeBiodbMain instance. Call this method when you are done with your \codeBiodbMain instance.

##### Usage

    BiodbMain$terminate()

##### Returns

Nothing.

#### Method `loadDefinitions()`

Loads databases and entry fields definitions from YAML file.

##### Usage

    BiodbMain$loadDefinitions(file, package = "biodb")

##### Arguments

`file`

  The path to a YAML file containing definitions for \codeBiodbMain (databases, fields or configuration keys).

`package`

  The package to which belong the new definitions.

##### Returns

Nothing.

#### Method `getConfig()`

Returns the single instance of the \codeBiodbConfig class.

##### Usage

    BiodbMain$getConfig()

##### Returns

The instance of the \codeBiodbConfig class attached to this BiodbMain instance.

#### Method `getPersistentCache()`

Returns the single instance of the BiodbPersistentCache class.

##### Usage

    BiodbMain$getPersistentCache()

##### Returns

The instance of the BiodbPersistentCache class attached to this BiodbMain instance.

#### Method `getDbsInfo()`

Returns the single instance of the \codeBiodbDbsInfo class.

##### Usage

    BiodbMain$getDbsInfo()

##### Returns

The instance of the \codeBiodbDbsInfo class attached to this BiodbMain instance.

#### Method `getEntryFields()`

Returns the single instance of the \codeBiodbEntryFields class.

##### Usage

    BiodbMain$getEntryFields()

##### Returns

The instance of the \codeBiodbEntryFields class attached to this BiodbMain instance.

#### Method `getFactory()`

Returns the single instance of the \codeBiodbFactory class.

##### Usage

    BiodbMain$getFactory()

##### Returns

The instance of the \codeBiodbFactory class attached to this BiodbMain instance.

#### Method `getRequestScheduler()`

Returns the single instance of the \codeBiodbRequestScheduler class.

##### Usage

    BiodbMain$getRequestScheduler()

##### Returns

The instance of the \codeBiodbRequestScheduler class attached to this BiodbMain instance.

#### Method `addObservers()`

Adds new observers. Observers will be called each time an event occurs. This is the way used in biodb to get feedback about what is going inside biodb code.

##### Usage

    BiodbMain$addObservers(observers)

##### Arguments

`observers`

  Either an object or a list of objects.

##### Returns

Nothing.

#### Method `getObservers()`

Gets the list of registered observers.

##### Usage

    BiodbMain$getObservers()

##### Returns

The list or registered observers.

#### Method `convertEntryIdFieldToDbClass()`

Gets the database class name corresponding to an entry ID field.

##### Usage

    BiodbMain$convertEntryIdFieldToDbClass(entry.id.field)

##### Arguments

`entry.id.field`

  The name of an ID field. It must end with \".id\".

#### Method `entriesFieldToVctOrLst()`

Extracts the value of a field from a list of entries. Returns either a vector or a list depending on the type of the field.

##### Usage

    BiodbMain$entriesFieldToVctOrLst(
      entries,
      field,
      flatten = FALSE,
      compute = TRUE,
      limit = 0,
      withNa = TRUE
    )

##### Arguments

`entries`

  A list of \codeBiodbEntry instances.

`field`

  The name of a field.

`flatten`

  If set to \codeTRUE and the field has a cardinality greater than one, then values be converted into a vector of class character in which each entry values are collapsed.

`compute`

  If set to \codeTRUE, computable fields will be output.

`limit`

  The maximum number of values to retrieve for each entry. Set to 0 to get all values.

`withNa`

  If set to TRUE, keep NA values. Otherwise filter out NAs values in vectors.

##### Returns

A vector if the field is atomic or flatten is set to \codeTRUE, otherwise a list.

#### Method `entriesToDataframe()`

Converts a list of entries or a list of list of entries (\codeBiodbEntry objects) into a data frame.

##### Usage

    BiodbMain$entriesToDataframe(
      entries,
      only.atomic = TRUE,
      null.to.na = TRUE,
      compute = TRUE,
      fields = NULL,
      limit = 0,
      drop = FALSE,
      sort.cols = FALSE,
      flatten = TRUE,
      only.card.one = FALSE,
      own.id = TRUE,
      prefix = ""
    )

##### Arguments

`entries`

  A list of \codeBiodbEntry instances or a list of list of \codeBiodbEntry instances.

`only.atomic`

  If set to \codeTRUE, output only atomic fields, i.e.: the fields whose value type is one of integer, numeric, logical or character.

`null.to.na`

  If set to \codeTRUE, each \codeNULL entry in the list is converted into a row of NA values.

`compute`

  If set to \codeTRUE, computable fields will be output.

`fields`

  A character vector of field names to output. The data frame output will be restricted to this list of fields.

`limit`

  The maximum number of field values to write into new columns. Used for fields that can contain more than one value. Set it to 0 to get all values.

`drop`

  If set to \codeTRUE and the resulting data frame has only one column, a vector will be output instead of data frame.

`sort.cols`

  Sort columns in alphabetical order.

`flatten`

  If set to \codeTRUE, then each field with a cardinality greater than one, will be converted into a vector of class character whose values are collapsed.

`only.card.one`

  Output only fields whose cardinality is one.

`own.id`

  If set to TRUE includes the database id field named `<database_name>.id` whose values are the same as the `accession` field.

`prefix`

  Insert a prefix at the start of all field names.

##### Returns

A data frame containing the entries. Columns are named according to field names.

#### Method `entryIdsToDataframe()`

Construct a data frame using entry IDs and field values of the corresponding entries.

##### Usage

    BiodbMain$entryIdsToDataframe(
      ids,
      db,
      fields = NULL,
      limit = 3,
      prefix = "",
      own.id = FALSE
    )

##### Arguments

`ids`

  A character vector of entry IDs or a list of character vectors of entry IDs.

`db`

  The biodb database name for the entry IDs, or a connector ID, as a sinle character value.

`fields`

  A character vector containing entry fields to add.

`limit`

  The maximum number of field values to write into new columns. Used for fields that can contain more than one value. Set it to 0 to get all values.

`prefix`

  Insert a prefix at the start of all field names.

`own.id`

  If set to TRUE includes the database id field named `<database_name>.id` whose values are the same as the `accession` field.

`A`

  data frame containing in columns the requested field values, with one entry per line, in the same order than in `ids` vector.

#### Method `addColsToDataframe()`

Add values from a database to an existing data frame using a column containing entry identifiers.

##### Usage

    BiodbMain$addColsToDataframe(x, id.col, db, fields, limit = 3, prefix = "")

##### Arguments

`x`

  A data frame containing at least one column with Biodb entry IDs identified by the parameter `id.col`.

`id.col`

  The name of the column containing IDs inside the input data frame.

`db`

  The biodb database name for the entry IDs, or a connector ID, as a single character value.

`fields`

  A character vector containing entry fields to add.

`limit`

  The maximum number of field values to write into new columns. Used for fields that can contain more than one value. Set it to 0 to get all values.

`prefix`

  Insert a prefix at the start of all field names.

##### Returns

A data frame containing `x` and new columns appended for the fields requested.

#### Method `entriesToJson()`

Converts a list of \codeBiodbEntry objects into JSON. Returns a vector of characters.

##### Usage

    BiodbMain$entriesToJson(entries, compute = TRUE)

##### Arguments

`entries`

  A list of \codeBiodbEntry instances. It may contain NULL elements.

`compute`

  If set to \codeTRUE, computable fields will added to JSON too.

##### Returns

A list of JSON strings, the same length as entries list.

#### Method `collapseRows()`

Collapses rows of a data frame, by looking for duplicated values in the reference columns (parameter `cols`). The values contained in the reference columns are supposed to be ordered inside the data frame, in the sens that all duplicated values are supposed to directly follow the original values. For all rows containing duplicated values, we look at values in all other columns and concatenate values in each column containing different values.

##### Usage

    BiodbMain$collapseRows(x, sep = "|", cols = 1L)

##### Arguments

`x`

  A data frame.

`sep`

  The separator to use when concatenating values in collapsed rows.

`cols`

  The indices or the names of the columns used as reference.

##### Returns

A data frame, with rows collapsed."

#### Method `entriesToSingleFieldValues()`

Extract all values of a field from a list of entries.

##### Usage

    BiodbMain$entriesToSingleFieldValues(
      entries,
      field,
      sortOutput = FALSE,
      uniq = TRUE
    )

##### Arguments

`entries`

  A list of BiodbEntry objects.

`field`

  The field for which to extract values.

`sortOutput`

  Set to TRUE to sort the values.

`uniq`

  Set to TRUE to remove duplicates.

##### Returns

The values of the field as a vector.

#### Method `entryIdsToSingleFieldValues()`

Extract all values of a field from a list of entries.

##### Usage

    BiodbMain$entryIdsToSingleFieldValues(
      ids,
      db,
      field,
      sortOutput = FALSE,
      uniq = TRUE
    )

##### Arguments

`ids`

  A list of entry identifiers.

`db`

  The database ID or connector ID where to find the entries.

`field`

  The field for which to extract values.

`sortOutput`

  Set to TRUE to sort the values.

`uniq`

  Set to TRUE to remove duplicates.

##### Returns

The values of the field as a vector.

#### Method `computeFields()`

Computes missing fields in entries, for those fields that are comptable.

##### Usage

    BiodbMain$computeFields(entries)

##### Arguments

`entries`

  A list of \codeBiodbEntry instances. It may contain NULL elements.

##### Returns

Nothing.

#### Method `saveEntriesAsJson()`

Saves a list of entries in JSON format. Each entry will be saved in a separate file.

##### Usage

    BiodbMain$saveEntriesAsJson(entries, files, compute = TRUE)

##### Arguments

`entries`

  A list of \codeBiodbEntry instances. It may contain NULL elements.

`files`

  A character vector of file paths, the same length as entries list.

`compute`

  If set to \codeTRUE, computable fields will be saved too.

##### Returns

Nothing.

#### Method `copyDb()`

Copies all entries of a database into another database. The connector of the destination database must be editable.

##### Usage

    BiodbMain$copyDb(conn.from, conn.to, limit = 0)

##### Arguments

`conn.from`

  The connector of the source datababase to copy.

`conn.to`

  The connector of the destination database.

`limit`

  The number of entries of the source database to copy. If set to \codeNULL, copy the whole database.

##### Returns

Nothing.

#### Method `print()`

Prints object information.

##### Usage

    BiodbMain$print()

##### Returns

Nothing.

#### Method `fieldIsAtomic()`

DEPRECATED method to test if a field is an atomic field. The new method is \codeBiodbEntryField :isVector()."

##### Usage

    BiodbMain$fieldIsAtomic(field)

##### Arguments

`field`

  The name of the field.

##### Returns

TRUE if the field's value is atomic.

#### Method `getFieldClass()`

DEPRECATED method to get the class of a field. The new method is `BiodbMain :getEntryFields()$get(field)$getClass()`.

##### Usage

    BiodbMain$getFieldClass(field)

##### Arguments

`field`

  The name of the field.

##### Returns

The class of the field.

#### Method `clone()`

The objects of this class are cloneable with this method.

##### Usage

    BiodbMain$clone(deep = FALSE)

##### Arguments

`deep`

  Whether to make a deep clone.

### See Also

`BiodbFactory`, `BiodbPersistentCache`, `BiodbConfig`, `BiodbEntryFields`, `BiodbDbsInfo`.

### Examples

    # Create an instance:
    mybiodb <- biodb::newInst()

    # Get the factory instance
    fact <- mybiodb$getFactory()

    # Terminate instance.
    mybiodb$terminate()
    mybiodb <- NULL

[Package biodb version 1.2.2 Index]