[](https://pypi.python.org/pypi/skymapper/)
[](https://github.com/pmelchior/skymapper/blob/master/LICENSE.md)
# Skymapper
*A collection of matplotlib instructions to map astronomical survey data from the celestial sphere onto 2D.*
The purpose of this package is to facilitate interactive work as well as the the creation of publication-quality plots with a python-based workflow many astronomers are accustomed to. The primary motivation is a truthful representation of samples and fields from the curved sky in planar figures, which becomes relevant when sizable portions of the sky are observed.
What can it do? For instance, find the optimal projection for a given list of spherical coordinates and [creating a density map](examples/example1.py) from a catalog in a few lines:
```python
import skymapper as skm
# 1) construct a projection, here Albers
# lon_0, lat_0: longitude/latitude that map onto 0/0
# lat_1, lat_2: reference latitudes for conic projection
lon_0, lat_0, lat_1, lat_2 = 27.35, -37.04, -57.06, -11.34
proj = skm.Albers(lon_0, lat_0, lat_1, lat_2)
# alternative: define the optimal projection for set of coordinates
# by minimizing the variation in distortion
crit = skm.stdDistortion
proj = skm.Albers.optimize(ra, dec, crit=crit)
# 2) construct map: will hold figure and projection
# the outline of the sphere can be styled with kwargs for matplotlib Polygon
map = skm.Map(proj)
# 3) add graticules, separated by 15 deg
# the lines can be styled with kwargs for matplotlib Line2D
# additional arguments for formatting the graticule labels
sep = 15
map.grid(sep=sep)
# 4) add data to the map, e.g.
# make density plot
nside = 32
mappable = map.density(ra, dec, nside=nside)
cb = map.colorbar(mappable, cb_label="$n_g$ [arcmin$^{-2}$]")
# add scatter plot
map.scatter(ra_scatter, dec_scatter, s=size_scatter, edgecolor='k', facecolor='None')
# focus on relevant region
map.focus(ra, dec)
```
The `map` instance has several members, most notably
* `fig`: the `matplotlib.Figure` that holds the map
* `ax`: the `matplotlib.Axes` that holds the map
The syntax mimics `matplotlib` as closely as possible. Currently supported are canonical plotting functions
* `plot`
* `scatter`
* `hexbin` for binning and interpolating samples
* `colorbar` with an optional argument `cb_label` to set the label
* `text` with an optional `direction in ['parallel','meridian']` argument to align along either graticule
as well as special functions
* `footprint` to show the region covered by a survey
* `vertex` to plot a list of simple convex polygons
* `healpix` to plot a healpix map as a list of polygons
* `density` to create a density map in healpix cells
* `extrapolate` to generate a field from samples over the entire sky or a subregion
Exploratory and interactive workflows are specifically supported. For instance, you can zoom and pan, also scroll in/out (google-maps style), and the `map` will automatically update the location of the graticule labels, which are not regularly spaced.
The styling of graticules can be changed by calling `map.grid()` with different parameters. Finer-grained access is provided by
* `map.labelParallelsAtFrame()` creates/styles the vertical axis labels at the intersection of the grid parallels
* `map.labelMeridiansAtFrame()` creates/styles the horizontal axis labels at the intersection of the grid meridians
* `map.labelParallelsAtMeridian()` creates/styles parallels at a given meridian (useful for all-sky maps)
* `map.labelMeridiansAtParallel()` creates/styles meridians at a given parallel (useful for all-sky maps)
## Installation and Prerequisites
You can either clone the repo and install by `python setup.py install` or get the latest release with
```
pip install skymapper
```
Dependencies:
* numpy
* scipy
* matplotlib
* healpy
For survey footprints, you'll need [`pymangle`](https://github.com/esheldon/pymangle).
## Background
The essential parts of the workflow are
1. Creating the `Projection`, e.g. `Hammer`, `Albers`, `WagnerIV`
2. Setting up a `Map` to hold the projection and matplotlib figure, ax, ...
3. Add data to the map
Several map projections are available, the full list is stored in the dictionary `projection_register`. If the projection you want isn't included, open an issue, or better: create it yourself (see below) and submit a pull request.
There are two conventions for longitudes in astronomy. The standard frame, used for instance for world maps or Galactic maps, has a longitudinal coordinates in the range [-180 .. 180] deg, which increase west to east (in other words, on the map east is right). The equatorial (RA/Dec) frame is left-handed (i.e. on the map east is left) and has coordinates in the range [0 .. 360] deg. To determine the convention, `Projection` has an argument `lon_type`, which can be either `"lon"` or `"ra"` for standard or equatorial, respectively. The default is `lon_type="ra"`.
Map projections can preserve sky area, angles, or distances, but never all three. That means defining a suitable projection must be a compromise. For most applications, sizes should exactly be preserved, which means that angles and distances may not be. The optimal projection for a given list of `ra`, `dec` can be found by calling:
```python
crit = skm.projection.stdDistortion
proj = skm.Albers.optimize(ra, dec, crit=crit)
```
This optimizes the `Albers` projection parameters to minimize the variance of the map distortion (i.e. the apparent ellipticity of a true circle on the sky). Alternative criteria are e.g. `maxDistortion` or `stdScale` (for projections that are not equal-area).
### Creating a custom projection
For constructing your own projection, derive from [`Projection`](skymapper/projection.py). You'll see that every projection needs to implement at least these methods:
* `transform` to map from spherical to map coordinates x/y
* `invert` to map from x/y to spherical (if not implemented defaults to basic and slow BFGS inversion)
If the projection has several parameters, you will want to create a special `@classmethod optimize` because the default one only determines the best longitude reference. An example for that is given in e.g. `ConicProjection.optimize`.
### Creating/using a survey
Several surveys are predefined and listed in the `survey_register` dictionary. If the survey you want isn't included, don't despair. To create one can derive a class from [`Survey`](skymapper/survey/__init__.py), which only needs to implement one method:
`def contains(self, ra, dec)` to determine whether RA, Dec are inside the footprint.
If this looks like the [`pymangle`](https://github.com/esheldon/pymangle) interface: it should. That means that you can avoid the overhead of having to define a survey and e.g. pass a `pymangle.Mangle` object directly to `footprint()`.
### Limitation(s)
The combination of `Map` and `Projection` is *not* a [matplotlib transformation](http://matplotlib.org/users/transforms_tutorial.html). Among several reasons, it is very difficult (maybe impossible) to work with the `matplotlib.Axes` that are not rectangles or ellipses. So, we decided to split the problem: making use of matplotlib for lower-level graphics primitive and layering the map-making on top of it. This way, we can control e.g. the interpolation method on the sphere or the location of the tick labels in a way consistent with visual expectations from hundreds of years of cartography. While `skymapper` tries to follow matplotlib conventions very closely, some methods may not work as expected. Open an issue if you think you found such a case.
In particular, we'd appreciate help to make sure that the interactive features work well on all matplotlib backends.
Raw data
{
"_id": null,
"home_page": "https://github.com/pmelchior/skymapper",
"name": "skymapper",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "visualization,map projection,matplotlib",
"author": "Peter Melchior",
"author_email": "peter.m.melchior@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ba/23/3da6c3dde40e505f0abb0c138b7f46e881e0716d60d348e63ff6ec4a29bb/skymapper-0.4.4.tar.gz",
"platform": null,
"description": "[](https://pypi.python.org/pypi/skymapper/)\n[](https://github.com/pmelchior/skymapper/blob/master/LICENSE.md)\n\n# Skymapper\n\n*A collection of matplotlib instructions to map astronomical survey data from the celestial sphere onto 2D.*\n\nThe purpose of this package is to facilitate interactive work as well as the the creation of publication-quality plots with a python-based workflow many astronomers are accustomed to. The primary motivation is a truthful representation of samples and fields from the curved sky in planar figures, which becomes relevant when sizable portions of the sky are observed.\n\nWhat can it do? For instance, find the optimal projection for a given list of spherical coordinates and [creating a density map](examples/example1.py) from a catalog in a few lines:\n\n```python\nimport skymapper as skm\n\n# 1) construct a projection, here Albers\n# lon_0, lat_0: longitude/latitude that map onto 0/0\n# lat_1, lat_2: reference latitudes for conic projection\nlon_0, lat_0, lat_1, lat_2 = 27.35, -37.04, -57.06, -11.34\nproj = skm.Albers(lon_0, lat_0, lat_1, lat_2)\n\n# alternative: define the optimal projection for set of coordinates\n# by minimizing the variation in distortion\ncrit = skm.stdDistortion\nproj = skm.Albers.optimize(ra, dec, crit=crit)\n\n# 2) construct map: will hold figure and projection\n# the outline of the sphere can be styled with kwargs for matplotlib Polygon\nmap = skm.Map(proj)\n\n# 3) add graticules, separated by 15 deg\n# the lines can be styled with kwargs for matplotlib Line2D\n# additional arguments for formatting the graticule labels\nsep = 15\nmap.grid(sep=sep)\n\n# 4) add data to the map, e.g.\n# make density plot\nnside = 32\nmappable = map.density(ra, dec, nside=nside)\ncb = map.colorbar(mappable, cb_label=\"$n_g$ [arcmin$^{-2}$]\")\n\n# add scatter plot\nmap.scatter(ra_scatter, dec_scatter, s=size_scatter, edgecolor='k', facecolor='None')\n\n# focus on relevant region\nmap.focus(ra, dec)\n```\n\n\n\nThe `map` instance has several members, most notably\n\n* `fig`: the `matplotlib.Figure` that holds the map\n* `ax`: the `matplotlib.Axes` that holds the map\n\nThe syntax mimics `matplotlib` as closely as possible. Currently supported are canonical plotting functions\n\n* `plot`\n* `scatter`\n* `hexbin` for binning and interpolating samples\n* `colorbar` with an optional argument `cb_label` to set the label\n* `text` with an optional `direction in ['parallel','meridian']` argument to align along either graticule\n\nas well as special functions\n\n* `footprint` to show the region covered by a survey\n* `vertex` to plot a list of simple convex polygons\n* `healpix` to plot a healpix map as a list of polygons\n* `density` to create a density map in healpix cells\n* `extrapolate` to generate a field from samples over the entire sky or a subregion\n\nExploratory and interactive workflows are specifically supported. For instance, you can zoom and pan, also scroll in/out (google-maps style), and the `map` will automatically update the location of the graticule labels, which are not regularly spaced.\n\nThe styling of graticules can be changed by calling `map.grid()` with different parameters. Finer-grained access is provided by \n\n* `map.labelParallelsAtFrame()` creates/styles the vertical axis labels at the intersection of the grid parallels\n* `map.labelMeridiansAtFrame()` creates/styles the horizontal axis labels at the intersection of the grid meridians\n* `map.labelParallelsAtMeridian()` creates/styles parallels at a given meridian (useful for all-sky maps)\n* `map.labelMeridiansAtParallel()` creates/styles meridians at a given parallel (useful for all-sky maps)\n\n## Installation and Prerequisites\n\nYou can either clone the repo and install by `python setup.py install` or get the latest release with\n\n```\npip install skymapper\n```\n\nDependencies:\n\n* numpy\n* scipy\n* matplotlib\n* healpy\n\nFor survey footprints, you'll need [`pymangle`](https://github.com/esheldon/pymangle).\n\n## Background\n\nThe essential parts of the workflow are\n\n1. Creating the `Projection`, e.g. `Hammer`, `Albers`, `WagnerIV`\n2. Setting up a `Map` to hold the projection and matplotlib figure, ax, ...\n3. Add data to the map\n\nSeveral map projections are available, the full list is stored in the dictionary `projection_register`. If the projection you want isn't included, open an issue, or better: create it yourself (see below) and submit a pull request.\n\nThere are two conventions for longitudes in astronomy. The standard frame, used for instance for world maps or Galactic maps, has a longitudinal coordinates in the range [-180 .. 180] deg, which increase west to east (in other words, on the map east is right). The equatorial (RA/Dec) frame is left-handed (i.e. on the map east is left) and has coordinates in the range [0 .. 360] deg. To determine the convention, `Projection` has an argument `lon_type`, which can be either `\"lon\"` or `\"ra\"` for standard or equatorial, respectively. The default is `lon_type=\"ra\"`.\n\nMap projections can preserve sky area, angles, or distances, but never all three. That means defining a suitable projection must be a compromise. For most applications, sizes should exactly be preserved, which means that angles and distances may not be. The optimal projection for a given list of `ra`, `dec` can be found by calling:\n\n\n```python\ncrit = skm.projection.stdDistortion\nproj = skm.Albers.optimize(ra, dec, crit=crit)\n```\n\nThis optimizes the `Albers` projection parameters to minimize the variance of the map distortion (i.e. the apparent ellipticity of a true circle on the sky). Alternative criteria are e.g. `maxDistortion` or `stdScale` (for projections that are not equal-area).\n\n### Creating a custom projection\n\nFor constructing your own projection, derive from [`Projection`](skymapper/projection.py). You'll see that every projection needs to implement at least these methods: \n\n* `transform` to map from spherical to map coordinates x/y\n* `invert` to map from x/y to spherical (if not implemented defaults to basic and slow BFGS inversion)\n\nIf the projection has several parameters, you will want to create a special `@classmethod optimize` because the default one only determines the best longitude reference. An example for that is given in e.g. `ConicProjection.optimize`.\n\n### Creating/using a survey\n\nSeveral surveys are predefined and listed in the `survey_register` dictionary. If the survey you want isn't included, don't despair. To create one can derive a class from [`Survey`](skymapper/survey/__init__.py), which only needs to implement one method:\n\n\u200b\t`def contains(self, ra, dec)` to determine whether RA, Dec are inside the footprint.\n\nIf this looks like the [`pymangle`](https://github.com/esheldon/pymangle) interface: it should. That means that you can avoid the overhead of having to define a survey and e.g. pass a `pymangle.Mangle` object directly to `footprint()`.\n\n### Limitation(s)\n\nThe combination of `Map` and `Projection` is *not* a [matplotlib transformation](http://matplotlib.org/users/transforms_tutorial.html). Among several reasons, it is very difficult (maybe impossible) to work with the `matplotlib.Axes` that are not rectangles or ellipses. So, we decided to split the problem: making use of matplotlib for lower-level graphics primitive and layering the map-making on top of it. This way, we can control e.g. the interpolation method on the sphere or the location of the tick labels in a way consistent with visual expectations from hundreds of years of cartography. While `skymapper` tries to follow matplotlib conventions very closely, some methods may not work as expected. Open an issue if you think you found such a case.\n\nIn particular, we'd appreciate help to make sure that the interactive features work well on all matplotlib backends.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Mapping astronomical survey data on the sky, handsomely",
"version": "0.4.4",
"project_urls": {
"Homepage": "https://github.com/pmelchior/skymapper"
},
"split_keywords": [
"visualization",
"map projection",
"matplotlib"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "58b188e2d8512ae786260f0f7506e485e4559a550695f329f0d826ddb65fb415",
"md5": "0cb16ced55fdbffb4fbf6a836e1bc7ca",
"sha256": "2db08b5483dddaefb12bb5765cd819ec6067bc3ea24f10eba2f62ea8efc80c3e"
},
"downloads": -1,
"filename": "skymapper-0.4.4-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "0cb16ced55fdbffb4fbf6a836e1bc7ca",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 42070,
"upload_time": "2023-06-21T18:44:13",
"upload_time_iso_8601": "2023-06-21T18:44:13.910978Z",
"url": "https://files.pythonhosted.org/packages/58/b1/88e2d8512ae786260f0f7506e485e4559a550695f329f0d826ddb65fb415/skymapper-0.4.4-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ba233da6c3dde40e505f0abb0c138b7f46e881e0716d60d348e63ff6ec4a29bb",
"md5": "7ec12be7a9e68f1b85dd60730a4a41c7",
"sha256": "aeb8cb6bf67c1a4bbe35ca8b9bc0d63d7ad6458d54866751e1dffa7225a946c9"
},
"downloads": -1,
"filename": "skymapper-0.4.4.tar.gz",
"has_sig": false,
"md5_digest": "7ec12be7a9e68f1b85dd60730a4a41c7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 52566,
"upload_time": "2023-06-21T18:44:15",
"upload_time_iso_8601": "2023-06-21T18:44:15.534696Z",
"url": "https://files.pythonhosted.org/packages/ba/23/3da6c3dde40e505f0abb0c138b7f46e881e0716d60d348e63ff6ec4a29bb/skymapper-0.4.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-21 18:44:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pmelchior",
"github_project": "skymapper",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "skymapper"
}
JSON
