Command-line usage

The wellmap package comes with a command-line tool (also called wellmap) that displays a visual representation of the plate layout described by a TOML file. This is meant to help catch mistakes, which can be easy to make in complex layouts.

For more information on this command and its options, run:

$ wellmap -h
Visualize the plate layout described by a wellmap TOML file.

Usage:
    wellmap <toml> [<param>...] [-o <path>] [-p] [-c <color>] [-s] [-f]

Arguments:
    <toml>
        TOML file describing the plate layout to display.  For a complete 
        description of the file format, refer to:
        
        https://wellmap.readthedocs.io/en/latest/file_format.html

    <param>
        The name(s) of one or more experimental parameters from the above TOML 
        file to project onto the plate.  For example, if the TOML file contains 
        something equivalent to `well.A1.conc = 1`, then "conc" would be a 
        valid parameter name.

        If no names are given, the default is to display any parameters that 
        have at least two different values.  For complex layouts, this may 
        result in a figure too big to fit on the screen.  The best solution for 
        this (at the moment) is just to specify some parameters to focus on.

Options:
    -o --output PATH
        Output an image of the layout to the given path.  The file type is 
        inferred from the file extension.  If the path contains a dollar sign 
        (e.g. '$.svg'), the dollar sign will be replaced with the base name of 
        the <toml> path.

    -p --print
        Print a paper copy of the layout, e.g. to reference when setting up an 
        experiment.  The default printer for the system will be used.  To see 
        the current default printer, run: `lpstat -d`.  To change the default 
        printer, run: `lpoptions -d <printer name>`.  When printing, the 
        default color scheme is changed to 'dimgray'.  This can still be 
        overridden using the '--color' flag.

    -c --color NAME
        Use the given color scheme to illustrate which wells have which 
        properties.  The given NAME must be one of the color scheme names 
        understood by either `matplotlib` or `colorcet`.  See the links below 
        for the full list of supported colors, but some common choices are 
        given below.  The default is 'rainbow':

        rainbow:  blue, green, yellow, orange, red
        viridis:  purple, green, yellow
        plasma:   purple, red, yellow
        coolwarm: blue, red
        tab10:    blue, orange, green, red, purple, ...
        dimgray:  gray, black

        Matplotlib colors:
        https://matplotlib.org/examples/color/colormaps_reference.html

        Colorcet colors:
        http://colorcet.pyviz.org/

    -s --superimpose
        Superimpose the exact value for each well (i.e. as a word/number) above 
        the layout.  Note that if the values are too big, they might overlap 
        neighboring wells, which could make things hard to read.  If you want 
        more control over the exact formatting of these superimposed values, 
        use the python/R API.

    -f --foreground
        Don't attempt to return the terminal to the user while the GUI runs.  
        This is meant to be used on systems where the program crashes if run in 
        the background.