To import taxonomic
names you have two options. Either use an
import taxonomic names including evaluation of names
according to codes like ICBN and automatic splitting of the names or a
generic 
import wizard
providing the additional possibilty to import synonyms and
hierarchies.
To import taxonomic
names, choose Data → Import taxonomic names
… from the menu. A window as shown below will open. Choose the
encoding of your datasource, that means if your datasource was encoded
with ASCII or a unicode format. To ensure a correct import of special
signs please provide resp. convert your data in one of the available
formats. You must choose a Project, in which your data should be
imported. You may choose a Taxon list and a Datasource and if
the names should be imported as accepted.
If there are
additional columns in the source file (separated by tab) you may add
these unsing the Add column 
button (see below)
in the sequence as found in the source file. The additional columns will
be included in the analysis of the data as shown below. To remove a
column use the 
button.
To start the
analysis of the data, just click on the 
button to
open the source file. If you want to re-analyse a file with new
settings, click on the 
button. To send a
feedback, use the 
button. If the names
should be linked to higher taxa, check the Link taxa to genera if
present option. The names can be compared with existing names within
the current project or the whole database. If you compare the names with
the whole database, you can insert a link for the current project for
identical names that are missing in the project.
Your names will be listed as shown in the image above. If an error (e.g. special signs converted with the wrong encoding)
or a similar name
or an identical name
is found these will be marked as shown above and the names of your list will not be imported unless you check the according field (second column - Import name). If you changed one of the options, click on the Requery button to see the result.
To start the import,
click on the according button Start
import.
With this import routine, you can import data from text files (as
tab-separated lists) into the database. Choose Data → ImportWizard
and then the type of data that should be
imported, e.g. 
Import Taxa … from the
menu. A window as shown below will open that will lead you through the
import of the data. The window is separated in 3 areas. On the left
side, you see a list of possible data related import steps according to
the type of data you choosed for the import. On the right side you see
the list of currently selected import steps. In the middle part the
details of the selected import steps are shown.
As a first step, choose the File from where the data
should be imported. The currently supported format is tab-separated text. Then choose the Encoding
of the file, e.g. Unicode. The Start line and End line will
automatically be set according to your data. You may change these to
restrict the data lines that should be imported. The not imported
parts in the file are indicated as shown below with a gray
background. If the 
First line contains the
column definition this line will not be imported as well. If your data
contains e.g. date information where notations differ between countries
(e.g. 31.4.2013 - 4.31.2013), choose the Language / Country to
ensure a correct interpretation of your data. Finally you can select a
prepared Schema (see chapter Schema below) for the import.
In the selection list on the left side of the window (see below) all possible import steps for the data are listed according to the type of data you want to import.
The import of certain tables can be paralleled. To add parallels click
on the button (see below). To remove parallels, use
the 
button. Only selected ranges will appear in
the list of the steps on the right (see below).
To import informations of logging columns like who created and changed
the data, click on 
button in the header line.
This will include a additional substeps for every step containing the
logging columns (see below). If you do not import these data, they will
be automatically filled by default values like the current time and
user.
You can either import your data as new data or
Attach them to data in the database. Select the import step
Attachment from the list. All tables that are selected and
contain columns at which you can attach data are listed (see below).
Either choose the first option 
Import as
new data or one of the columns the attachment columns offered like
SeriesCode in the table Series in the example below.
If you select a column for attachment, this column will be marked with a blue background (see below and chapter Table data).
You can either import your data as new data or
Merge them with data in the database. Select the import step
Merge from the list. For every table you can choose between
Insert, 
Merge, 
Update and
Attach (see below).
The Insert option will import the data
from the file independent of existing data in the database.
The Merge option will compare the data
from the file with those in the database according to the
Key columns (see below). If no matching data are
found in the database, the data from the file will be imported,
otherwise the data will be updated..
The Update option will compare the data
from the file with those in the database according to the
Key columns. Only matching data found in the
database will be updated.
The Attach option will compare the data from
the file with those in the database according to the
Key columns. The found data will not be changed, but used as a
reference data in depending tables.
To set the source for the columns in the file, select the step of a
table listed underneath the Merge step. All
columns available for importing data will be listed in the central part
of the window. In the example shown below, the first column is used to
attach the new data to data in the database.
A reminder in the header line will show you what actions are still needed to import the data into the table:
= No
column has been selected so far.
=
If data will be imported depends on the content of decisive colums, so
at least one must be selected.
=
The position in the file must be given if the data for a column should
be taken from the file.
= For all merge types other than insert columns for comparision with
data in the database are needed. = For every you have
to decide whether the data are taken from the file or a value is
entered for all
= You have
to select a value from the provided list
= You have to enter a
value used for all datasetsThe handling of the columns in described in the chapter columns.
To test if all requirements for the import are met use the
Testing step. You can use a certain line in
the file for you test and then click on the Test data in line:
button. If there are still unmet requirements, these will be listed in a
window as shown below.
If finally all requirements are met, the testing function will try to write the data into the database and display any errors that occurred as shown below. All datasets marked with a red background, produced some error.
To see the list of all errors, double click in the error list window in the header line (see below).
If finally no errors are left, your data are ready for import. The
colors in the table nodes in the tree indicate the handling of the
datasets: INSERT, MERGE, UPDATE, No difference. Attach, No data. The colors of the
table colums indicate whether a colum is decisive , a key column
or an attachment column
.
If you suspect, that the import file contains data allready present in
the database, you may test this an extract only the missing lines in a
new file. Choose the attachment column (see chapter Attaching data) and
click on the button Check for allready present data. The data
allready present in the database will be marked red (see below). Click
on the button Save missing data a text file 
to
store the data not present in the database in a new file for the import.
Please keep in mind, that this comparision will be performed without any transformations of the data, that
means the data in the file must match exactly those in the database.
With the last step you can finally start to import the data into the database. If you want to repeat the import with the same settings and data of the same structure, you can save a schema of the current settings (see below).
| Schedule for import of tab-separated text files into DiversityTaxonNames | |||
| Target within DiversityTaxonNames: TaxonName | |||
| Schedule version: | 1 | Database version: | 02.05.14 |
| Lines: | 3 - 5 | First line contains column definition: | ? |
| Encoding: | ANSI | Language: | US |
Tables
TaxonName
(TaxonName)
Merge handling: Merge
| Column in table | ? | Key | Copy | Pre | Post | File pos. | Transformations | Value | Source | Table |
|---|---|---|---|---|---|---|---|---|---|---|
| NameID | 2027929 | Interface | ||||||||
| TaxonomicRank | fam. | Interface | ||||||||
| GenusOrSupragenericName | ? | ? | 0 | File | ||||||
| NomenclaturalCode | 3 | Interface |
TaxonNameProject
(TaxonNameProject)
Parent: Merge
| Column in table | ? | Key | Copy | Pre | Post | File pos. | Transformations | Value | Source | Table |
|---|---|---|---|---|---|---|---|---|---|---|
| NameID | ParentTable | |||||||||
| ProjectID | ? | ? | 58 | Interface |
TaxonAcceptedName_1
(TaxonAcceptedName)
Parent: TaxonNameProject
Merge handling: Insert
| Column in table | ? | Key | Copy | Pre | Post | File pos. | Transformations | Value | Source | Table |
|---|---|---|---|---|---|---|---|---|---|---|
| ProjectID | ParentTable | |||||||||
| NameID | ParentTable |
Lines that could not be imported will be marked with a red background while imported lines are marked green (see below).
If you want to save lines that produce errors during the import in a separate file, use the Save failed lines option. The protocol of the import will contain all settings acording to the used schema and an overview containing the number of inserted, updated, unchanged and failed lines (see below).
This tutorial demostrates the import of a small file into the database. The example file is included in the software. At the end of this tutorial you will have imported several datasets and practiced most of the possibilities provided by the import wizard. The import is done in several steps to demonstrate the functionality of the wizard. Please keep in mind, that this tutorial will only work as shown, if the names contained in the file are not already present in the database.
Choose Data → Import Wizard →
import Taxa … from the menu. A window as
shown here below will open. Click on the
button to open the file ImportTutorial.txt
shipped with this application. In addition to the preselected steps,
select the step 
Common names to import the
common name contained in the file. In the
Merging step leave all tables as Insert (see below).
In the Taxon step, set the first
column NameID to
Generate new value. Then select the additional columns as shown below.
For the column TaxonomicRank choose
For all and select species from the list.
For the column NomenclaturalCode choose
For all and select Botany (incl. Mycology)
from the list. All columns besides NameID,
NomenclaturalCode and TaxonomicRank are set on
From file and the colums are set as shown in
the image below.
The column CombiningAuthors needs a
transformation. To add this, click on
the 
button. Enter a translation as shown below
where the value NULL is translated to nothing.
Select a translation transformation (click on the
button) and press the
button to enter a translation (see below).
Press Test the transformation to visualize how the data would be imported (see below).
To allow the import of this table, choose the 2 columns GenusOrSupragenericName and SpeciesEpithet as Decisive columns (see below).
In the step Common name choose the
column CommonName as
Decisive column and
From file (column 6) for and For all for the
other 3 columns as shown in the image below.
In the step 
Project select
For all and the project DiversityWorkbench
from the list and select this column as
Decisive column.
In the step 
Accepted name no further
action is needed.
In the step Testing check if you missed
any settings described above. A test should return a result as shown
below.
Finally Import the taxa. If no errors occur,
the import should return a result as shown below.
To import the hierarchy, the higher taxa must be imported first. Choose
the same file as in the first step for the import. The data for the
higher taxa are not unique in the file. Therefore in the
Merging step, choose
Merge for all tables (see below).
In the Taxon step, set the first
column NameID to
Generate new value. Then select the column
TaxonomicRank and choose For all and
select family from the list. Finally select the column
GenusOrSupragenericName, set it as Decisive columns, set it on
From file and the column 1 as source (see
below).
In the step Project select
For all and the project DiversityWorkbench
from the list and select this column as
Decisive column.
In the step Accepted name no futher
action is needed.
Finally Import the
taxa. If no errors occur, the import should return a result as shown
below. Only the green lines are imported. The yellow lines are found
identical to the already imported data and are therefore not imported.
Next we Import the
order. Follow the steps as described for the family above with the
difference that now for TaxonomicRank we
select order from the list and choose column
0 as source for the column GenusOrSupragenericName taxa. If no errors
occur, the import should return a result as shown below. Only the green
lines are imported. The yellow lines are found identical to the already
imported data and are therefore not imported (see below).
To import the hierarchical relation between the taxa choose Data →
Import Wizard →
Import Hierarchy … from the menu. For every hierarchical rank, you
have to import the relations between the taxa. We start with the
relations from the species to the family (the genus as intermediate rank
between species and family is omitted in this example).
As described in the previous steps, open the file ImportTutorial.txt
shipped with this application. In the Merging
step leave the table on Insert (see
below).
In the Hierachy step, select the
columns Taxon (Name or ID) and Higher taxon (Name or ID) as
Decisive
columns (see below).
For the column ProjectID, select
For all as shown below and select the
project of your choice from the list (e.g. DiversityWorkbench if
available).
As the file does not contain the IDs of the name, we let the program
determine the ID on basis of the name. To enable the program to detect
the ID we need to provide the whole name from the data in the file. We
start with the column Taxon (Name or ID). As
first step, click on the button to set the
source for the genus, the first part of the taxonomic name. A window as
shown below will open. Mark the column as shown below an click on the
OK button.
Next we need the species epithet as second part of the names. Click on
the button to add another column. A window as shown
below will open where where the previous selected column for the Genus
is marked with 1. We select the column containing the species epithet
(see below) and click OK.
Now we need the authors as last part of the names. Again click on the
button to add a column and select the source as
shown below.
As shown below, enter a space in the Postfix for the first 2 columns.
If combining authors do exist for a name, the authors of the basionym
are set in brackets. To ensure the correct build-up of the name, we need
to add a transformation. Click on the button to
enter the a 
filter as shown below where an
opening bracket ( is inserted in dependence of the content of the
column of the combining authors.
To set the column for the filter, click on the
button and choose the column containing the
combining authors as shown below.
The final Transformation should look like shown below.
After adding the optional opening bracket we add the authors of the
basionym. Click on the button and select the column
as shown below.
As final step for the authors of the basionym we need the optional
closing bracket. Click on the button and select the
column as shown above. For the new colum enter another
filter transformation as
shown below. To set the column for the filter, click on the
button as described for the opening bracket.
Finally we need the combining authors, provided they do exist. Click on
the button and select the column containing the
combining authors. As these are missing for some names we have to add a
transformation where the content NULL is
translated into nothing. Click on the button to
add a transformation and in the window that will open, click on the
button to add a translation (see below).
To add a value that should be translated, click on the
button and type NULL into the window as shown below.
The final transformation should look like shown in the image below.
The final build-up for the Taxon should look like in the image below.
Now we enter the higher taxon, in this example the family. Click on the
button and choose the column containing the
family as shown below.
Now the Hierarchy step is finished and
should look like shown below.
In the Testing
steps use the test for a check if you missed any settings described
above. The result of the test should appear like shown below.
Finally Import the
data according to your settings. The result of the import should appear
like shown below.
After the relations between the species and the families are imported we
proceed with the hierarchical relation between families and the order.
Choose Data → Import Wizard →
Import Hierarchy … from the menu.
As described in the previous steps, open the file ImportTutorial.txt
shipped with this application. In the Merging
step set the table on Merge (see below).
As described in the previous step, select the project of your choice and
set the columns Taxon and Higher Taxon to From
file.
Click on the button to select the source for
the family (see below).
… and the orders as shown below.
Additionally you must select these columns as Key
columns, used to compare the data from the file with the content in
the database (see below).
A final test before importing the data turns positive (see below).
Now we are ready to import the relation into the database. For every family this relation will be imported only once (see below).
As a last step, search for the highest taxon “Russulales” in the hierarchy in the main from and click on the button set hierarchy (see below) .
After the hierarchy for the Russulales is set, all imported name will show the complete hierarchy as shown in the example below.
To import the synonyms, choose Data → Import
Wizard → 
import Synonyms … from the
menu. A window as shown below will open.
In the Taxon step choose
From file for the Genus and select the colums
Synonym1 as shown below.
To get only the genus from the name in the source, add a transformation
for the column. Click on the button and in the
window as shown below add a 
cutting transformation.
Enter a space as Splitter. A Test of the transformation should produce
the result as shown below.
Next select the SpeciesEpithet and again
From file (see below).
Select the same column as for the genus (see below).
… and as for the genus add a cutting
transformation with a space as splitter but this time set the
Position to 2 (see below).
Choose the columns for the genus and the epithet as
Decisive columns (see below). Next we turn to the authors of the
synonym. Select the From file for BasionymAuthors …
And choose the SynonymAut1 Column as shown below.
To cut out the basionym authors we add a cut
transformation as shown below. Enter ) as splitter.
Next we add a 
Replace transformation to get
rid of the leeding bracket (see below).
Now we turn to the combining authors …
Again we add a cut transformation with ) as
Splitter, but 2 as Position (see below).
The window now should look like below.
As a last entry in the taxon step we choose Botany for the Nomenclatural Code (see below).
In the Project step select
For all, choose the project where you
want to import the data and set this column as
Decisive column.
In the Synonymy step select
From file for the accepted name. Now we
must combine the accepted name from the entries in the file to match the
entry in the database.
Select the Genus column for the first part of the accepted name (see below).
Click on the button to add another column and choose
the Species column as shown below as source.
For both columns enter a space into the Postfix (see below).
Next we add the authors. For the basionym authors we need to add brackets if combining authors do exist. Select the Author column …
… and add a filter transformation (see below).
Here we choose Import fixed value and
enter ( as a value. As condition we choose that the colum of the
combining autors should not contain the string NULL.
To complete this transformation click on the
button and select the column containing the combining authors (see
below).
To add the basionym authors themselves, click on the button and choose the corresponding source as shown below.
Next we need the closing bracket for the basionym authors. As before we
click on the button and for the new entered columns we add a
filter transformation as shown below. Enter )
as fixed value and as before select that the source for the combining
authors should be unequal to NULL.
Finally we get the values for the combining authors. Add another column and select the corresponding column in the source (see below).
To remove the NULL value, we add a translation transformation. As only string that should be translated, we click on the button and enter NULL (see below).
Now the translation should look like below.
As final action in the Synonym step we
choose the column for the Acc.name as Decisive column (see below).
A final Testing will detect any missed
settings.
After the final test is passed, we can Import
the data as shown below. The schema will automatically be created and is
available for subsequent imports.
