Metadata-Version: 2.4
Name: maser-tools
Version: 0.3.2
Summary: Tools to handle some file formats supported in maser-data package
Keywords: maser,data science,radioastronomy
Author: MASER team
Author-email: MASER team <contact.maser@obspm.fr>
License-Expression: CECILL-B
Requires-Dist: numpy>=2.0
Requires-Dist: spacepy>=0.7,<1.0
Requires-Dist: openpyxl>=3.1,<4
Requires-Dist: pytz>=2022.4
Requires-Dist: pandas>=2.2.2
Requires-Dist: requests>=2.27
Requires-Python: >=3.10
Project-URL: Homepage, https://pypi.org/project/maser-tools
Project-URL: Repository, https://gitlab.obspm.fr/maser/maser-tools
Project-URL: Documentation, https://maser.pages.obspm.fr/maser4py/
Description-Content-Type: text/markdown

# About maser-tools

maser-tools is part of the [MASER](https://maser.obspm.fr) Python libraries, with
[maser4py](https://pypi.org/project/maser4py/), maser-data and maser-plot.
It offers programs to support radio data format (e.g., CDF) and time
(e.g. leap seconds and time conversion handling):

- `maser.tools.cdf.serializer`: conversions between master binary CDF (.cdf),
  skeleton table (.skt) and Excel (.xlsx) files, as follows:

  ```
  Excel (.xlsx) <--> binary CDF (.cdf) <--> skeleton table (.skt)
  ```

- `maser.tools.cdf.cdfcompare`: comparison of two CDF files
- `maser.tools.cdf.validator`: validation of a CDF file against a model (e.g. ISTP)
- `maser.tools.time`: leap seconds and time conversions (UTC, TT2000, Julian days)

Read [main documentation](https://maser.pages.obspm.fr/maser4py/) for details.

# Installation

To install the package, run the following command:

```bash
pip install maser-tools
```

or, with [uv](https://docs.astral.sh/uv/):

```bash
uv add maser-tools        # in a uv project
uv tool install maser-tools  # to only use the maser-tools command
```

## Requirements

- Python 3.10 or later
- The CDF files are read and written with [spacepy.pycdf](https://spacepy.github.io/pycdf.html),
  which relies on the [NASA CDF library](https://cdf.gsfc.nasa.gov/html/sw_and_docs.html)
  (see [spacepy installation](https://spacepy.github.io/install.html) if it is not found).
- The conversions between binary CDF and skeleton table call the `skeletoncdf` and
  `skeletontable` programs of the [NASA CDF software](https://cdf.gsfc.nasa.gov/html/sw_and_docs.html).
  They are searched in the `$CDF_BIN` directory, then in the `$PATH`.

# Usage

## Command line interface

The programs can be run from a terminal with the `maser-tools` command
(or `python -m maser.tools`):

```bash
maser-tools --help
maser-tools skeletoncdf --help
```

Available sub-commands are:

| Sub-command     | Description                                                          |
|-----------------|----------------------------------------------------------------------|
| `skeletoncdf`   | Convert skeleton table (.skt) or Excel (.xlsx) files into binary CDF |
| `skeletontable` | Convert binary CDF files into skeleton tables (and Excel files)      |
| `leapsec`       | Leap seconds handling tool                                           |
| `cdf_compare`   | Compare two CDF files                                                |
| `cdf_validator` | Validate a CDF file                                                  |

For instance, to make a master CDF from an Excel file, then save it back as
a skeleton table and an Excel file in the `build` folder:

```bash
maser-tools skeletoncdf -o build my_master.xlsx
maser-tools skeletontable --to-xlsx -o build/skt build/my_master.cdf
```

An example of Excel file is provided in
`src/maser/tools/support/cdf/converter_example.xlsx`.

## Python

```python
from maser.tools.cdf.serializer import xlsx2cdf, cdf2xlsx

cdf_file = xlsx2cdf("my_master.xlsx", output_dir="build", overwrite=True)
xlsx_file = cdf2xlsx("build/my_master.cdf", output_dir="build", overwrite=True)
```

# Development

To contribute to the development of the package, clone the repository:

```bash
git clone https://gitlab.obspm.fr/maser/maser-tools.git
cd maser-tools
```

The project is managed with [uv](https://docs.astral.sh/uv/getting-started/installation/).
Its requirements are detailed in the `pyproject.toml` file, and pinned in the `uv.lock` file.

## Installing a local copy of maser-tools

Run the following command to create the virtual environment (`.venv`) and install
the package (in editable mode) with its development dependencies:

```bash
uv sync
```

Then run the programs from this environment with `uv run`, e.g.:

```bash
uv run maser-tools --help
```

The binary files (e.g. Excel files) are stored with [Git LFS](https://git-lfs.com):
run `git lfs install` once before cloning the repository.

## Code quality

The code is linted and formatted with [ruff](https://docs.astral.sh/ruff/), through
[pre-commit](https://pre-commit.com) hooks. Install them once with:

```bash
uv run pre-commit install
```

They can also be run on all the files with:

```bash
uv run pre-commit run --all-files
```

## Tests

Run the tests with:

```bash
uv run pytest
```

The tests calling the `skeletoncdf` and `skeletontable` programs are skipped when they
are not found.

## Publish `maser-tools` on PyPI

Build the source and wheel distributions in the `dist` folder:

```bash
uv build
```

And then publish them on PyPI (see [uv publish](https://docs.astral.sh/uv/guides/package/#publishing-your-package)):

```bash
uv publish
```
