From 8e4d0d9f722a85541ae59b84cf7e2587f19b971b Mon Sep 17 00:00:00 2001 From: Richard Harris <richard.harris@nanoporetech.com> Date: Tue, 7 Nov 2023 12:56:59 +0000 Subject: [PATCH] added warning about positional arguments and --columns --- CHANGELOG.md | 1 + docs/docs/tools.rst | 14 +++++++++++++- python/pod5/README.md | 11 +++++++++++ 3 files changed, 25 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index edadf71..d5256dd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Transfers dataframes used in subsetting / filter use categorical fields to reduce memory consumption - Polars version increased to `~=0.19` +- Documentation regarding positional arguments - Renamed deprecated `polars.groupby` to `polars.group_by` ### Fixed diff --git a/docs/docs/tools.rst b/docs/docs/tools.rst index 50c5be7..65c5a3c 100644 --- a/docs/docs/tools.rst +++ b/docs/docs/tools.rst @@ -239,7 +239,7 @@ then ``pod5 filter`` might be a more appropriate tool as the only input is a lis $ pod5 subset example_1.pod5 --csv mapping.csv # Subset input(s) using a dynamic mapping created at runtime - $ pod5 subset example_1.pod5 --table table.txt --columns barcode + $ pod5 subset example_1.pod5 --columns barcode --table table.txt .. important:: @@ -248,6 +248,18 @@ then ``pod5 filter`` might be a more appropriate tool as the only input is a lis will be raised unless the ``--duplicate-ok`` argument is set. If ``--duplicate-ok`` is set then both reads will be written to the output, although this is not recommended. +.. warning:: + + The ``--columns`` argument will greedily consume values and as such, care should be taken + with the placement of any positional arguments. The following line will result in an error + as the input pod5 file is consumed by ``--columns`` resulting in no input file being set. + + .. code-block:: console + + # Invalid placement of positional argument example.pod5 + $ pod5 subset --table table.txt --columns barcode example.pod5 + + Creating a Subset Mapping ------------------------------ diff --git a/python/pod5/README.md b/python/pod5/README.md index 7f221a7..aec5c88 100644 --- a/python/pod5/README.md +++ b/python/pod5/README.md @@ -340,6 +340,17 @@ then ``pod5 filter`` might be a more appropriate tool as the only input is a lis > will be raised unless the ``--duplicate-ok`` argument is set. If ``--duplicate-ok`` is > set then both reads will be written to the output, although this is not recommended. +#### Note on positional arguments + +> The ``--columns`` argument will greedily consume values and as such, care should be taken +> with the placement of any positional arguments. The following line will result in an error +> as the input pod5 file is consumed by ``--columns`` resulting in no input file being set. + +```bash +# Invalid placement of positional argument example.pod5 +$ pod5 subset --table table.txt --columns barcode example.pod5 +``` + #### Creating a Subset Mapping ##### Target Mapping (.csv)