pyicat-plus |version|
=====================

*pyicat-plus* is a python client for ICAT+.

*pyicat-plus* has been developed by the `Software group <https://www.esrf.fr/Instrumentation/software>`_ of the `European Synchrotron <https://www.esrf.fr/>`_.

Getting started
---------------

Register raw datasets with ICAT

.. code-block:: bash

    icat-store-raw --beamline id00 \
        --proposal id002207 \
        --path /data/visitor/path/to/dataset1 \
        --dataset test1 \
        --sample mysample

    icat-store-raw --beamline id00 \
        --proposal id002207 \
        --path /data/visitor/path/to/dataset2 \
        --dataset test2 \
        --sample mysample

Register processed data with ICAT

.. code-block:: bash

    icat-store-processed --beamline id00 \
        --proposal id002207 \
        --path /data/visitor/path/to/processed \
        --dataset testproc \
        --sample mysample \
        --raw /data/visitor/path/to/dataset1 \
        --raw /data/visitor/path/to/dataset2

Register saved datasets with ICAT

.. code-block:: bash

    icat-store-from-file /data/visitor/.../__icat__/*.xml

Synchronize raw data with ICAT

.. code-block:: bash

    icat-sync-raw --beamline id27 --proposal blc14904 --session 20230829 \
                  --save-dir /tmp/icat/summary --cache-dir /tmp/icat/cache \
                  --format esrfv3 --register --invalidate-cache

* *--save-dir*: generate CSV files and bash scripts to resolves issues later
* *--cache-dir*: store session information in JSON files
* *--register*: ask for ICAT registration when a session is not properly
   registered with ICAT and removes the session from the cache when answering "yes"
* *--auto-register*: same as `--register` but then without prompting for validation
   and only for datasets that are safe to register unsupervised

To update the cache periodically, this command is appropriate

.. code-block:: bash

    icat-sync-raw --save-dir /tmp/icat/summary --cache-dir /tmp/icat/cache \
                  --invalidate-cache --no-print

* *--invalidate-cache*: remove session from the cache that no longer exist on disk or have changed
* *--no-print*: do not print a summary for each session

Save all possible ICAT dataset metadata fields in a NeXus-compliant HDF5 file.
By default the definitions from the locally installed `icat-esrf-definitions` are used
but a URL to the ICAT definitions XML file can be provided.

.. code-block:: bash

    icat-nexus-definitions [--filename=icat.h5] [--url https://...]

Documentation
-------------

.. toctree::
    :maxdepth: 2

    api