getting_started.md

Getting started

Installation

VASCA is tested to work with Python 3.10 and 3.11. Typically, you want to create a new Python environment, e.g., with pyenv-virtualenv or mamba:

mamba create -n vasca python=3.11
mamba activate vasca

For standard usage, install VASCA from PyPi:

pip install vasca

Standard usage covers all pipeline functions for data from instruments that are already implemented in VASCA. For more information consult the list of supported instruments.

In order to extend VASCA to incorporate another instrument's data, install it directly from the Github repository.

pip install -e git+https://github.com/rbuehler/vasca

This will ensure that all resources for testing and the jupyter examples are included in the installation.

Resource management

Management of the input observational data is handled in VASCA via the class. Before first use, users need to edit environment variables that specify the data storage locations in an .env file in VASCA's root directory.

:::{Tip} The easiest way to set up the resource manager is to duplicate the .env_template and rename it. Then edit your paths to the location of cloud-synced or local directories. :::

The system is very flexible and can be tailored to your needs. New environment variables specifying storage locations can be added in the resource_envs.yml file. New data items that might be required to support additional instruments can be added in the resource_catalog.yml file.

Running the pipeline and post-processing

To start the pipeline processing go into the vasca directory and start the command line script:

vasca-pipe <path-to-config.yml>

See the user guide for more infos on how to configure the pipeline in the yaml file.

We use Jupyter Lab for post-processing, with functional examples provided in vasca/examples.

Coding guidelines

We use the PEP 8 coding conventions. Before contributing, please consider the use of automatic code formatting tools. We recommend ruff. It is a one-stop-shop that combines all style rules from tools like isort, flake8, and black. All ruff configurations can be found in the pyproject.toml file. We set 88 characters as the default line width. The recommended Python version to use is 3.11. For docstrings, we use the numpy format.

Build the documentation

For documentation, we use Sphinx. To build it locally, run the following command from VASCA's root directory:

sphinx-build docs docs/_build

To create Unified Modeling Language diagrams, install pyreverse and graphviz, then run:

pyreverse vasca -o png -d ./docs/