Skip to content

Commit

Permalink
Merge pull request #2192 from dominikl/cli_import_options
Browse files Browse the repository at this point in the history 
Update CLI import option documentation
  • Loading branch information
@jburel
jburel authored Dec 6, 2021
2 parents 1b40b78 + 06b5625 commit db669f7
Show file tree
Hide file tree
Showing 2 changed files with 156 additions and 41 deletions.
172 changes: 132 additions & 40 deletions omero/downloads/cli/help.out
View file
Original file line number Diff line number Diff line change
@@ -1,49 +1,141 @@

Import any number of files into an OMERO instance.
If "-" is the only path, a list of files or directories
is read from standard in. Directories will be searched for
all valid imports.

Session arguments:
Mandatory arguments for creating a session are 1- either the OMERO server hostname,
username and password or 2- the OMERO server hostname and a valid session key.
-s SERVER OMERO server hostname
-u USER OMERO username
-w PASSWORD OMERO password
-k KEY OMERO session key (UUID of an active session)
-p PORT OMERO server port (default: 4064)
Run the Java-based command-line importer

This is a Python wrapper around the Java importer. Login is handled by Python
OMERO.cli. To see more options, use "--javahelp".

Options marked with "**" are passed strictly to Java. If they interfere with
any of the Python arguments, you may need to end precede your arguments with a
"--".

Bulk imports:

Rather than passing one or more files to the import command, a single
dictionary-like file (e.g. yml or json) can be passed to the `--bulk`
argument. Most keys in the bulk file will be treated like additional
command-line arguments. Special keys include:

* columns A list of columns for parsing the value of path
* continue Like the "-c" changes error handling
* dry_run If true, print out additional arguments rather than run them.
If another string other than false, use as a template for
storing the import commands. (e.g. /tmp/%s.sh)
* include Relative path (from the bulk file) of a parent bulk file
* path A file which will be parsed line by line based on its file
ending. Lines containing zero or more keys along with a
single file to be imported. Options for formats include:
- .tsv and .csv files will be parsed by the existing library
- other files will be parsed with shlex
- unless no columns are specified, in which case each line
is treated as a file

Optional Arguments:
In addition to any higher level options

-h, --help show this help message and exit
--javahelp, --java-help Show the Java help text

Login arguments:
Environment variables:

OMERO_USERDIR Set the base directory containing the user's files.
Default: $HOME/omero
OMERO_SESSIONDIR Set the base directory containing local sessions.
Default: $OMERO_USERDIR/sessions
OMERO_TMPDIR Set the base directory containing temporary files.
Default: $OMERO_USERDIR/tmp
OMERO_PASSWORD Set the user's password for creating new sessions.
Ignored if -w or --password is used.


Optional session arguments:

-C, --create Create a new session regardless of existing ones
-s SERVER, --server SERVER OMERO server hostname
-p PORT, --port PORT OMERO server port
-g GROUP, --group GROUP OMERO server default group
-u USER, --user USER OMERO username
-w PASSWORD, --password PASSWORD OMERO password
-k KEY, --key KEY OMERO session key (UUID of an active session)
--sudo ADMINUSER Create session as this admin. Changes meaning of password!
-q, --quiet Quiet mode. Causes most warning and diagnostic messages to be suppressed.

Python arguments:
Optional arguments which are used to configure import.

--bulk [BULK] Bulk YAML file for driving multiple imports
--logprefix [LOGPREFIX] Directory or file prefix for --file and --errs
--file [FILE] File for storing the standard output from the Java process
--errs [ERRS] File for storing the standard error from the Java process
--clientdir CLIENTDIR Path to the directory containing the client JARs. Default: lib/client
--logback LOGBACK Path to a logback xml file. Default: etc/logback-cli.xml
--fetch-jars FETCH_JARS Download this version of OMERO.java jars and exit
--depth DEPTH Number of directories to scan down for files
--skip {all,checksum,minmax,thumbnails,upgrade}
Optional step to skip during import
path Path to be passed to the Java process

Naming arguments:
All naming arguments are optional
-n NAME Image or plate name to use
-x DESCRIPTION Image or plate description to use
--name NAME Image or plate name to use
--description DESCRIPTION Image or plate description to use

Optional arguments:
-h Display this help and exit
-f Display the used files and exit
-c Continue importing after errors
-l READER_FILE Use the list of readers rather than the default
-d DATASET_ID OMERO dataset ID to import image into
-r SCREEN_ID OMERO screen ID to import plate into
-T TARGET target for imports
--report Report errors to the OME team
--upload Upload broken files and log file (if any) with report. Required --report
--logs Upload log file (if any) with report. Required --report
--email EMAIL Email for reported errors. Required --report
--debug LEVEL Turn debug logging on (optional level)
--annotation-ns ANNOTATION_NS Namespace to use for subsequent annotation
--annotation-text ANNOTATION_TEXT Content for a text annotation
--annotation-link ANNOTATION_LINK Comment annotation ID to link all images to
Optional arguments passed strictly to Java.

-n NAME, --name NAME Image or plate name to use (**)
-x DESCRIPTION, --description DESCRIPTION
Image or plate description to use (**)

Feedback arguments:
Optional arguments passed strictly to Java allowing to report errors to the OME team.

--report Report errors to the OME team (**)
--upload Upload broken files and log file (if any) with report. Required --report (**)
--logs Upload log file (if any) with report. Required --report (**)
--email EMAIL Email for reported errors. Required --report (**)

Annotation arguments:
Optional arguments passed strictly to Java allowing to annotate imports.

--annotation-ns ANNOTATION_NS Namespace to use for subsequent annotation (**)
--annotation-text ANNOTATION_TEXT Content for a text annotation (**)
--annotation-link ANNOTATION_LINK Comment annotation ID to link all images to (**)

Java arguments:
Optional arguments passed strictly to Java.

-f Display the used files and exit (**)
-c Continue importing after errors (**)
-l READER_FILE, --readers READER_FILE
Use the list of readers rather than the default (**)
-d DATASET_ID OMERO dataset ID to import image into (**)
-r SCREEN_ID OMERO screen ID to import plate into (**)
-T TARGET, --target TARGET OMERO target specification (**)
--debug LEVEL Turn debug logging on (**)
--output TYPE Set an alternative output style
--encrypted TYPE Whether the import should use SSL or not

Advanced Java arguments:
Optional arguments passed strictly to Java. For more information, see --advanced-help.

--advanced-help Show the advanced help text
--transfer [TYPE] Transfer methods like in-place import
--exclude [TYPE] Exclusion filters for preventing re-import
--checksum-algorithm [TYPE] Alternative hashing mechanisms balancing speed & accuracy
--parallel-upload COUNT Number of file upload threads to run at the same time
--parallel-fileset COUNT Number of fileset candidates to import at the same time

Examples:

$ importer-cli -s localhost -u user -w password -d 50 foo.tiff
$ importer-cli -s localhost -u user -w password -d Dataset:50 foo.tiff
$ importer-cli -f foo.tiff
$ importer-cli -s localhost -u username -w password -d 50 --debug ALL foo.tiff
# Display help
$ omero import -h
# Import foo.tiff using current login
$ omero import ~/Data/my_file.dv
# Import foo.tiff using input credentials
$ omero import -s localhost -u user -w password foo.tiff
# Set Java debugging level to ALL
$ omero import foo.tiff -- --debug=ALL
# Display used files for importing foo.tiff
$ omero import foo.tiff -f
# Limit debugging output
$ omero import -- --debug=ERROR foo.tiff

For additional information, see:
https://docs.openmicroscopy.org/latest/omero/users/cli/import.html
Report bugs at https://www.openmicroscopy.org/forums
Report bugs at https://forum.image.sc/tag/omero-cli
25 changes: 24 additions & 1 deletion omero/users/cli/import.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ Some of the options available to the import command are:

$ omero import -s SERVER -p PORT -u USER -g GROUP image.tif

.. option:: -d DATASET_ID, -T TARGET, --target TARGET
.. option:: -d DATASET_ID, -r SCREEN_ID, -T TARGET, --target TARGET

To import images into a Dataset::

Expand All @@ -50,6 +50,29 @@ Some of the options available to the import command are:

See :doc:`import-target` for more information on import targets.

--logprefix [LOGPREFIX] Directory or file prefix for --file and --errs
--file [FILE] File for storing the standard output from the Java process
--errs [ERRS] File for storing the standard error from the Java process

.. option:: --file FILE

File for storing the standard output from the Java process

.. option:: --errs FILE

File for storing the standard error from the Java process

.. option:: --logprefix DIR

Directory or file prefix for --file and --errs

.. option:: --output TYPE

Set an alternative output style, for example::

$ omero import --output=yaml ...


Scanning folders prior to Import
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand Down

0 comments on commit db669f7

Please sign in to comment.