BiodbMain: The central class of the biodb package.

In pkrog/biodb: biodb, a library and a development framework for connecting to chemical and biological databases

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

pkrog/biodb documentation built on Nov. 29, 2022, 4:24 a.m.