Swapped docstrings for `--multiple-targets` vs `--multiple-morphs`?

[tinatn29]

Problem

Current docstring says:

--multiple-morphs Changes usage to 'diffpy.morph [options] FILE
DIRECTORY'. FILE will be morphed with each file in
DIRECTORY as target. Files in DIRECTORY are sorted by
alphabetical order unless a field is specified by
--sort-by.
--multiple-targets Changes usage to 'diffpy.morph [options] DIRECTORY
FILE'. Each file in DIRECTORY will be morphed with
FILE as target. Files in DIRECTORY are sorted by
alphabetical order unless a field is specified by
--sort-by.

Are these switched by any chance? Based on the function names, I would think --multiple-morphs morphs each file in DIRECTORY onto a single TARGET, and --multiple-targets morphs a single FILE onto multiple targets in a DIRECTORY.

Proposed solution

Double check and correct the docstring as needed.

[sbillinge]

Also, these docstrings are very hard to read and understand. Can we have a quick discussion about usage and then try and come up with clearer descriptions?

[Sparks29032]

@tinatn29 Yes, thank you.

@sbillinge Maybe something like:

--multiple-morphs Changes the program usage
to 'diffpy.morph [options] DIRECTORY FILE'.
Morphs are performed between each file
in DIRECTORY and FILE.
For each, a file in DIRECTORY is morphed
to best match FILE.
By default, the Rw for each morph is plotted,
where the x-axis is the name of each file in
DIRECTORY in alphabetical order.
The y-axis can be changed using the
--plot-parameter option.
The x-axis can be changed using the
--sort-by option.

--multiple-targets Changes the program usage
to 'diffpy.morph [options] FILE DIRECTORY'. 
Morphs are performed between FILE and each
file in DIRECTORY.
For each, FILE is morphed to best match
one file in DIRECTORY.
By default, the Rw for each morph is plotted,
where the x-axis is the name of each file in
DIRECTORY in alphabetical order.
The y-axis can be changed using the
--plot-parameter option.
The x-axis can be changed using the
--sort-by option.

--sort-by=FIELD Used with --multiple-<targets/morphs>
to sort files in DIRECTORY by some FIELD.
If the FIELD being used (e.g. temperature)
has a numerical value, sort from lowest to highest.
Otherwise, sort in ASCII sort order.
The program will look for the FIELD (case insensitive)
in the header of each of the files in DIRECTORY.
If plotting is enabled, the x-axis of the plot
will be the field.

[sbillinge]

how about

--multiple-morphs
    Usage: 'diffpy.morph --multiple-morphs [options] DIRECTORY TARGET'.   

   Morphs every file in DIRECTORY to the a single file TARGET.  
   TARGET is assumed to exist in DIRECTORY.
  
   By default, the Rw for each morph is plotted,
   where the x-axis is sorted alphanumerically by 
   filename of the file being morphed.
   Use --sort-by option to change the x-axis order.
   Use --plot-parameter to modify the parameter plotted
   on the y-axis

   For further analysis and plotting, results are summarized 
   in the files ????? <something something>

and make the other have a similar format?

[Sparks29032]

Target can exist outside the directory (any arbitrary file they link to). I had originally written it as DIRECTORY and FILE since those are the types that the user would enter.

How is the following?

--multiple-morphs
    Usage: 'diffpy.morph --multiple-morphs [options] DIRECTORY FILE'.   

   Morphs every file in DIRECTORY to the a single target FILE.
  
   By default, the Rw for each morph is plotted,
   where the x-axis is sorted alphanumerically by 
   filename of the file being morphed.
   Use --sort-by option to change the x-axis order.
   Use --plot-parameter to modify the parameter plotted
   on the y-axis.

   For further analysis and plotting, results can be summarized
   and saved using the --verbose and --save options.

[sbillinge]

This is nice.

When I was reading the docs, I found the DIRECTORY FILE language pretty unclear tbh. TARGET is very clear. It is pretty easy to let them know (if it was not already obvious) that TARGET must be a file. A strong vote here for DIRECTORY and TARGET.

Also, we may want to say a word about the default path to the file. If I do DIRECTORY = my_data and TARGET = my_target.gr is the default that it looks for my_target.gr in . or in ./my_data (and which do we want)?

[Sparks29032]

Good point. Like this? (Default for both files and directories is relative to CWD, which I think makes it consistent.)

--multiple-morphs
    Usage: 'diffpy.morph --multiple-morphs [options] DIRECTORY TARGET'.   

   Morphs every file in DIRECTORY to the a single TARGET file.
   Paths for DIRECTORY and TARGET are relative to the current
   working directory.

  
   By default, the Rw for each morph is plotted,
   where the x-axis is sorted alphanumerically by 
   filename of the file being morphed.
   Use --sort-by option to change the x-axis order.
   Use --plot-parameter to modify the parameter plotted
   on the y-axis.

   For further analysis and plotting, results can be summarized
   and saved using the --verbose and --save options.

--multiple-targets
    Usage: 'diffpy.morph --multiple-targets [options] MORPH DIRECTORY'.   

   Morphs the MORPH file to every file in DIRECTORY.
   Paths for MORPH and DIRECTORY are relative to the current
   working directory.
  
   By default, the Rw for each morph is plotted,
   where the x-axis is sorted alphanumerically by 
   filename of the file being morphed.
   Use --sort-by option to change the x-axis order.
   Use --plot-parameter to modify the parameter plotted
   on the y-axis.

   For further analysis and plotting, results can be summarized
   and saved using the --verbose and --save options.

[sbillinge]

This looks good but please check the usage in the second help message

[Sparks29032]

Okay, I will see what other docstrings need to be cleaned also.