source: branches/lib/GDEHELP/HELP_WRITTEN/import_calc.help

Import from calc-sheets

OCCURRENCE

        ARB/File/Import/Import fields from calc-sheet

DESCRIPTION

        Allows to import data from calc-sheets.

        Your data HAS TO contain a column which allows
        to identify a species in arb, i.e. a column
        containing a unique identifier (e.g. the arb species id ('name')
        or the 'acc' field).

        Workflow:

          * export your calc-sheet in
            * .csv format (comma separated values) or
            * .tsv format (tab separated values),
          * select that file at "Import from CSV",
          * select format type,
          * select which sheet-column/arb-field combination
            identifies the target species,
          * select the match-mode (use '=' to check for equality; see below for details).

        Each execution of this function does import the cells of ONE column
        from your file. For each step select

          * sheet-column to import and
          * target-field desired.

        Additional options:

          * how to handle non-matching sheet-rows.
          * whether to ignore rows where matching cell is empty.
          * import scope (marked/all).
          * set marks of modified species.
          * field type.

MATCHMODE

        The 'match mode' property allows to fine-tune how the target species
        identification is done.

        The default setting of 'match mode' is '='.
        It triggers if the cell content in the selected sheet column matches the
        content of the selected arb field.

        Other supported settings require to define how cell and field shall be
        analyzed and compared.

        Each of these two possible definitions has to start with the
        character 'c' or 'f' (referring the target of the definition: 'cell'
        or 'field'), followed by either

          * an '=', if that target shall be interpreted as single entry,
          * the character 'w' followed by a separator character, if the target
            shall be interpreted as list of multiple entries, or
          * the character 'd' also followed by a separator character.
            Same as 'w' above, but ignores duplicated
            entries, instead of aborting with error.

        In the two latter cases, each entry from that list gets compared versus the
        other definition (i.e. 'column' versus 'field' or vv.).
        Depending on the other definition, this either

          * compares a single entry with all entries of a list, or
          * all combinations of all entries of two lists.

        These comparisons are performed for all combinations of table cells and
        species in the database.

        The import algorithm requires that each species in the database matches
        at most with one table row.
        The cells are required to contain unique content in case mode 'c=' is used.
        If the cells are interpreted as lists of entries (using 'cw' or 'cd'),
        the comparison succeeds if one of multiple entries does match.
        Entries occurring in multiple cells can be regarded as "noise" and will be
        ignored, if mode contains 'cd' instead of 'cw'.
        If multiple matches occur (i.e. single entries extracted from one species
        match multiple table rows), the importer aborts with an error.

        Please note that opposed to what has been said in the previous section,
        the importer allows that multiple species get assigned to the same table row.

        Examples:

          * 'f=cw;'
          * 'fw;cw/'
          * 'fw;cd;'

NOTES

        The reverse dataflow is available
        via LINK{arb_export_nds.hlp}.