# VCAT — VLBI Comprehensive Analysis Toolkit
**VCAT (VLBI Comprehensive Analysis Toolkit)** is a Python package that provides a unified framework for the analysis of Very Long Baseline Interferometry (VLBI) data. It was developed in collaboration with several colleagues from the VLBI community (A. Baczko, V. Bartolini, F. Eppel, F. Pötzl, L. Ricci, J. Röder, F. Rösch) to combine existing analysis scripts into a single, coherent package that supports a wide range of VLBI analysis methods.
Many of the implemented analysis techniques have been used for a long time, while others were specifically developed for recent scientific projects. VCAT is still evolving — we’d love your help! Contributions, feedback, and ideas are always welcome.
All included methods are applicable to any source with standard VLBI data available in .fits, .uvf format.
---
## Installation
The package can be installed directly from PyPI:
```bash
pip install vcat-vlbi
```
### Important Note
Many tasks run **DIFMAP** in the background.
If DIFMAP is already in your `PATH`, VCAT will automatically find it.
If you don't have DIFMAP yet, see here for a quick installation instruction for Ubuntu-based systems.
It is also possible to use many functions without DIFMAP by specifying `use_difmap=False`, but this mode is **not yet fully supported** and may have limited functionality.
---
## Overview
VCAT consists of the two core classes: **`ImageData`** and **`ImageCube`**.
### `ImageData`
`ImageData` represents a single observation of a radio source at a given frequency and epoch.
It accepts as input:
- **FITS** files (full polarization images)
- **UVFITS** (`.uvf`) visibility data
- **Modelfit** files (`.mod` or `.fits`)
For example, loading and plotting an image can quickly be done with
```python
from vcat import ImageData
image=ImageData("image.fits", uvf_file="data.uvf", model="model.mod")
image.plot()
```
Upon loading, key parameters such as image noise, integrated flux density, and fractional polarization are automatically calculated and stored as attributes.
If a modelfit file is provided, VCAT also calculates the signal-to-noise ratio (SNR), brightness temperature, and component errors automatically.
`ImageData` objects can be modified or analyzed using various tasks:
- `restore()`, `regrid()`, `shift()`, `center()` – runs DIFMAP in the background to modify full-polarization images
- `get_ridgeline()` – perform a ridgeline fit
- `align()` – align one image to another
- `plot()` – generate customizable plots of total intensity or polarization
---
### `ImageCube`
`ImageCube` is designed to handle multi-frequency, multi-epoch data sets.
It manages a collection of `ImageData` objects representing different observations of the same source and provides high-level analysis methods, including:
- **Spectral analysis**
- `get_turnover_map()` — pixel-based turnover frequency fitting
- `fit_comp_spectrum()` — component-based spectral fitting
- **Kinematic analysis**
- `get_speed()` and `get_speed2d()` — estimate apparent jet speeds and perform kinematic analysis
- **Structural analysis**
- `stack()` — stack multiple images
- `fit_collimation_profile()` — fit collimation profiles (ridgeline or component-based)
- **Spectral & polarization mapping**
- `get_spectral_index_map()` and `get_rm_map()` — compute spectral index and rotation measure maps
- **Temporal evolution & visualization**
- `plot_evolution()` and `plot_component_evolution()` — track flux density, polarization, and EVPA evolution
- `movie()` — generate interpolated movies of jet evolution in total intensity or full polarization
---
## Configuration
Usually, the standard settings are sufficient, but some parameters can be customized via a `config.yml` file.
An example configuration file is provided in the repository.
To use a custom configuration file, define the environment variable `VCAT_CONFIG` to point to it:
```bash
export VCAT_CONFIG=/path/to/config.yml
```
---
### Example `config.yml`
```yaml
# General settings:
difmap_path: "/usr/local/difmap/uvf_difmap_2.5g/"
uvw: [0, -1]
# Method selection
noise_method: "Histogram Fit"
mfit_err_method: "Schinzel12"
res_lim_method: "Kovalev05"
# Plot settings
font: "Quicksand"
plot_colors: ["#023743FF", "#FED789FF", "#72874EFF", "#476F84FF", "#A4BED5FF", "#453947FF"]
plot_markers: [".", ".", ".", ".", ".", "."]
# Cosmology
# Values from Planck Collaboration et al. 2020
H0: 67.4
Om0: 0.315
logging:
level: "INFO" # Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
log_file: "" # Optional: specify path to redirect log output to a file
```
---
## Example Scripts
Example scripts demonstrating the different functionalities of **VCAT** are available on the [VCAT website](INSERT LINK).
These examples showcase how to load data, perform analysis, and generate publication-quality plots.
---
## Citation
If you use **VCAT** in your research, please cite:
**INSERT VCAT REFERENCE HERE**
---
## License
VCAT is released under the **GNU General Public License v3.0 (GPL-3.0)**.
You are free to use, modify, and distribute this software under the terms of the GPL-3.0 license.
For more details, see the [LICENSE](LICENSE) file included with this repository.
---
**VCAT – VLBI Comprehensive Analysis Toolkit**
A unified framework for the analysis and visualization of VLBI data.
Raw data
{
"_id": null,
"home_page": "https://github.com/mpifr-vlbi/VCAT",
"name": "vcat-vlbi",
"maintainer": "Florian Eppel",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "florian@eppel.space",
"keywords": "VLBI astronomy analysis radio-astronomy radio agn jets",
"author": "Anne-Kathrin Baczko, Vieri Bartolini, Florian Eppel, Felix P\u00f6tzl, Luca Ricci, Jan R\u00f6der, Florian R\u00f6sch",
"author_email": "anne-kathrin.baczko@chalmers.se, vbartolini@mpifr-bonn.mpg.de, florian@eppel.space, luca.ricci@uni-wuerzburg.de, jroeder@mpifr-bonn.mpg.de, florian.roesch@uni-wuerzburg.de",
"download_url": "https://files.pythonhosted.org/packages/46/7c/1dbf7b600dabc2ff7f1bd19483c6b4993164ad48f7aff42f02c25456c116/vcat_vlbi-0.0.0.tar.gz",
"platform": null,
"description": "# VCAT \u2014 VLBI Comprehensive Analysis Toolkit\n\n**VCAT (VLBI Comprehensive Analysis Toolkit)** is a Python package that provides a unified framework for the analysis of Very Long Baseline Interferometry (VLBI) data. It was developed in collaboration with several colleagues from the VLBI community (A. Baczko, V. Bartolini, F. Eppel, F. P\u00f6tzl, L. Ricci, J. R\u00f6der, F. R\u00f6sch) to combine existing analysis scripts into a single, coherent package that supports a wide range of VLBI analysis methods.\n\nMany of the implemented analysis techniques have been used for a long time, while others were specifically developed for recent scientific projects. VCAT is still evolving \u2014 we\u2019d love your help! Contributions, feedback, and ideas are always welcome.\nAll included methods are applicable to any source with standard VLBI data available in .fits, .uvf format.\n\n---\n\n## Installation\n\nThe package can be installed directly from PyPI:\n\n```bash\npip install vcat-vlbi\n```\n\n### Important Note\n\nMany tasks run **DIFMAP** in the background. \nIf DIFMAP is already in your `PATH`, VCAT will automatically find it. \nIf you don't have DIFMAP yet, see here for a quick installation instruction for Ubuntu-based systems.\nIt is also possible to use many functions without DIFMAP by specifying `use_difmap=False`, but this mode is **not yet fully supported** and may have limited functionality.\n\n\n\n---\n\n## Overview\n\nVCAT consists of the two core classes: **`ImageData`** and **`ImageCube`**.\n\n### `ImageData`\n\n`ImageData` represents a single observation of a radio source at a given frequency and epoch. \nIt accepts as input:\n\n- **FITS** files (full polarization images) \n- **UVFITS** (`.uvf`) visibility data \n- **Modelfit** files (`.mod` or `.fits`)\n\nFor example, loading and plotting an image can quickly be done with\n\n```python\nfrom vcat import ImageData\n\nimage=ImageData(\"image.fits\", uvf_file=\"data.uvf\", model=\"model.mod\")\nimage.plot()\n```\n\nUpon loading, key parameters such as image noise, integrated flux density, and fractional polarization are automatically calculated and stored as attributes. \nIf a modelfit file is provided, VCAT also calculates the signal-to-noise ratio (SNR), brightness temperature, and component errors automatically.\n\n`ImageData` objects can be modified or analyzed using various tasks:\n\n- `restore()`, `regrid()`, `shift()`, `center()` \u2013 runs DIFMAP in the background to modify full-polarization images \n- `get_ridgeline()` \u2013 perform a ridgeline fit \n- `align()` \u2013 align one image to another \n- `plot()` \u2013 generate customizable plots of total intensity or polarization\n\n---\n\n### `ImageCube`\n\n`ImageCube` is designed to handle multi-frequency, multi-epoch data sets. \nIt manages a collection of `ImageData` objects representing different observations of the same source and provides high-level analysis methods, including:\n\n- **Spectral analysis** \n - `get_turnover_map()` \u2014 pixel-based turnover frequency fitting \n - `fit_comp_spectrum()` \u2014 component-based spectral fitting \n\n- **Kinematic analysis** \n - `get_speed()` and `get_speed2d()` \u2014 estimate apparent jet speeds and perform kinematic analysis\n\n- **Structural analysis** \n - `stack()` \u2014 stack multiple images \n - `fit_collimation_profile()` \u2014 fit collimation profiles (ridgeline or component-based) \n\n- **Spectral & polarization mapping** \n - `get_spectral_index_map()` and `get_rm_map()` \u2014 compute spectral index and rotation measure maps \n\n- **Temporal evolution & visualization** \n - `plot_evolution()` and `plot_component_evolution()` \u2014 track flux density, polarization, and EVPA evolution \n - `movie()` \u2014 generate interpolated movies of jet evolution in total intensity or full polarization \n\n---\n\n## Configuration\n\nUsually, the standard settings are sufficient, but some parameters can be customized via a `config.yml` file. \nAn example configuration file is provided in the repository.\n\nTo use a custom configuration file, define the environment variable `VCAT_CONFIG` to point to it:\n\n```bash\nexport VCAT_CONFIG=/path/to/config.yml\n```\n\n---\n\n### Example `config.yml`\n\n```yaml\n# General settings:\ndifmap_path: \"/usr/local/difmap/uvf_difmap_2.5g/\"\nuvw: [0, -1]\n\n# Method selection\nnoise_method: \"Histogram Fit\"\nmfit_err_method: \"Schinzel12\"\nres_lim_method: \"Kovalev05\"\n\n# Plot settings\nfont: \"Quicksand\"\nplot_colors: [\"#023743FF\", \"#FED789FF\", \"#72874EFF\", \"#476F84FF\", \"#A4BED5FF\", \"#453947FF\"]\nplot_markers: [\".\", \".\", \".\", \".\", \".\", \".\"]\n\n# Cosmology\n# Values from Planck Collaboration et al. 2020\nH0: 67.4\nOm0: 0.315\n\nlogging:\n level: \"INFO\" # Options: DEBUG, INFO, WARNING, ERROR, CRITICAL\n log_file: \"\" # Optional: specify path to redirect log output to a file\n```\n\n---\n\n## Example Scripts\n\nExample scripts demonstrating the different functionalities of **VCAT** are available on the [VCAT website](INSERT LINK). \nThese examples showcase how to load data, perform analysis, and generate publication-quality plots.\n\n---\n\n## Citation\n\nIf you use **VCAT** in your research, please cite: \n**INSERT VCAT REFERENCE HERE**\n\n---\n\n## License\n\nVCAT is released under the **GNU General Public License v3.0 (GPL-3.0)**. \nYou are free to use, modify, and distribute this software under the terms of the GPL-3.0 license. \nFor more details, see the [LICENSE](LICENSE) file included with this repository.\n\n---\n\n**VCAT \u2013 VLBI Comprehensive Analysis Toolkit** \nA unified framework for the analysis and visualization of VLBI data.\n\n\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "VLBI Comprehensive Analysis Toolkit",
"version": "0.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/mpifr-vlbi/VCAT",
"Documentation": "https://github.com/mpifr-vlbi/VCAT",
"Homepage": "https://github.com/mpifr-vlbi/VCAT"
},
"split_keywords": [
"vlbi",
"astronomy",
"analysis",
"radio-astronomy",
"radio",
"agn",
"jets"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c30c11f71a37b7462c4d52091663bc1e30defc6ac27f88c7bd7c9c6801d426f5",
"md5": "0097e30da167085deb7f27214e5b3e97",
"sha256": "3de0a4b3abd62f0cdfe7cded48001d3b3496428545158d215f063ca68b6ae3de"
},
"downloads": -1,
"filename": "vcat_vlbi-0.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0097e30da167085deb7f27214e5b3e97",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 126917,
"upload_time": "2025-10-20T13:34:23",
"upload_time_iso_8601": "2025-10-20T13:34:23.918627Z",
"url": "https://files.pythonhosted.org/packages/c3/0c/11f71a37b7462c4d52091663bc1e30defc6ac27f88c7bd7c9c6801d426f5/vcat_vlbi-0.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "467c1dbf7b600dabc2ff7f1bd19483c6b4993164ad48f7aff42f02c25456c116",
"md5": "48568bf207cf18ee2cce13162f6dfea5",
"sha256": "3a285746a4f566c3ed433197f371d6ef0e1e3b59dc2d2f3caf9b66a67aa8f84b"
},
"downloads": -1,
"filename": "vcat_vlbi-0.0.0.tar.gz",
"has_sig": false,
"md5_digest": "48568bf207cf18ee2cce13162f6dfea5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 122762,
"upload_time": "2025-10-20T13:34:25",
"upload_time_iso_8601": "2025-10-20T13:34:25.611160Z",
"url": "https://files.pythonhosted.org/packages/46/7c/1dbf7b600dabc2ff7f1bd19483c6b4993164ad48f7aff42f02c25456c116/vcat_vlbi-0.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-20 13:34:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mpifr-vlbi",
"github_project": "VCAT",
"github_not_found": true,
"lcname": "vcat-vlbi"
}
JSON
