Package: phylosophos
PhyloSophosA python-based high-throughput scientific name mapping algorithmTable of contentsIn a nutshellSummarySystem requirementsInstallation guideInitialization guideTaxonomic reference update guideUsage guideResult format guideCiting PhyloSophosLicenseContactIn a nutshellpip install phylosophos

python [initialization script name] [optional_update_parameter]

python [processing script name] [[optional_parameter_type] [optional_parameter_value]]SummaryPhyloSophos is a high-throughput scientific name processor package which achieves greater mapping performance by referencing multiple taxonomic references and recognizing the semantic structure of scientific names. It also corrects common Latin variants and vernacular names, which often appear in various biological databases and resources.Please refer tophylosophos_guide.pdffor detailed information on the github repository and instructions on how to use and modify it.System requirementsStoragePhyloSophos requires a minimum of approximately 6.0GB of storage space for downloading and processing the metadata of three taxonomic reference databases (CoL, EoL, NCBI taxonomy) into base reference files. Importing GBIF adds an additional 7.0GB of storage space to accommodate its data.MemoryPhyloSophos requires a minimum of 8GB RAM for conducting taxonomic mapping with three base reference files. An additional 8GB RAM is required for incorporating GBIF reference.Installation guidePhyloSophos requires Numpy, along with other basic libraries of Python 3. Before initializing PhyloSophos to fit with your environment, please set up an environment with a python version >=3.8 (preferably with Conda), and install numpy (https://numpy.org/install/) as appropriate.conda create -n "phylosophos" python>=3.8

conda activate phylosophosPhyloSophos is available via PyPI. please install PhyloSophos as:pip install phylosophosInitialization guideA function for initialization and update isphylosophos.phylosophos_initialize_update.initialize_update(). This script will download raw taxonomic metadata from Catalogue of Life (CoL), Encyclopedia of Life (EoL), and NCBI Taxonomy, process it into reference files, and place it within the working directory.You may download and utilizephylosophos_initialize_update.pyscript file within GitHub repository for your convenience. This script has the following structure:from phylosophos import phylosophos_initialize_update

phylosophos_initialize_update.initialize_update()You may execute this script as:python phylosophos_initialize_update.py [optional_update_parameter]For initialization purposes, the optional parameter will not affect downstream processes. It is possible for Catalogue of Life and Encyclopedia of Life to change the name of the metadata file in their FTP server. In addition, there was an instance when the taxonomic databases changed the format of their metadata, making the initialization script non-functional. If any of these cases happen, please notify me immediately (see contact information).Taxonomic reference update guideAgain, taxonomic reference update uses the samephylosophos.phylosophos_initialize_update.pyscript. You may execute this script as:python phylosophos_initialize_update.py 1In this case, optional update parameter affects the downstream process: by default, if a database metadata file is found in the/external filesdirectory, the metadata download step is skipped to reduce processing time (allowing manual download of reference metadata). If an integer value other than 0 is given as an optional argument, the update script will start downloading the reference metadata file, overriding any pre-existing data.Usage guideA function for PhyloSophos analysis isphylosophos.phylosophos_core.phylosophos(). You may download and utilizephylosophos_core.pyscript file within GitHub repository for your convenience. This script has the following structure:from phylosophos import phylosophos_core

phylosophos_core.phylosophos()Please make sure to put your input file inside the/inputdirectory before proceeding. You may execute this script as:python phylosophos_core.py [[optional_parameter_type] [optional_parameter_value]]PhyloSophos currently recognizes five types of optional parameters.Help (-h, -help, -guide): if one of these arguments is given, a hard-coded guide to PhyloSophos will appear in the console. This will provide simple instructions on how to customize PhyloSophos mapping parameters. No following parameter value is required.Reference type change (-r, -ref): if one of these arguments is given, PhyloSophos will change the database of choice to the one specified by the following argument. The default setting is 'ncbi', while 'col' and 'eol' are also available in basic PhyloSophos system. You may change the default setting by modifying/ps_init/ps_initialize.py(see lines 56, 60 & 62). If you want to include other types of references into PhyloSophos system, please read chapter 6.Input type change (-i, -input): if one of these arguments is given, along with the name of the input file, PhyloSophos will specifically import the given file as an input. If not (as a default setting), PhyloSophos will consider all files within the/inputdirectory to be scientific name input files.Levenshtein distance cutoff (-l, -lev, -cutoff): if one of these arguments is given, along with an integer value, PhyloSophos will change the edit distance cutoff (default setting = 3) to the specified value.Manual curation status (-m, -manual, -curation): if one of these arguments is given, along with a value 1, PhyloSophos will import/pp_learning/manual_curation_list.tsvand utilize this information to pre-process inputs. If not (as a default setting), PhyloSophos will not import extra information other than reference data files within /pp_ref directory.The following is the example result of executing PhyloSophos with a sample input file (sample_scientific_name_inputs.txt), which includes 4,010 scientific name strings.(base) D:\project\phylosophos>python phylosophos_core.py -ref ncbi -cutoff 3
#### PhyloSophos initialization started ####
## Reference type: ncbi
## Input type: default directory
## Levenshtein cutoff: 3
## Manual curation data usage: False
#### PhyloSophos analysis started ####
#### Input file import completed ####
#### Reference file import completed ####
- sample_scientific_name_inputs.txt 4010 analysis completed
#### PhyloSophos analysis completed ####

(base) D:\project\phylosophos>Result format guideThe results of the PhyloSophos analysis will be deposited in the/resultdirectory. The name of the result file will bephylosophos_result_[export_date]_[export_time]_[input_file_name]. [export_date] and [export_time] will be six-digit numbers.The following is an excerpt from the example result file generated by executing PhyloSophos with a sample input file (sample_scientific_name_inputs.txt).Input_file_nameInput_original_orderRaw_name_inputPre_corrected_inputChosen_referenceChosen_reference_mapped_IDChosen_reference_scientific_nameChosen_reference_mapping_status_codeChosen_reference_mapping_status_descriptioncol_mapped_IDcol_scientific_namecol_mapping_status_codeeol_mapped_IDeol_scientific_nameeol_mapping_status_codegbif_mapped_IDgbif_scientific_namegbif_mapping_status_codencbi_mapped_IDncbi_scientific_namencbi_mapping_status_codeManual_curation_recommendedsample_scientific_name_inputs.txt1Abelmoschus esculentusAbelmoschus esculentusncbi455045Abelmoschus esculentus0Raw / Exact DB / Canonical match8JZLAbelmoschus esculentus0EOL-000000421238Abelmoschus esculentus03152707Abelmoschus esculentus0455045Abelmoschus esculentus0NOsample_scientific_name_inputs.txt2Abies albaAbies albancbi45372Abies alba0Raw / Exact DB / Canonical match8K9YAbies alba0EOL-000000503258Abies alba02685484Abies alba045372Abies alba0NOsample_scientific_name_inputs.txt3Abies balsameaAbies balsameancbi90345Abies balsamea0Raw / Exact DB / Canonical match63Z6QAbies balsamea0EOL-000000503176Abies balsamea02685383Abies balsamea090345Abies balsamea0NOsample_scientific_name_inputs.txt4Abies pindrowAbies pindrowncbi425843Abies pindrow0Raw / Exact DB / Canonical match8KFLAbies pindrow0EOL-000000503164Abies pindrow02685683Abies pindrow0425843Abies pindrow0NOsample_scientific_name_inputs.txt5Abies pinsapoAbies pinsaponcbi56046Abies pinsapo0Raw / Exact DB / Canonical match8KFMAbies pinsapo0EOL-000000503252Abies pinsapo02685464Abies pinsapo056046Abies pinsapo0NOPhyloSophos result file has the following format (delimited by tabs). Each column shows the information about:Input_file_name: Name of input file which contains given scientific name inputInput_original_order: The order in which the scientific name is contained in the fileRaw_name_input: Raw scientific name input, as it is appeared in the input filePre_corrected_input: Pre-corrected scientific name inputChosen_reference: Reference of choice (e.g. 'ncbi', 'col', 'eol')Chosen_reference_mapped_ID: Taxonomic entry ID(s) mapped to given scientific name input (based on reference of choice)Chosen_reference_scientific_name: Canonical scientific name(s) associated with mapped taxonomic ID(s) (based on reference of choice)Chosen_reference_mapping_status_code: PhyloSophos mapping status code (based on reference of choice)Chosen_reference_mapping_status_description: Short description of mapping status code (based on reference of choice)(specific_reference)_mapped_id: Taxonomic entry ID(s) mapped to given scientific name input (based on specific reference)(specific_reference)_scientific_name: Canonical scientific name(s) associated with mapped taxonomic ID(s) (based on specific reference)(specific_reference)_mapping_status_code: PhyloSophos mapping status code (based on specific reference)Manual_curation_recommended: Mapping status code-based opinion on whether manual curation is needed for this mapping resultEach taxonomic reference found within/pp_refdirectory provides[(specific_reference)_mapped_id] - [(specific_reference)_scientific_name] - [(specific_reference)_mapping_status_code]column triplet. Base PhyloSophos provides 3 column triplets for CoL/EoL/NCBI taxonomy respectively.Citing PhyloSophosWe recommend that those wishing to cite PhyloSophos use the following citation:
Cho MH, No KT. PhyloSophos: a high-throughput scientific name mapping algorithm augmented with explicit consideration of taxonomic science, and its application on natural product (NP) occurrence database processing. BMC Bioinformatics. (under review: to be updated soon)LicensePhyloSophos is released with MIT license. This is open to all and can be used for any purpose. We look forward to an increase in the development of this field with the help of contributors who share their derived work publicly.Contactmhcho@bmdrc.org