# vi: fdm=marker

# CONFIGURATION FIELDS {{{1
################################################################################

config:

  allow.huge.downloads:
    title: Authorize download of big files.
    type: logical
    description: If disabled, download of huge files like whole database data is blocked if there is another way to retrieve the data.
    default: TRUE

  autoload.extra.pkgs:
    title: Enable automatic loading of extension packages.
    type: logical
    description: If enabled, all available extension packages will be loaded at start up.
    default: TRUE
      
  cache.all.requests:
    title: Enable caching of all requests and their results.
    type: logical
    description: All requests are cached. If disabled, only requests of entries by accession number are cached.
    default: TRUE

  cache.directory:
    title: Path to the cache folder.
    type: character
    description: The directory in which cache files are stored. The default location depends on your operating system and the choice between the custom persistent cache and the Bioconductor persistent cache.
    default: NULL

  cache.read.only:
    title: Set cache system in read only mode.
    type: logical
    description: If set to TRUE, then the cache system becomes not writable. This is mainly used for test purposes.
    default: FALSE

  cache.subfolders:
    title: Use subfolders to divide files into cache folder.
    type: logical
    description: Use subfolders shortterm and longterm in cache system, in order to divide the downloaded files. If a whole database is downloaded, the file(s) will be put in the longterm subfolders.
    deprecated: Short and long term folders are not used anymore. Now one subfolder is automatically created for each database connector.
    default: TRUE

  cache.system:
    title: Enable cache system.
    type: logical
    description: Cache system is ON.
    default: TRUE

  use.cache.for.local.db:
    title: Enable the use of the cache system also for local databases.
    type: logical
    description: |-
      "If set to TRUE, then the cache system will also be used for connectors to local databases (i.e.: non-remote databases)."
    default: FALSE

  dwnld.chunk.size:
    title: The number of new entries to wait before saving them into the cache.
    type: integer
    description: The number of entries to download before saving to cache. By default, saving to cache is only down once all requested entries have been downloaded.

  dwnld.timeout:
    title: Download timeout in seconds.
    type: integer
    description: The timeout used when downloading big files, in seconds.
    default: 3600
      
  compute.fields:
    title: Enable automatic computing of missing fields.
    type: logical
    description: If the field of an entry is accessed but has no value, then biodb will try to compute one. This is done by following rules that tell biodb in which database to look for this field's value.
    default: TRUE

  factory.cache:
    title: Enable factory cache.
    type: logical
    description: Set the factory cache system ON. The factory cache system stores entry instances already created. When the factory cache is enabled and an entry already created is requested, the factory returns that same instance. This is possible, because biodb uses the R6 OOP system, which uses references instead of object copy. Thus, if you modify an entry and ask the factory for the same entry, it will be the same exact object that will be given to you and it will include your modifications. On the contrary, if the factory cache is OFF, a new entry instance will be returned to you each time. The factory cache enables to speed up entry retrieval when the same entries are requested several times, avoiding the parsing process.
    default: FALSE
    deprecated: The cache is now always enabled. Thus all entries returned are referenced inside the cache and will be returned when needed.

  force.locale:
    title: Force change of current locale for the application.
    type: logical
    description: Forcing current locale is allowed.
    default: TRUE

  longterm.cache.subfolder:
    title: Name of the long term cache subfolder.
    type: character
    description: The name of the long term cache subfolder.
    default: longterm
    deprecated: We do not use anymore a longterm subfolder in cache directory. Cache files are now stored under a different folder for each database.

  msg.caution.lvl:
    title: Maximum level of the caution messages to display.
    type: integer
    description: The desired level of caution messages. Set to 0 to turn messages off.
    deprecated: Caution messages have been replaced by warnings.
    default: 1

  msg.debug.lvl:
    title: Maximum level of the debug messages to display.
    type: integer
    description: The desired level of debug messages. Debug messages are turned off by default.
    deprecated: Debug messages are not handled by the `lgr` package. You can get the biodb `lgr::Logger` instance by calling `biodb::getLogger()`.
    default: 0

  msg.info.lvl:
    title: Maximum level of the information messages to display.
    type: integer
    description: The desired level of information messages. Set to 0 to turn messages off.
    deprecated: Info messages are not handled by the `lgr` package. You can get the biodb `lgr::Logger` instance by calling `biodb::getLogger()`.
    default: 1

  multival.field.sep:
    title: The separator used for concatenating values.
    type: character
    description: The character used as separator when concatenating multiple values of a field.
    default: ';'

  intra.field.name.sep:
    title: The separator use for building a field name.
    type: character
    description: The character to use for separating words inside a field name. When defining or accessing a field, all non alphanumeric characters will be replaced by this character.
    default: '.'

  entries.sep:
    title: The separator used between values from different entries.
    type: character
    description: The character used as separator when concatenating values from different entries.
    default: '|'

  offline:
    title: Stops sending requests to the network.
    type: logical
    description: If set to TRUE, all network accesses are blocked. This is mainly used for test purposes.
    default: FALSE

  persistent.cache.impl:
    title: The implementation to use for the persistent cache.
    type: character
    description: 'Choose either "custom" or "bioc".'
    default: custom

  proton.mass:
    title: The mass of one proton.
    type: numeric
    description: The mass of a proton, in u or Da.
    default: 1.0072765

  shortterm.cache.subfolder:
    title: Name of the short term cache subfolder.
    type: character
    description: The name of the short term cache subfolder.
    default: shortterm
    deprecated: We do not use anymore a shortterm subfolder in cache directory. Cache files are now stored under a different folder for each database.

  svn.binary.path:
    title: The path to the svn binary.
    type: character
    description: The path to the SubVersion binary (svn).

  test.functions:
    title: List of functions to test.
    type: character
    description: A comma separated list of test functions to run during tests. Only those functions will be run.

  useragent:
    title: The application name and contact address to send to the contacted web server.
    type: character
    description: The user agent description string. This string is compulsory when connection to remote databases.

# DATABASES {{{1
################################################################################

databases:

# Compound CSV File {{{2
################################################################################
  comp.csv.file:
    name: Compound CSV File
    description: A connector to handle a compound database stored inside a CSV file. It is possible to choose the separator for the CSV file, as well as match the column names with the biodb entry fields.
    entry.content.type: tsv
    compound.db: true
    editable: true
    writable: true
    searchable.fields:
      - name
      - monoisotopic.mass
      - molecular.mass
      - average.mass
      - nominal.mass

# Compound SQLite {{{2
################################################################################
  comp.sqlite:
    name: Compound SQLite
    description: A connector to handle a compound database stored inside an SQLite file.
    entry.content.type: list
    compound.db: true
    editable: true
    writable: true
    searchable.fields:
      - name
      - monoisotopic.mass
      - molecular.mass
      - average.mass
      - nominal.mass

# Mass CSV File {{{2
################################################################################
  mass.csv.file:
    name: Mass spectra CSV File
    description: A connector to handle a mass spectra database stored inside a CSV file. It is possible to choose the separator for the CSV file, as well as match the column names with the biodb entry fields..
    mass.db: true
    entry.content.type: tsv
    editable: true
    writable: true

# Mass SQLite {{{2
################################################################################
  mass.sqlite:
    name: Mass spectra SQLite
    description: A connector to handle a mass spectra database stored inside an SQLite file.
    mass.db: true
    entry.content.type: list
    editable: true
    writable: true

# FIELDS {{{1
################################################################################

fields:

# General fields {{{2
################################################################################

  accession:
    description: The accession number of the entry.

  description:
    alias: protdesc
    description: The decription of the entry.

  name:
    alias:
    - fullnames
    - synonyms
    card: many
    case.insensitive: true
    description: The name of the entry.
    forbids.duplicates: true
    type: name

# Database IDs {{{2
################################################################################

  cas.id:
    alias: casid
    card: many
    case.insensitive: true
    description: CAS ID
    forbids.duplicates: true
    type: id

  chebi.id:
    description: ChEBI ID
    case.insensitive: true
    forbids.duplicates: true
    type: id
    card: many

  chemspider.id:
    description: ChemSpider ID
    case.insensitive: true
    forbids.duplicates: true
    type: id
    card: many

  comp.csv.file.id:
    description: Compound CSV File ID
    case.insensitive: true
    forbids.duplicates: true
    type: id
    card: many

  comp.sqlite.id:
    description: Compound SQLite ID
    case.insensitive: true
    forbids.duplicates: true
    type: id
    card: many

  expasy.enzyme.id:
    description: ExPASy ENZYME ID
    case.insensitive: true
    forbids.duplicates: true
    type: id
    card: many

  hmdb.metabolites.id:
    description: HMDB Metabolites ID
    case.insensitive: true
    forbids.duplicates: true
    type: id
    card: many

  kegg.compound.id:
    description: KEGG Compound ID
    case.insensitive: true
    forbids.duplicates: true
    type: id
    card: many

  kegg.genes.id:
    description: KEGG Genes ID
    case.insensitive: true
    forbids.duplicates: true
    type: id
    card: many

  mass.csv.file.id:
    description: Mass CSV File ID
    case.insensitive: true
    forbids.duplicates: true
    type: id
    card: many

  mass.sqlite.id:
    description: Mass SQLite ID
    case.insensitive: true
    forbids.duplicates: true
    type: id
    card: many

  ncbi.gene.id:
    description: NCBI Gene ID
    case.insensitive: true
    forbids.duplicates: true
    type: id
    card: many

  ncbi.pubchem.comp.id:
    description: PubChem Compound ID
    case.insensitive: true
    forbids.duplicates: true
    type: id
    card: many

  compound.id:
    alias: compoundid
    card: many
    case.insensitive: true
    description: The compound ID.
    forbids.duplicates: true
    type: id

# Masses {{{2
################################################################################

  average.mass:
    class: double
    description: Average mass, or average molecular weight, or relative molecular mass, or molar mass is defined as the mass of a sample of a compound divided by the amount of substance in that sample. It takes into account the presence of isotopes inside the sample. See https://en.wikipedia.org/wiki/Molar_mass.
    type: mass

  molecular.mass:
    alias:
    - mass
    - molecular.weight
    - compoundmass
    class: double
    description: Molecular mass (also called molecular weight), in u (unified atomic mass units) or Da (Dalton). It is computed from the atomic masses of each nuclide present in the molecule, taking into account the various possible isotops of each atom. See https://en.wikipedia.org/wiki/Molecular_mass.
    type: mass

  monoisotopic.mass:
    alias: exact.mass
    class: double
    description: Monoisotopic mass, in u (unified atomic mass units) or Da (Dalton). It is computed using the mass of the primary isotope of the elements including the mass defect (mass difference between neutron and proton, and nuclear binding energy). Used with high resolution mass spectrometers. See https://en.wikipedia.org/wiki/Monoisotopic_mass.
    type: mass

  nominal.mass:
    class: integer
    description: Nominal mass, in u (unified atomic mass units) or Da (Dalton). It is computed using the mass number of the most abundant isotope of each atom. Typically used with low resolution mass spectrometers. See https://en.wikipedia.org/wiki/Monoisotopic_mass.
    type: mass

# Peak fields {{{2
################################################################################

  peak.attr:
    description: "The chemical attributions of the peaks, in terms of losses and/or aggregations (e.g.: [(M+H)-(H2O)-(NH3)]+)."
    type: peak
    dataFrameGroup: peaks
    card: many
    alias: peakattr

  peak.comp:
    description: The molecular compositions of the peaks.
    type: peak
    dataFrameGroup: peaks
    card: many
    alias: peakcomp

  peak.error.ppm:
    class: double
    description: Peak error in PPM.
    type: peak
    dataFrameGroup: peaks
    card: many

  peak.formula:
    description: The chemical formulae of the peaks.
    type: peak
    dataFrameGroup: peaks
    card: many

  peak.intensity:
    class: double
    description: The absolute intensities of the peaks.
    type: peak
    dataFrameGroup: peaks
    card: many

  peak.mass:
    class: double
    description: Peak mass.
    type: peak
    dataFrameGroup: peaks
    card: many

  peak.mztheo:
    alias: mztheo
    class: double
    description: Peak theoretical M/Z.
    type: peak
    dataFrameGroup: peaks
    card: many

  peak.mzexp:
    class: double
    description: Peak experimental M/Z.
    type: peak
    dataFrameGroup: peaks
    card: many

  peak.mz:
    class: double
    description: Peak M/Z.
    type: peak
    dataFrameGroup: peaks
    card: many
    computable.from:
      - database: self
        fields:
          - peak.mzexp
          - peak.mztheo

  peak.relative.intensity:
    class: double
    description: Peak relative intensity, in percentage (from 0 to 100).
    type: peak
    dataFrameGroup: peaks
    card: many

  peaks:
    class: data.frame
    description: Peaks table.
    virtual: true
    virtual.group.by.type: peak

# Chromatography fields {{{2
################################################################################

  chrom.col.constructor:
    description: Chromatographic column constructor.
  chrom.col.diameter:
    class: double
    description: Chromatographic column diameter.
  chrom.col.id:
    description: Chromatographic column ID.
  chrom.col.length:
    class: double
    description: Chromatographic column length.
  chrom.col.method.protocol:
    description: Chromatographic method protocol.
  chrom.col.name:
    alias:
    - chrom.col
    - chromcol
    description: Chromatographic column name.
  chrom.flow.gradient:
    description: Chromatographic column flow gradient.
  chrom.flow.rate:
    description: Chromatographic column flow rate.
  chrom.rt:
    alias:
    - chromcolrt
    - chrom.col.rt
    class: double
    description: Chromatographic column retention time.
  chrom.rt.max:
    alias: chrom.col.rt.max
    class: double
    description: Chromatographic column retention time maximum.
  chrom.rt.min:
    alias: chrom.col.rt.min
    class: double
    description: Chromatographic column retention time minimum.
  chrom.rt.unit:
    alias: chrom.col.rt.unit
    allowed.values:
    - min
    - s
    description: Chromatographic column retention time unit.
    lower.case: true
  chrom.solvent:
    card: many
    description: Chromatographic column solvent.

# Proteins and genes {{{2
################################################################################

  aa.seq:
    alias: sequence
    description: Amino acids sequence.

  aa.seq.length:
    alias:
    - seq.length
    - length
    class: integer
    description: Length of the amino acids sequence.

  aa.seq.location:
    alias:
    - seq.location
    - location
    description: Location of the amino acids sequence.

  nt.seq:
    description: Nucleotids sequence.

  nt.seq.length:
    class: integer
    description: Length of the nucleotids sequence.

  ec:
    description: Enzyme Commission number. See https://en.wikipedia.org/wiki/Enzyme_Commission_number.
    case.insensitive: true
    forbids.duplicates: true
    card: many

  organism:
    description: The biological organism to which this entry belongs.

  pathway.class:
    card: many
    description: Pathway class.

  catalytic.activity:
    card: many
    description: Catalytic activity.

  cofactor:
    card: many
    description: Cofactor.

  gene.symbol:
    alias:
    - gene.symbols
    - symbol
    - genesymbols
    card: many
    case.insensitive: true
    description: A list of gene symbols.
    forbids.duplicates: true

# Other fields {{{2
################################################################################

  charge:
    class: integer
    description: Charge.
  comp.iupac.name.allowed:
    description: IUPAC allowed name
    type: name
  comp.iupac.name.cas:
    description: IUPAC CAS name
    type: name
  comp.iupac.name.pref:
    description: IUPAC preferred name
    type: name
  comp.iupac.name.syst:
    description: IUPAC systematic name
    type: name
  comp.iupac.name.trad:
    description: IUPAC traditional name
    type: name
  comp.super.class:
    alias:
    - superclass
    - super.class
    description: Compound super class.
  equation:
    description: Chemical equation
  formula:
    description: Empirical chemical formula of a compound.
  composition:
    description: The molecular composition of a compound.
    alias:
      - compoundcomp
  inchi:
    description: International Chemical Identifier (InChI).
  inchikey:
    description: Hash key of the International Chemical Identifier (InChIKey).
  logp:
    class: double
    description: logP
  ms.level:
    class: integer
    description: Mass spectrum level.
  ms.mode:
    alias: msmode
    allowed.values:
      neg:
      - '-'
      - negative
      pos:
      - +
      - positive
    description: Mass spectrometry mode.
    lower.case: true
  msdev:
    description: Mass spectrometer device.
  msdevtype:
    description: Mass spectrometer device type.
  msprecannot:
    description: MS precursor annotation.
  msprecmz:
    card: many
    class: double
    description: MS precursor M/Z value.
  mstype:
    description: Mass spectrometry type.
  nb.compounds:
    alias: nbcompounds
    class: integer
    description: Number of associated compounds.
  nb.peaks:
    alias: nbpeaks
    class: integer
    description: Number of MS peaks.
  products:
    card: many
    description: Products of an enzymatic chemical reaction.
  smiles:
    description: SMILES.
  smiles.canonical:
    description: SMILES canonical.
  smiles.isomeric:
    description: SMILES isomeric.
  substrates:
    card: many
    description: Substrates of an enzymatic chemical reaction.
