=======
CARACal
=======
|Build Version|
|Doc Status|
|Pypi Version|
|Python Versions|
|Project License|
CARACal stands for Containerized Automated Radio Astronomy Calibration and is a pipeline for radio interferometry data reduction
Main website: `caracal.rtfd.io <https://caracal.readthedocs.io/>`_
It includes the Install & Run instructions described below, and much more.
==================
Installation & Run
==================
Usage and publication policy
-------------------------------
When using CARACal please be aware of and adhere to the `CARACal publication policy <https://docs.google.com/document/d/e/2PACX-1vTqZoKhdewnWvxvEI4C9DxI-IHP1FTCoC5Iqz_MqlX63q8UnnpcqoZvVf-sSfqACu8sA_nufkXICUH6/pub>`_.
Requirements
------------
* `Python <https://www.python.org>`_ 3.8 or higher.
* Container technology of your choice. It can be one of the following:
* `Docker <https://www.docker.com>`_
* `Podman <https://podman.io>`_
* `Singularity <https://github.com/sylabs/singularity>`_ 3.5 - 3.9 (nearly all functionality available for > 2.6.0-dist, see `here <https://github.com/caracal-pipeline/caracal/issues/1154>`_ for further information)
* `Apptainer <https://apptainer.org>`_ does not support all CARACal functionalities (at the moment).
============
Installation
============
We strongly recommend and describe an installation using a `Python3` virtual environment. Only try outside a virtual environment if you know what you are doing. Any name as ``${name}`` occurring in the description below can be chosen arbitrarily. If it symbolises directories or files, those directories or files should exist and the user should have **write** access.
There are three (3) available methods to install the `caracal` pipeline:
1. Manual
---------
Choose the name of the virtual environment `${caracal-venv}`. Then:
.. code-block:: bash
$ python3 -m venv ${caracal-venv}
OR, if the command above does not work
.. code-block:: bash
virtualenv -p python3 ${caracal-venv}
source ${caracal-venv}/bin/activate
pip install -U pip setuptools wheel
For a CARACal stable release run:
.. code-block:: bash
pip install -U caracal
CARACal has a few optional dependencies (*scipy, astropy, regions, astroquery*) which are not installed by default. But to get full functionality, you can install them by running:
.. code-block:: bash
pip install -U caracal[all]
And CARACal developer version which is not recommended for users:
.. code-block:: bash
pip install -U 'caracal[all] @ git+https://github.com/caracal-pipeline/caracal.git@master'
*Ignore any error messages concerning `pyregion`.*
2. `caratekit.sh` script
------------------------
Download the installation script `caratekit.sh <https://github.com/caracal-pipeline/caracal/blob/master/caratekit.sh>`_ . Choose the parent directory ``${workspace}`` and the name of the CARACal directory ``${caracal_dir}``. Any name as ``${name}`` occurring in the description below can be chosen arbitrarily. If it symbolises directories or files, those directories or files should exist and the user should have write acccess.
If using `Docker <https://www.docker.com>`_:
.. code-block:: bash
caratekit.sh -ws ${workspace} -cr -di -ct ${caracal_dir} -rp install -f -kh
If using `Singularity <https://github.com/sylabs/singularity>`_:
.. code-block:: bash
caratekit.sh -ws ${workspace} -cr -si -ct ${caracal_testdir} -rp install -f -kh
3. Poetry (For developers)
--------------------------
Installation from source using `poetry`. First, install poetry:
.. code-block:: bash
pip install poetry
In the working directory where source is checked out run `poetry install` or to include all optional dependencies:
.. code-block:: bash
poetry install --extras all
=========================================
Installation on (ILIFU) slurm environment
=========================================
The installation of CARACal on ilifu has been tried and tested on the Ubuntu 20.0 operating system, although, it should also work on other OS versions. On the login node, follow these instructions:
.. code-block:: bash
cd /path/to/working/area
module add python/3.9.4
python3 -m venv <venv-name>
source <venv-name>/bin/activate
pip install -U pip setuptools wheel
git clone https://github.com/caracal-pipeline/caracal.git
pip install -U -e caracal
deactivate
where ``/path/to/working/area`` is the actual path to the directory where you wish to install CARACal.
In principle, this can also be done in the Slurm environment of ILIFU by submitting an *sbatch* script.
Please amend your `pip install` command with `[all]` option when needed in accordance with the instructions above.
Install the latest release with:
.. code-block:: bash
pip install -U caracal
NB: The stimela singularity images needed for CARACal are stored in this location: ``/software/astro/caracal/``
where you can access the latest version of the images, for example, ``/software/astro/caracal/STIMELA_IMAGES_1.7.0``.
=======
Running
=======
If you installed CARACal manually, activate the virtual environment with:
.. code-block:: bash
source ${caracal-venv}/bin/activate
If you installed CARACal with the ``caratekit.sh`` script, activate the virtual environment with:
.. code-block:: bash
source ${workspace}/${caracal_dir}/caracal_venv/bin/activate
If using `Docker <https://www.docker.com>`_ run CARACal with:
.. code-block:: bash
caracal -c ${your-configuration-file}
If using `Singularity <https://github.com/sylabs/singularity>`_ run CARACal with:
.. code-block:: bash
caracal -ct singularity -c ${your-configuration-file}
For more detailed installation instructions, troubleshooting tips and a full user manual please see `caracal.readthedocs.io <https://caracal.readthedocs.io>`_.
==========
New issues
==========
We encourage users who experience problems installing or running CARACal to check for known issues or open a new issue at
our `GitHub issues page <https://github.com/caracal-pipeline/caracal/issues>`_.
When opening a new issue, please include your:
#. installation type (e.g., Docker, Singularity)
#. software version (both CARACal and Stimela)
#. CARACal configuration file
#. CARACal log files.
In case you are *not* carrying out a fresh installation, remove earlier Stimela images with:
.. code-block:: bash
stimela clean -ac
Then, if using `Docker <https://www.docker.com>`_:
.. code-block:: bash
stimela pull
If using `Singularity <https://github.com/sylabs/singularity>`_, choose a pull folder ``${singularity_pull_folder}``, where the `Singularity <https://github.com/sylabs/singularity>`_ images are stored and define an environment variable by adding this in the rc file of your shell (e.g. .bashrc):
.. code-block:: bash
export SINGULARITY_PULLFOLDER=${WORKSPACE_ROOT}/singularity_images
and run:
.. code-block:: bash
stimela pull -s
If using `Podman <https://podman.io>`_:
.. code-block:: bash
stimela pull -p
=======
License
=======
This project is licensed under the GNU General Public License v2.0 - see license_ for details.
==========
Contribute
==========
Contributions are always welcome! Please ensure that you adhere to our coding
standards pep8_.
.. |Doc Status| image:: https://readthedocs.org/projects/caracal/badge/?version=latest
:target: http://caracal.readthedocs.io/en/latest
:alt:
.. |Pypi Version| image:: https://img.shields.io/pypi/v/caracal.svg
:target: https://pypi.python.org/pypi/caracal
:alt:
.. |Build Version| image:: https://github.com/caracal-pipeline/caracal/actions/workflows/continuous_integration.yml/badge.svg
:target: https://github.com/caracal-pipeline/caracal/actions/workflows/continuous_integration.yml/
:alt:
.. |Python Versions| image:: https://img.shields.io/badge/python-3.8+-blue.svg
:target: https://pypi.python.org/pypi/caracal/
:alt:
.. |Project License| image:: https://img.shields.io/badge/license-GPL-blue.svg
:target: https://github.com/caracal-pipeline/caracal/blob/master/LICENSE
:alt:
.. _license: https://github.com/caracal-pipeline/caracal/blob/master/LICENSE
.. _pep8: https://www.python.org/dev/peps/pep-0008
Raw data
{
"_id": null,
"home_page": "https://github.com/caracal-pipeline/caracal",
"name": "caracal",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "Astronomy,Visualisation,Pipelines",
"author": "The CaraCAL Team",
"author_email": "caracal-info@googlegroups.com",
"download_url": "https://files.pythonhosted.org/packages/be/2a/b1e2301bc5640c894641c7051371bae7d13e04ae1bdddff5a615a6224da0/caracal-1.1.3.tar.gz",
"platform": null,
"description": "=======\nCARACal\n=======\n\n|Build Version|\n|Doc Status|\n|Pypi Version|\n|Python Versions|\n|Project License|\n\nCARACal stands for Containerized Automated Radio Astronomy Calibration and is a pipeline for radio interferometry data reduction\n\nMain website: `caracal.rtfd.io <https://caracal.readthedocs.io/>`_\n\nIt includes the Install & Run instructions described below, and much more.\n\n==================\nInstallation & Run\n==================\n\nUsage and publication policy\n-------------------------------\n\nWhen using CARACal please be aware of and adhere to the `CARACal publication policy <https://docs.google.com/document/d/e/2PACX-1vTqZoKhdewnWvxvEI4C9DxI-IHP1FTCoC5Iqz_MqlX63q8UnnpcqoZvVf-sSfqACu8sA_nufkXICUH6/pub>`_.\n\nRequirements\n------------\n* `Python <https://www.python.org>`_ 3.8 or higher.\n* Container technology of your choice. It can be one of the following:\n * `Docker <https://www.docker.com>`_\n * `Podman <https://podman.io>`_\n * `Singularity <https://github.com/sylabs/singularity>`_ 3.5 - 3.9 (nearly all functionality available for > 2.6.0-dist, see `here <https://github.com/caracal-pipeline/caracal/issues/1154>`_ for further information) \n * `Apptainer <https://apptainer.org>`_ does not support all CARACal functionalities (at the moment).\n\n============\nInstallation\n============\n\nWe strongly recommend and describe an installation using a `Python3` virtual environment. Only try outside a virtual environment if you know what you are doing. Any name as ``${name}`` occurring in the description below can be chosen arbitrarily. If it symbolises directories or files, those directories or files should exist and the user should have **write** access.\n\nThere are three (3) available methods to install the `caracal` pipeline: \n\n1. Manual\n---------\n\nChoose the name of the virtual environment `${caracal-venv}`. Then:\n\n.. code-block:: bash\n\n $ python3 -m venv ${caracal-venv}\n\nOR, if the command above does not work\n\n.. code-block:: bash\n\n virtualenv -p python3 ${caracal-venv}\n source ${caracal-venv}/bin/activate\n pip install -U pip setuptools wheel\n\nFor a CARACal stable release run:\n\n.. code-block:: bash\n\n pip install -U caracal\n\nCARACal has a few optional dependencies (*scipy, astropy, regions, astroquery*) which are not installed by default. But to get full functionality, you can install them by running:\n\n.. code-block:: bash\n\n pip install -U caracal[all]\n\nAnd CARACal developer version which is not recommended for users:\n\n.. code-block:: bash\n\n pip install -U 'caracal[all] @ git+https://github.com/caracal-pipeline/caracal.git@master'\n\n\n\n*Ignore any error messages concerning `pyregion`.*\n\n2. `caratekit.sh` script\n------------------------\n\nDownload the installation script `caratekit.sh <https://github.com/caracal-pipeline/caracal/blob/master/caratekit.sh>`_ . Choose the parent directory ``${workspace}`` and the name of the CARACal directory ``${caracal_dir}``. Any name as ``${name}`` occurring in the description below can be chosen arbitrarily. If it symbolises directories or files, those directories or files should exist and the user should have write acccess.\n\nIf using `Docker <https://www.docker.com>`_:\n\n.. code-block:: bash\n\n caratekit.sh -ws ${workspace} -cr -di -ct ${caracal_dir} -rp install -f -kh\n\n\nIf using `Singularity <https://github.com/sylabs/singularity>`_:\n\n.. code-block:: bash\n\n caratekit.sh -ws ${workspace} -cr -si -ct ${caracal_testdir} -rp install -f -kh\n\n\n3. Poetry (For developers)\n--------------------------\n\nInstallation from source using `poetry`. First, install poetry:\n\n.. code-block:: bash\n\n pip install poetry\n\n\nIn the working directory where source is checked out run `poetry install` or to include all optional dependencies:\n\n.. code-block:: bash\n\n poetry install --extras all\n\n=========================================\nInstallation on (ILIFU) slurm environment\n=========================================\n\nThe installation of CARACal on ilifu has been tried and tested on the Ubuntu 20.0 operating system, although, it should also work on other OS versions. On the login node, follow these instructions:\n\n.. code-block:: bash\n\n cd /path/to/working/area\n module add python/3.9.4\n python3 -m venv <venv-name>\n source <venv-name>/bin/activate\n pip install -U pip setuptools wheel\n git clone https://github.com/caracal-pipeline/caracal.git\n pip install -U -e caracal\n deactivate\n\nwhere ``/path/to/working/area`` is the actual path to the directory where you wish to install CARACal.\nIn principle, this can also be done in the Slurm environment of ILIFU by submitting an *sbatch* script.\nPlease amend your `pip install` command with `[all]` option when needed in accordance with the instructions above.\nInstall the latest release with:\n\n.. code-block:: bash\n\n pip install -U caracal\n\n\nNB: The stimela singularity images needed for CARACal are stored in this location: ``/software/astro/caracal/``\nwhere you can access the latest version of the images, for example, ``/software/astro/caracal/STIMELA_IMAGES_1.7.0``. \n\n=======\nRunning\n=======\n\nIf you installed CARACal manually, activate the virtual environment with:\n\n.. code-block:: bash\n\n source ${caracal-venv}/bin/activate\n\nIf you installed CARACal with the ``caratekit.sh`` script, activate the virtual environment with:\n\n.. code-block:: bash\n\n source ${workspace}/${caracal_dir}/caracal_venv/bin/activate\n\nIf using `Docker <https://www.docker.com>`_ run CARACal with:\n\n.. code-block:: bash\n\n caracal -c ${your-configuration-file}\n\nIf using `Singularity <https://github.com/sylabs/singularity>`_ run CARACal with:\n\n.. code-block:: bash\n\n caracal -ct singularity -c ${your-configuration-file}\n\nFor more detailed installation instructions, troubleshooting tips and a full user manual please see `caracal.readthedocs.io <https://caracal.readthedocs.io>`_.\n\n==========\nNew issues\n==========\n\nWe encourage users who experience problems installing or running CARACal to check for known issues or open a new issue at\nour `GitHub issues page <https://github.com/caracal-pipeline/caracal/issues>`_.\n\nWhen opening a new issue, please include your:\n #. installation type (e.g., Docker, Singularity)\n #. software version (both CARACal and Stimela)\n #. CARACal configuration file\n #. CARACal log files.\n\nIn case you are *not* carrying out a fresh installation, remove earlier Stimela images with:\n\n.. code-block:: bash\n\n stimela clean -ac\n\n\nThen, if using `Docker <https://www.docker.com>`_:\n\n.. code-block:: bash\n\n stimela pull\n\nIf using `Singularity <https://github.com/sylabs/singularity>`_, choose a pull folder ``${singularity_pull_folder}``, where the `Singularity <https://github.com/sylabs/singularity>`_ images are stored and define an environment variable by adding this in the rc file of your shell (e.g. .bashrc):\n\n.. code-block:: bash\n\n export SINGULARITY_PULLFOLDER=${WORKSPACE_ROOT}/singularity_images\n\nand run:\n\n.. code-block:: bash\n\n stimela pull -s\n\nIf using `Podman <https://podman.io>`_:\n\n.. code-block:: bash\n\n stimela pull -p \n\n=======\nLicense\n=======\n\nThis project is licensed under the GNU General Public License v2.0 - see license_ for details.\n\n==========\nContribute\n==========\n\nContributions are always welcome! Please ensure that you adhere to our coding\nstandards pep8_.\n\n.. |Doc Status| image:: https://readthedocs.org/projects/caracal/badge/?version=latest\n :target: http://caracal.readthedocs.io/en/latest\n :alt:\n\n.. |Pypi Version| image:: https://img.shields.io/pypi/v/caracal.svg\n :target: https://pypi.python.org/pypi/caracal\n :alt:\n.. |Build Version| image:: https://github.com/caracal-pipeline/caracal/actions/workflows/continuous_integration.yml/badge.svg\n :target: https://github.com/caracal-pipeline/caracal/actions/workflows/continuous_integration.yml/\n :alt:\n\n.. |Python Versions| image:: https://img.shields.io/badge/python-3.8+-blue.svg\n :target: https://pypi.python.org/pypi/caracal/\n :alt:\n\n.. |Project License| image:: https://img.shields.io/badge/license-GPL-blue.svg\n :target: https://github.com/caracal-pipeline/caracal/blob/master/LICENSE\n :alt:\n\n\n.. _license: https://github.com/caracal-pipeline/caracal/blob/master/LICENSE\n.. _pep8: https://www.python.org/dev/peps/pep-0008\n",
"bugtrack_url": null,
"license": "GNU GPL v2",
"summary": "Containerized Automated Radio Astronomy Calibration",
"version": "1.1.3",
"project_urls": {
"Homepage": "https://github.com/caracal-pipeline/caracal",
"Repository": "https://github.com/caracal-pipeline/caracal"
},
"split_keywords": [
"astronomy",
"visualisation",
"pipelines"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6886176d819db080068e3900b5a8aa34815ee7c27cf985ff26e9aa60c46adde3",
"md5": "37b78f91d76f02af0dd762967c0d03a8",
"sha256": "c5f70df1875768715dd693c92874af902b8f34866a12162bcdbffe0f6c27e5f5"
},
"downloads": -1,
"filename": "caracal-1.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "37b78f91d76f02af0dd762967c0d03a8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 58141067,
"upload_time": "2024-02-22T12:21:57",
"upload_time_iso_8601": "2024-02-22T12:21:57.346318Z",
"url": "https://files.pythonhosted.org/packages/68/86/176d819db080068e3900b5a8aa34815ee7c27cf985ff26e9aa60c46adde3/caracal-1.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "be2ab1e2301bc5640c894641c7051371bae7d13e04ae1bdddff5a615a6224da0",
"md5": "bee1924c52cbfd73624bd1924ff5e56d",
"sha256": "e1721b91105f970d6ab7cd2c14352a99c1083d0a99b075ec34618362e69a2d5b"
},
"downloads": -1,
"filename": "caracal-1.1.3.tar.gz",
"has_sig": false,
"md5_digest": "bee1924c52cbfd73624bd1924ff5e56d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 58087663,
"upload_time": "2024-02-22T12:22:07",
"upload_time_iso_8601": "2024-02-22T12:22:07.410547Z",
"url": "https://files.pythonhosted.org/packages/be/2a/b1e2301bc5640c894641c7051371bae7d13e04ae1bdddff5a615a6224da0/caracal-1.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-22 12:22:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "caracal-pipeline",
"github_project": "caracal",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "caracal"
}
JSON
