WoRMStools

Features:

[x] get up-to-date information from WoRMS database
[x] Terminal-based scripts

Software requierements: * Python 3

Installation

By using pip:

pip install WoRMStools

Using git (Optional):

git clone https://github.com/Ulises-Rosas/WoRMStools.git
cd WoRMStools
python3 setup.py install

AphiaID

We can obtain the species ID which WoRMS database identify a given species (i.e. aphiaID). If this ID is not known, then species cannot be validated or continue with downstream procedures. Therefore, to know species aphiaID is an important step towards getting metadata inside WoRMS database.

Let's suppose we have the following a list of species stored at species.txt:

cat species.txt

Conus roosevelti
Latirus hemphilli
Favartia peasei
Lolliguncula panameusis
Pholoides tuberculata

We can obtain their aphiaIDs by running:

worms species.txt -id

By default worms uses its input to name all outputs, however this can be modified with --out option. Since we did not specify any output name, by default the output name is species_worms_aphiaID.tsv and is contains the following:

species aphiaIDs    Obs
Conus roosevelti    429945  
Latirus hemphilli   447141  
Favartia peasei 738152  
Lolliguncula panameusis     Record not found in WoRMS
Pholoides tuberculata       Record not found in WoRMS

Validate names

Currently accepted name according to WoRMS for each species can be obtained with the option -val. The output, when using this option, has the following columns: species, validated names and obs. If there were species that cannot be validated through WoRMS, it is stated on the obs column.

Example:

worms species.txt -val

By default the output name is species_worms_val.tsv and is contains the following:

species validated names Obs
Conus roosevelti    Conus tiaratus  
Latirus hemphilli   Pustulatirus hemphilli  
Favartia peasei Favartia peasei 
Lolliguncula panameusis Lolliguncula (Lolliguncula) panamensis  
Pholoides tuberculata       Record not found in WoRMS

Synonyms

Synonyms of each species can be obtained with the option -syn. This option is aphiaID-dependent, which means that it obtains synonyms if there is any available aphiaID for each given species, including non-accepted ones. The output, when using this option, has the following columns: species, synonyms and obs. If there was a species that are not found in WoRMS its validated name is taken and stated on the obs column. Furthermore, if this species cannot be validated^*, it is also stated in the obs column.

Example:

worms species.txt -syn

By default the output name is species_worms_syn.tsv and is contains the following:

species synonyms    Obs
Conus roosevelti        
Latirus hemphilli       
Favartia peasei Murex foveolatus, Murex peasei  
Lolliguncula (Lolliguncula) panamensis  Lolliguncula panamensis, Lolliguncula tydeus    Deprecated name: Lolliguncula panameusis
Pholoides tuberculata       Record not found in WoRMS

*While species that does not have an aphiaID can be either validated in order to get an aphiaID or simply skipped, it is highly recomendable to introduce a list of validated species (see how here).

Taxonomic rank

Different taxonomical categories can obtained with the option --at. This option is aphiaID-dependent, which means that it obtains taxonomical categories if there is any aphiaID available for each given species, including non-accepted ones. The output, when using this option, varies according to introduced values into --at option (see example). The structure of column names, however, has the following structure: [Taxa] + species + obs. If there was a species that are not found in WoRMS its validated name is taken and stated on the obs column. Furthermore, if this species cannot be validated^*, it is also stated in the obs column.

Example:

worms species.txt --at Class Family

By default the output name is species_worms_ranks.tsv and is contains the following:

Class   Family  Species Obs
Gastropoda  Conidae Conus roosevelti    
Gastropoda  Fasciolariidae  Latirus hemphilli   
Gastropoda  Muricidae   Favartia peasei 
Cephalopoda Loliginidae Lolliguncula (Lolliguncula) panamensis  deprecated name: Lolliguncula panameusis
        Pholoides tuberculata   Record not found in WoRMS

Finally, this option can be used together with all above options.

*While species that does not have an aphiaID can be either validated in order to get an aphiaID or simply skipped, it is highly recomendable to introduce a list of validated species (see how here).

Usage within python3

The way WoRMStools is used inside python3 resemble pretty much as the usage in the terminal we have already seen:

# import worms class
from WoRMStools.worms import Worms

# get aphiaID
Worms(taxon = 'Conus roosevelti').aphiaID

# validate name
Worms(taxon = 'Conus roosevelti').taxamatch()

# get synonyms
Worms(taxon = 'Favartia peasei').get_synonyms()

# get an specific taxonomic rank
Worms(taxon = 'Favartia peasei').get_rank(rank = 'Family')