spiceracs 0.1.0
Processing polarized RACS data products.
License: BSD 3-clause "New" or "Revised License
Requires Python: >=3.6.0


# SPICE-RACS
**S**pectra and **P**olarization **I**n **C**utouts of **E**xtragalactic **S**ources from **R**ACS

Scripts for processing polarized RACS data products.


## Installation
```
pip install spiceracs
```
Or, after cloning this repo, please run:
```
cd SPICERACS/
pip install -e .
```
This will install the python dependencies and the command-line scrips. Please note: this package requires `python >= 3.6`.

### Third-party tools
Additionally, this package also requires `RM-Tools`, `java >= 8`, and `mongodb` to be installed. Details on how to install these can be found at their respective websites:
* [RM-Tools](https://github.com/CIRADA-Tools/RM)
* [Java](https://www.java.com/en/download/)
* [MongoDB](https://www.mongodb.com/what-is-mongodb)

### Parallelisation
If you wish to use MPI for parallelisation, please also make sure some implementation (such as [OpenMPI](https://www.open-mpi.org/)) is also installed. If MPI is not available, then python multiprocessing can be used. Please note that multiprocessing is not capable of going across nodes in an HPC environment. 

## Getting started
It is recommended to use the command-line tools. Alternatively, scripts for processing RACS data are located in `spiceracs/`. 

Bash scripts which run everything together on PBS or SBATCH systems are located in `submit/`.

To keep track of the many files, and associated metadata, these scripts use MongoDB. Additionally, the scripts are intended to be run in order (pipeline-style). 

Currently, the order to run each script is:

0. `mongod --dbpath /path/to/database/ &` -- This initialises MongoDB in a directory of your choosing.
1. `spicecutout` or `spiceracs/cutout.py` -- Produce cubelets from a RACS field using a Selavy table.
2. The datacubes can be removed from disk, if required.
Optional:
    3. `spiceunresolved` or `spiceracs/unresolved.py` -- Find unresolved sources from a Selavy catalogue.
    4. `spicemoments` or `spiceracs/moments_oncuts.py` -- Make Faraday moment maps for Farnes+ (2018) method.
    5. `spicepolfind` or `spiceracs/polfind.py`-- Find polarized sources in a RACS field using the Farnes+ (2018) method.
6. `spicermsynth` or `spiceracs/rmsynth_oncuts.py` -- Run RM synthesis on cutouts.
7. `spicermclean` or `spiceracs/rmclean_oncuts.py` -- Run RM-CLEAN on cutouts.
8.  `spicemakecat` or `spiceracs/makecat.py` -- Make RM catalogue from results.

## Acknowledging
### Third-party software
This package utilises a number of third-party libraries. Please acknowledge these, as appropriate, if you use these tools for your research.

List of third party libraries:
* [Numpy](https://numpy.org/)
* [Matplotlib](https://matplotlib.org/)
* [Astropy](https://www.astropy.org/)
* [RM-Tools](https://github.com/CIRADA-Tools/RM)
* [Spectral-Cube](https://spectral-cube.readthedocs.io/)
* [tqdm](https://tqdm.github.io/) 
* [MongoDB](https://www.mongodb.com/) / [pymongo](https://api.mongodb.com/python/current/) 
* [Schwimmbad](https://schwimmbad.readthedocs.io/)
* [AegeanTools](https://github.com/PaulHancock/Aegean)
* [STILTS](http://www.star.bristol.ac.uk/~mbt/stilts/)