annotate med_environ.xml @ 1:b79faea33a8a draft

planemo upload for repository https://github.com/jeremyfix/medenv commit 56fa523a7852e06962a05a05224ca193c25e20bc

<tool id="iabiodiv_smartbiodiv_med_environ" name="Adds environment variables" version="0.0.1" profile="22.05">
    <description>
        From Copernicus and etopo given geolocalized and timestamped observations
    </description>
    <requirements>
        <requirement type="package" version="2.1.3">pandas</requirement>
        <requirement type="package" version="4.9.3">lxml</requirement>
        <requirement type="package" version="1.0.4">medenv</requirement>
    </requirements>
    <creator>
        <person givenName="Jérémy" familyName="Fix" url="http://www.github.com/jeremyfix/" email="[e-mail]"/>
    </creator>
    <command><![CDATA[
        #set $cmems_username = $__user__.extra_preferences.get('cmems_username', "")
        #if $cmems_username != ""
            cp '$cmems_credentials' ~/.medenvkey &&
        #end if

python '$__tool_directory__/med_environ.py'
    --datafile '${input}'
    --out_file '${out_file}'
    --lat_key  '${lat_key}'
    --long_key '${long_key}'
    --date_key '${date_key}'
    --depth_key '${depth_key}'
    --variables '${env_variables}'
    --tol_spatial_coordinates '${tol_spatial_coordinates}'
    --keyfile ~/.medenvkey
    --verbose '${verbose}'
        ]]></command>
    <configfiles>
        <configfile name="cmems_credentials"><![CDATA[
            #set $cmems_username = $__user__.extra_preferences.get('cmems_username', "")
            #set $cmems_password = $__user__.extra_preferences.get('cmems_password', "")
            cmems_username: $cmems_username
            cmems_password: $cmems_password
        ]]></configfile>
    </configfiles>
    <inputs>
        <param name="input" type="data" format="tabular" label="Input dataset"/>
        <param name="env_variables" type="select" label="Which variables to add" multiple="true">
            <option value="temperature">temperature</option>
            <option value="salinity">salinity</option>
            <option value="phytoplankton-carbon-biomass">Mole concentration of phytoplankton expressed as carbon in sea water (phyc)</option>
            <option value="chlorophyl-a">chlorophyl-a (CHL, mg/m3)</option>
            <option value="nitrate">nitrate (NO3, mmol/M3)</option>
            <option value="phosphate">phosphate (PO4, mmol/m3)</option>
            <option value="ammonium">ammonium (NH4, mmol/m3)</option>
            <option value="net-primary-production">Net primary production of biomass expressed as carbon per unit volume in sea water (nppv, [mg/m3/day])</option>
            <option value="oxygen">Mole concentration of dissolved molecular oxygen in sea water (O2, [mmol/m3])</option>
            <option value="ph">Sea water ph reported on total scale (ph) </option>
            <option value="dissolved-inorganic-carbon">Mole concentration of dissolved inorganic carbon in sea water (dissic, [mol/m3])</option>
            <option value="alkalinity">alkalinity (talk)</option>
            <option value="bathymetry">bathymetry</option>
            <option value="northward-water-velocity">Northward water velocity</option>
            <option value="eastward-water-velocity">Eastward water velocity</option>
            <option value="sea-surface-temperature">sea surface temperature</option>
            <option value="sea-surface-salinity">sea surface salinity</option>
            <option value="sea-surface-above-geoid">sea surface above geoid</option>
            <option value="surface-partial-pressure-co2">surface partial pressure CO2</option>
            <option value="surface-co2-flux">surface CO2 flux</option>
            <option value="mixed-layer-thickness">mixed layer thickness</option>
        </param>
        <param name="lat_key" label="The key of the column for the latitude" type="data_column" data_ref="input" use_header_names="true"/>
        <param name="long_key" label="The key of the column for the longitude" type="data_column" data_ref="input" use_header_names="true"/>
        <param name="tol_spatial_coordinates" type="float" value="0.2" label="A tolerance on the latitude/longitude for the request point" optional="False"/>
        <param name="depth_key" label="The key of the column for the depth" type="data_column" data_ref="input" use_header_names="true"/>
        <param name="date_key" label="The key of the column for the observation time" type="data_column" data_ref="input" use_header_names="true"/>
        <param name="verbose" type="boolean" value="False" label="Verbose in the standard output of the tool"/>
    </inputs>
    <outputs>
        <data format="tabular" name="out_file" metadata_source="input" label="Dataset augmented with the environmental variables"/>
    </outputs>
    <tests>
        <test expect_num_outputs="1">
            <param name="input" value="reef_life_subset.tsv"/>
            <param name="env_variables" value="bathymetry"/> <!-- This test is requesting etopo only -->
            <param name="lat_key" value="9"/>
            <param name="long_key" value="10"/>
            <param name="tol_spatial_coordinates" value="0.2"/>
            <param name="depth_key" value="12"/>
            <param name="date_key" value="11"/>
            <param name="verbose" value="False"/>
            <output name="out_file" file="expected-output.tsv">
                <assert_contents>
                    <has_n_lines n="100"/>
                    <has_n_columns n="21"/>
                </assert_contents>
            </output>
        </test>
    </tests>
    <help>

        **What it does**

        This tool allows you to augment your dataset by adding some environmental variables grabbed from CMEMS, etopo, and woa. It is a galaxy tool built on the medenv python package available at https://github.com/jeremyfix/medenv.

        It will augment the dataset with environmental variables as provided by copernicus and etopo based on the informations coming from an "observation file". This version of the tool gets environmental data from etopo for the bathymetry and otherwise copernicus mediterranean products.

        We expect the dataset you provide to contain the coordinates of the observation: latitude, longitude, depth, and time. The time is expected in ISO 8601: YYYY-MM-DDTHH:MM:SSZ

        The `cmems_username` and `cmems_password` are required only if you want to add variables provided by CMEMS. These must be defined in "User -> Preferences -> Manage Information"

        The CMEMS data are collected from the following products :

        - med-cmcc: https://resources.marine.copernicus.eu/product-detail/MEDSEA_MULTIYEAR_PHY_006_004/INFORMATION
        - med-ogs: https://resources.marine.copernicus.eu/product-detail/MEDSEA_MULTIYEAR_BGC_006_008/INFORMATION

        The bathymetry is obtained with the ETOPO at : 

        - https://www.ngdc.noaa.gov/mgg/global/relief/ETOPO1/data/bedrock/grid_registered/netcdf/ETOPO1_Bed_g_gmt4.grd.gz

        We request data around the point with a given tolerance and average the collected values. The medenv package does not force that averaging and could return a raster. A later update of the Galaxy tool could take this into account.

        The features you can request are the following, some indexed by depth :

        - "bathymetry", (etopo)
        - "temperature",
        - "salinity",
        - "chlorophyl-a",
        - "nitrate",
        - "phosphate",
        - "ammonium",
        - "phytoplankton-carbon-biomass",
        - "oxygen",
        - "net-primary-production",
        - "ph",
        - "alkalinity",
        - "dissolved-inorganic-carbon",
        - "northward-water-velocity",
        - "eastward-water-velocity".

        and others not indexed by depth : 

        - "mixed-layer-thickness",
        - "sea-surface-temperature",
        - "sea-surface-salinity",
        - "sea-surface-above-geoid",
        - "surface-partial-pressure-co2",
        - "surface-co2-flux".

        ** Copernicus credentials **

        To request Copernicus, you need to have an account on the https://resources.marine.copernicus.eu platform.
        Then, you need to provide your credentials in the user-preference section of Galaxy.

    </help>
    <citations>
        <citation type="bibtex">@misc{medenvGithubRepository,
        title = "MedEnv",
        author = "{Jeremy Fix}",
        howpublished = "\url{https://github.com/jeremyfix/medenv}",
        year = 2023
        }
        </citation>
    </citations>
</tool>