more updates of trident-related documentation

Author: nevrome

pdf_conversion/pdf_conversion_list.tsv

@@ -10,6 +10,7 @@ trident_guide_archive/trident_guide_1.1.7.0.md	trident_guide_archive/trident_gui
 trident_guide_archive/trident_guide_1.2.0.0_to_1.2.1.0.md	trident_guide_archive/trident_guide_1.2.0.0_to_1.2.1.0.pdf
 trident_guide_archive/trident_guide_1.3.0.4.md	trident_guide_archive/trident_guide_1.3.0.4.pdf
 trident_guide_archive/trident_guide_1.4.0.2_to_1.4.0.3.md	trident_guide_archive/trident_guide_1.4.0.2_to_1.4.0.3.pdf
+trident_guide_archive/trident_guide_1.4.1.0_to_1.5.0.1.md	trident_guide_archive/trident_guide_1.4.1.0_to_1.5.0.1.pdf
 xerxes_guide_archive/xerxes_guide_0.2.0.0.md	xerxes_guide_archive/xerxes_guide_0.2.0.0.pdf
 xerxes_guide_archive/xerxes_guide_1.0.0.2.md	xerxes_guide_archive/xerxes_guide_1.0.0.2.pdf
 janno_details.md	janno_details.pdf

trident.md

@@ -541,7 +541,7 @@ If a query results in multiple individuals with the same name, forge will throw
 
 By default the order of samples in a Poseidon package created with `forge` depends on the order in which the relevant source packages are discovered by `trident` (e.g. when it crawls for packages in the `-d` base directories) and then the sample order within these packages.
 
-The option `--ordered` gives more control over the output order. It causes `trident` to output the resulting package with samples ordered according to the selection in `-f` or `--forgeFile`. This works through an alternative, slower sample selection algorithm that loops through the list of entities and checks for each entity which samples it adds or removes respectively from the final selection.
+The option `--ordered` gives more control over the output order. It causes `trident` to output the resulting package with samples ordered according to the selection in `-f` or `--forgeFile`. This works through an alternative, slower sample selection algorithm that loops through the list of entities and checks for each entity which samples it adds or removes respectively to and from the final selection.
 
 For simple, positive selection, packages, groups and samples are added as expected. Negative selection removes samples from the list again. If an entity is selected twice via positive selection, then its first occurrence is considered for the ordering.
 
@@ -552,7 +552,8 @@ One particular application of `--ordered` is the reordering of samples in an exi
 1. Generate a `--forgeFile` with the desired order of the samples in `MyPac`. This can be done manually or with any suitable tool. Here is an example, where we employ `qjanno` to generate a `forge` selection so that the samples are ordered alphabetically by their `Poseidon_ID`:
 
 ```bash
-qjanno "SELECT '<'||Poseidon_ID||'>' FROM d(MyPac) ORDER BY Poseidon_ID" --raw --noOutHeader > myOrder.txt
+qjanno "SELECT '<'||Poseidon_ID||'>' FROM d(MyPac) ORDER BY Poseidon_ID" \
+  --raw --noOutHeader > myOrder.txt
 ```
 
 2. Use `trident forge` with `--ordered` and `--preservePyml` (see below) to create the package with the specified order:
@@ -564,7 +565,8 @@ trident forge -d MyPac --forgeFile myOrder.txt -o MyPac2 --ordered --preservePym
 3. Apply `trident rectify` to increment the package version number and document the reordering:
 
 ```bash
-trident rectify -d MyPac2 --packageVersion Minor --logText "reordered the samples alphabetically by Poseidon_ID"
+trident rectify -d MyPac2 --packageVersion Minor \
+  --logText "reordered the samples alphabetically by Poseidon_ID"
 ```
 
 `MyPac2` then acts as a stand-in replacement for `MyPac` that only differs in the order of samples (and maybe the order of variables/fields in the `POSEIDON.yml`, `.janno`, `.ssf` or `.bib` files).

web_api.md

@@ -85,31 +85,40 @@ With `/zip_file/<package_name>`, one can download a package as a zip-file.
 
 The endpoints can be accessed directly, or with additional arguments. These have to be listed after `?`, and must be separated by `&`. See the documentation of individual arguments below.
 
+**`archive=...`:**
+
 The most imporant argument is `archive=...`, which serves to select the package archive a given query should be applied to. See the overview [here](archive_overview) for the currently available options `community-archive`, `minotaur-archive` and `aadr-archive`. The archive names are identical to the respecitve GitHub repository names. If `archive=...` is not provided, then the query will target the default `community-archive`.
 
 ?> Request a list of packages in the `aadr-archive`:<br>
    https://server.poseidon-adna.org/packages?archive=aadr-archive<br>
    Download a package from this archive:<br>
    https://server.poseidon-adna.org/zip_file/AADR_v54_1_p1_1240K_EuropeAncient?archive=aadr-archive
 
+**`client_version=...`:**
+
 `client_version=...` is an argument for `/packages`, `/groups`, and `/individuals` to check client-server compatibility (primarily for the trident subcommand `list`). It defaults to the trident version of the server, so usually the latest release version of trident. If the client has a version that is not supported by the server the connection attempt is rejected.
 
 ?> Request a list of packages with an old client version:<br>
    https://server.poseidon-adna.org/packages?archive=aadr-archive&client_version=1.2.0.0<br>
    (note how the two arguments were appended here with `&`)
 
+**`package_version=...`:**
+
 `/zip_file/<package_name>` allows to specify a version of the requested package by appending `?package_version=...`. It defaults to the latest available version of a given package.
 
 ?> Download a specific version of a package:<br>
    https://server.poseidon-adna.org/zip_file/AADR_v54_1_p1_1240K_EuropeAncient?archive=aadr-archive&package_version=0.1.2
 
+**`additionalJannoColumns=...`:**
+
 For `/individuals` the API provides an additional argument: `additionalJannoColumns=...`. It allows to add information from arbitrary .janno file columns into the `additionalJannoColumns` JSON-list. Note that the precise names of the Column titles in the Janno specification must be used. A list can be found [here](https://github.com/poseidon-framework/poseidon-schema/blob/master/janno_columns.tsv).
 
 ?> Request the individuals list for the default archive, but with information on the origin country of the samples:<br>
    https://server.poseidon-adna.org/individuals?additionalJannoColumns=Country<br>
    This also works for multiple variables at once, which can be given in a comma-separated list:<br>
    https://server.poseidon-adna.org/individuals?additionalJannoColumns=Latitude,Longitude
 
+To request all available columns at once the special key word `ALL` can be used: `?additionalJannoColumns=ALL`.
 
 ## The server implementation