docs on what can be used for `path(stageName)`

[nick-youngblut]

The inputs docs state:

name
Specify how the file should be named in the task work directory. Can be a name or a pattern.

It is not clear whether a val can be use to customize the name. For example:

input:
  tuple val(id), path(file, stageAs: "${id}_*")

This staging pattern would be very powerful, but it appears that the code does not work (at least I cannot get it working).

So, it would be helpful to state whether such such code is possible.

While one could argue that this "clutters" the docs, another could argue that docs are read more and more by LLMs and less by humans, so including more detail is not much of a problem for LLMs.

[pditommaso]

You are right, seems something went lost. Checking on branch 22.10.x it was much more extensive

The ``stageAs`` option allows you to control how the file should be named in the task work
directory. You can provide a specific name or a pattern as described in the `Multiple input files`_
section::

    process foo {
      input:
      path x, stageAs: 'data.txt'

      """
      your_command --in data.txt
      """
    }

    workflow {
      foo('/some/data/file.txt')
    }


Multiple input files
--------------------

A ``path`` input can also accept a collection of files instead of a single value.
In this case, the input variable will be a Groovy list, and you can use it as such.

When the input has a fixed file name and a collection of files is received by the process,
the file name will be appended with a numerical suffix representing its ordinal position
in the list. For example::

    process blastThemAll {
        input:
        path 'seq'

        "echo seq*"
    }

    workflow {
        def fasta = Channel.fromPath( "/some/path/*.fa" ).buffer(size: 3)
        blastThemAll(fasta)
    }

will output::

    seq1 seq2 seq3
    seq1 seq2 seq3
    ...

The target input file name may contain the ``*`` and ``?`` wildcards, which can be used
to control the name of staged files. The following table shows how the wildcards are
replaced depending on the cardinality of the received input collection.

============ ============== ==================================================
Cardinality   Name pattern   Staged file names
============ ============== ==================================================
 any         ``*``           named as the source file
 1           ``file*.ext``   ``file.ext``
 1           ``file?.ext``   ``file1.ext``
 1           ``file??.ext``  ``file01.ext``
 many        ``file*.ext``   ``file1.ext``, ``file2.ext``, ``file3.ext``, ..
 many        ``file?.ext``   ``file1.ext``, ``file2.ext``, ``file3.ext``, ..
 many        ``file??.ext``  ``file01.ext``, ``file02.ext``, ``file03.ext``, ..
 many        ``dir/*``       named as the source file, created in ``dir`` subdirectory
 many        ``dir??/*``     named as the source file, created in a progressively indexed subdirectory e.g. ``dir01/``, ``dir02/``, etc.
 many        ``dir*/*``      (as above)
============ ============== ==================================================

The following example shows how a wildcard can be used in the input file definition::

    process blastThemAll {
        input:
        path 'seq?.fa'

        "cat seq1.fa seq2.fa seq3.fa"
    }

    workflow {
        def fasta = Channel.fromPath( "/some/path/*.fa" ).buffer(size: 3)
        blastThemAll(fasta)
    }

.. note::
  Rewriting input file names according to a named pattern is an extra feature and not at all required.
  The normal file input syntax introduced in the :ref:`process-input-path` section is valid for collections of
  multiple files as well. To handle multiple input files while preserving the original file names, use a variable
  identifier or the ``*`` wildcard.


Dynamic input file names
------------------------

When the input file name is specified by using the ``name`` option or a string literal, you
can also use other input values as variables in the file name string. For example::

  process simpleCount {
    input:
    val x
    path "${x}.fa"

    """
    cat ${x}.fa | grep '>'
    """
  }

In the above example, the input file name is determined by the current value of the ``x`` input value.

This approach allows input files to be staged in the task directory with a name that is coherent
with the current execution context.

.. tip::
  In most cases, you won't need to use dynamic file names, because each task is executed in its
  own directory, and input files are automatically staged into this directory by Nextflow.
  This behavior guarantees that input files with the same name won't overwrite each other.

  An example of when you may have to deal with that is when you have many input files in a task,
  and some of these files may have the same filename. In this case, a solution would be to use
  the option ``stageAs``.

tagging @christopher-hakkaart for visibility

[bentsherman]

All of that content is still in the docs

https://www.nextflow.io/docs/latest/process.html#input-files-path

[bentsherman]

@nick-youngblut to your original question, I'm actually not sure if this behavior is well-defined. It might work in some cases and not in others. I'd have to look into it. But it's a bit of a moot point for me because I do intend to support it as part of static types. These kinds of ambiguities are part of why I want to move away from the custom process input/output syntax

[pditommaso]

as a user, search for stageAs, find this, missing link to that details

[nick-youngblut]

@bentsherman that's great to hear! Thanks for looking into it. I continually find file naming as one of the biggest pain points for developing nextflow pipelines, especially when it comes to creating the final multiqc report. Any streamlining of this task would be greatly appreciated.

Also, thanks @pditommaso for your help with this issue!

[nick-youngblut]

Also, for what it's worth, I've seen new nextflow developers often use paths (e.g., genome reference files) as values instead of converting to path types. Then the developers do not understand why their pipeline breaks when run on AWS or GCP. They generally use this "hack" since it is easier than dealing with path types (e.g., just point multiqc at the final output (publishdir) directory, as a simple hack).

It might be helpful to emphasize good practices in the docs.