Metadata-Version: 2.4
Name: mocpy
Version: 0.21.0
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Rust
Classifier: License :: OSI Approved :: BSD License
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Dist: astropy
Requires-Dist: numpy
Requires-Dist: regions ; extra == 'astropy-regions'
Requires-Dist: pre-commit>=2.20 ; extra == 'dev'
Requires-Dist: pytest>6.0 ; extra == 'dev'
Requires-Dist: pytest-mock ; extra == 'dev'
Requires-Dist: pytest-cov ; extra == 'dev'
Requires-Dist: requests ; extra == 'dev'
Requires-Dist: regions ; extra == 'dev'
Requires-Dist: ruff>=0.5.0 ; extra == 'dev'
Requires-Dist: cdshealpix>=0.6.4 ; extra == 'dev'
Requires-Dist: astropy-sphinx-theme ; extra == 'docs'
Requires-Dist: nbsphinx ; extra == 'docs'
Requires-Dist: numpydoc ; extra == 'docs'
Requires-Dist: sphinx-astropy ; extra == 'docs'
Requires-Dist: sphinx-collections ; extra == 'docs'
Requires-Dist: sphinx-copybutton ; extra == 'docs'
Requires-Dist: sphinx-gallery ; extra == 'docs'
Requires-Dist: sphinxcontrib-bibtex ; extra == 'docs'
Requires-Dist: ipython ; extra == 'docs'
Requires-Dist: toml ; extra == 'docs'
Requires-Dist: astropy-healpix ; extra == 'docs'
Requires-Dist: matplotlib ; extra == 'notebooks'
Requires-Dist: cdshealpix>=0.6.4 ; extra == 'notebooks'
Requires-Dist: networkx>=2.5 ; extra == 'notebooks'
Requires-Dist: astroquery>=0.4.9 ; extra == 'notebooks'
Requires-Dist: astropy-healpix ; extra == 'notebooks'
Requires-Dist: ipyaladin ; extra == 'notebooks'
Requires-Dist: regions ; extra == 'notebooks'
Requires-Dist: nbmake ; extra == 'notebooks'
Requires-Dist: matplotlib ; extra == 'plots'
Requires-Dist: cdshealpix>=0.6.4 ; extra == 'plots'
Requires-Dist: networkx>=2.5 ; extra == 'plots'
Requires-Dist: requests ; extra == 'query'
Provides-Extra: astropy_regions
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: notebooks
Provides-Extra: plots
Provides-Extra: query
License-File: LICENSE
Summary: MOCPy allows to create and manipulate MOCs (Multi-Order Coverage maps)
Keywords: astronomy,astrophysics,HEALPix
Author-email: Matthieu Baumann <matthieu.baumann@astro.unistra.fr>, Thomas Boch <thomas.boch@astro.unistra.fr>, Manon Marchand <manon.marchand@astro.unistra.fr>, "F.-X. Pineau" <francois-xavier.pineau@astro.unistra.fr>
License: BSD-3-Clause
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/cds-astro/mocpy/blob/master/CHANGELOG.md
Project-URL: Documentation, https://cds-astro.github.io/mocpy/
Project-URL: Issues, https://github.com/cds-astro/mocpy/issues
Project-URL: Repository, https://github.com/cds-astro/mocpy

# MOCPy

[![PyPI version](https://badge.fury.io/py/mocpy.svg)](https://badge.fury.io/py/MOCPy)
[![python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14%20%7C%203.15-informational)](https://www.python.org/downloads/ "https://www.python.org/downloads/")
[![Build/Test status](https://github.com/cds-astro/mocpy/actions/workflows/test.yml/badge.svg)](https://github.com/cds-astro/mocpy/actions/workflows/test.yml)
[![Doc](https://img.shields.io/badge/Documentation-link-green.svg)](https://cds-astro.github.io/mocpy/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15517957.svg)](https://doi.org/10.5281/zenodo.15517957)

<img align="right" width="200px" alt="mocpy's logo" src="./docs/_static/MOCpy-light.svg">

MOCPy is a Python library allowing easy creation and manipulation of MOCs (Multi-Order Coverage maps).

MOC is an [IVOA standard](https://ivoa.net/documents/MOC/20220727/index.html) enabling
description of arbitrary sky, time, (or frequency) coverages.

## What's in MOCpy?

|           | Space              | Time               | Frequency          |
|-----------|--------------------|--------------------|--------------------|
| Space     | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Time      | :white_check_mark: | :white_check_mark: | :x:                |
| Frequency | :white_check_mark: | :x:                | :white_check_mark: |

There is support for one dimensional MOCs:

- **Space MOCs**. The sky tesselation is based on the HEALPix sky tessellation, it maps
  regions of the sky into hierarchically grouped cells.
- **Time MOCs**. The segmentation of the time axis is linear. This is described in the
  MOC standard since its version 2.0.
- **Frequency MOCs**. :warning: this is not standard yet! The segmentation of the frequency
  axis is logarithmic. See [this IVOA presentation][https://wiki.ivoa.net/internal/IVOA/InterOpMay2023Apps/FMOC_IVOA_Bologne_Fernique.pdf] for a description.

But also these combinations:

- **Space-Time MOCs**
- **Space-Frequency MOCs**

![a MOC plotted with MOCPy](./resources/readme.png)

*Rendered with MOCpy!*

## Quick example

```python
from mocpy import MOC
import astropy.units as u

# Create a MOC from a cone
field_of_view = MOC.from_cone(lon=0*u.deg, lat=0*u.deg, radius=10*u.deg, max_depth=7)

# Check if a position is covered
field_of_view.contains_lonlat(0*u.deg, 0*u.deg)  # True

# Combine MOCs with set operations
field_of_view2 = MOC.from_cone(lon=8*u.deg, lat=8*u.deg, radius=5*u.deg, max_depth=7)
coverage = field_of_view | field_of_view2

# Quick preview of the combined field of views
coverage.display_preview()
```

![A quick display of the coverage. The two MOCs are combined into one.](./resources/readme_quick_example.png)

## Other resources

For a command line tool, see the [moc-cli](https://github.com/cds-astro/cds-moc-rust/tree/main/crates/cli).

For more information about MOCPy's Rust core, see the [moc crate](https://crates.io/crates/moc)

## Installation

### Latest stable version

- from pip `pip install mocpy`
- from conda `conda install -c conda-forge mocpy`

### Unreleased latest version

To install `MOCPy` from this repository, make sure you have Python (https://www.python.org/downloads/)
and Rust (https://www.rust-lang.org/tools/install) on your machine. Then, run

```
pip install git+https://github.com/cds-astro/mocpy.git
```

## To run the notebooks

The example notebooks require additional dependencies. They can be installed with

```sh
pip install mocpy[notebooks]
```

## Development installation

Contributions are very welcome. To build and test the library, clone this repository,
make sure that you've got Rust on your machine (https://www.rust-lang.org/tools/install).
Check that the Rust version you have is more recent than the minimal version declared in
`Cargo.toml` under `rust-version` and do:

```sh
pip install pre-commit
pre-commit install
pip install maturin
maturin develop --release
```

And the library is ready to be edited. After a change on the Rust side, you'll have to
do `maturin develop --release` again. If you only edit the python side, then a
`pip install .` at the root of the repository will suffice.

We use pre-commit to keep consistent style conventions between all of us. This means
that your commits will not pass if they require modifications. If this happens, do the
required changes, `git add` the files again and attempt to commit again as usual.

To run the tests, do:

```sh
pip install .[dev]
python -m pytest
```

The tests that require to download remote data from external servers don't run by
default. To execute them, do:

```sh
python -m pytest --run-remote
```

To check that the documentation builds. Make sure you have pandoc
(https://pandoc.org/installing.html) and do:

```sh
pip install .[docs,plots]
cd docs
make clean html
```
The output will be in `docs/_build/html`.

## For use in pyodide

Wheels that run in pyodide can be downloaded from each github's release for the module.

## Other python packages for MOCs

- https://github.com/grahambell/pymoc/

