astropy / regions

Astropy package for region handling

Regions

Regions is an Astropy package for region handling.

Please see the online documentation for installation instructions and usage information.

Citing Regions

If you use Regions for a project that leads to a publication, whether directly or as a dependency of another package, please include the following acknowledgment:

This research made use of Regions, an Astropy package for region
handling (Bradley et al. 202X).

where (Bradley et al. 202X) is a citation to the Zenodo record of the Regions version that was used. We also encourage citations in the main text wherever appropriate. Please see the CITATION file for details and an example BibTeX entry.

License

Regions is licensed under a BSD 3-clause license. Please see the LICENSE file for details.

regions's Issues

Return a Mask class from the to_mask() method

Just to follow-up on #30, it would be better if the to_mask() method returns a Mask object. The Mask object would be initialized with the mask array and the tuple slice and it could then handle the cases where the aperture is partially (or completely) outside of the image.

API question: to_patch or Artist or...?

What API should we adopt for plotting region objects?

Options we have considered:

• region.to_patch()/region.to_patch_collection()
• region.Artist
• region.Patch/PatchCollection

Which do you prefer? cc @joleroi, @astrofrog @cdeil

ds9 reader regression: whitespace at front of line

this region: 'galactic; circle(+0:14:26.064,+0:00:45.206,30.400")' fails to parse because of the whitespace. See #130 (comment). Fix forthcoming.

Implement composite regions in ds9 parser

This probably requires implementation of composite regions... anywhere.

Composite regions should have at least:

• container for other regions
• some method to convert to matplotlib patch collections

__contains__ scope?

At the moment the Region base classes have an abstract method: __contains__

https://github.com/astropy/regions/blob/master/regions/core/core.py#L195

The docstring suggests that this is supposed to work for a list of SkyCoords

https://github.com/astropy/regions/blob/master/regions/core/core.py#L197

I don't think this works/is a good idea

In [35]: c1
Out[35]:
CircleSkyRegion
Center:<SkyCoord (Galactic): (l, b) in deg
    (0.0, 0.0)>
Radius:1.0 deg

In [36]: coords
Out[36]:
<SkyCoord (Galactic): (l, b) in deg
    [(1.2, 1.2), (0.5, 0.5), (0.7, 0.7)]>

In [37]: c1.__contains__(coords)
Out[37]: array([False,  True,  True], dtype=bool)

In [38]: coords in c1
---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
/tmp/test.py in <module>()
----> 1 coords in c1

ValueError: The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()

I looks like the in operator checks for a (non-array) boolean output of __contains__. This makes sense if you think about statements like

if coord in regions:
    do something

I would suggest changing the API to regions.contains(coords) (without the underscores).

Do you agree @keflavich @astrofrog @bsipocz ?

Have a standardized way of testing correctness

For testing correctness, the pattern is always going to be the same - create a region with some arguments, then check that calling certain fixed methods or properties return a given result. We could therefore simplify the boilerplate by simply making it possible to have a list of regions to test and provide reference results. One way to do this would be to have the regions stored in a serialized way, and have a mapping from serialized file to reference results. For instance, we could have a table with the following format (just an idea to start the discussion):

region_file,    area,    to_mask,         to_pixel
region1.xml,     5.4,  mask1.fits, region1_pix.xml
region2.xml,     2.3,  mask2.fits, region2_pix.xml

We then have a parametrized test that loops over each entry and gives a pass/fail status. This would save writing a lot of code and make it easier to have many tests for corner cases, etc. It would also be easy to inspect things like masks.

Ideally we would use a serialization format simpler than XML for this so that these can be written by hand, not generated.

Is photometric regions within the scope of astropy.regions?

Hello

I wasn't present at any of the region discussion/sprint/unconference of PyAstro16 so I don't really know the scope of the project and its main goals, but defining photometric regions, e.g petrosian region in a single galaxy image, is within such objectives? I could really use something like that in some nonparametric morphology measurements I'm pushing to photutils.

Thank you

Regions describing masks

It will sometimes be useful to represent pixel masks as regions. This should probably be implemented as a mask-to-polygon function with options for accuracy / contour smoothness. The most expensive polygon would have 2-3 points per pixel covering each corner, which is still cheap enough to be useful in some cases.

Add "about" page describing regions and pyregion

As mentioned at astropy/pyregion#48 (comment) , there should be a better description on the scope and status of the regions package and also pyregion.

I would propose small edits to the pyregions docs (adding a brief "About" page, along the lines of what I pointed out in astropy/pyregion#48 (comment)), as well as adding a small, but not super-small "About" page to the regions docs.
There's the sentence "The goal is to merge the functionality from pyregion and photutils apertures and then after some time propose this package for inclusion in the Astropy core." on the top-level page http://astropy-regions.readthedocs.io/en/latest/ that could be moved to that About page, and then About would come before Getting started.
Content would be a brief description of scope and status of the regions package, briefly mentioning the main features.

conda install fails on travis-ci with Python 3.6

@bsipocz - The Python 3.6 builds on travis-ci are failing with a conda install fail:
https://travis-ci.org/astropy/regions/jobs/202159396

UnsatisfiableError: The following specifications were found to be in conflict:
  - astropy
  - numpy 1.12*
  - python 3.6*

This is just a CI issue, so I'll still cut the 0.2 release now.
(just mentioning it so that you don't commit to master, but go through a pull request to fix this CI issue)

Implementing to_mask for composite regions

PR #71 adds to_mask for some of the single regions, but in future we'll need to implement it on Compound regions. This will have varying degrees of difficulty depending on the mode:

• mode='center' - should be easy to implement using boolean operations

• mode='subpixel' and mode='exact' - this is more complex because if you get two mask pixels that have values of 0.5 for example, it's not clear whether that 0.5 fraction is the same for the two regions in a compound region. If the compound region is a union, the final result could be anywhere from 0.5 to 1.0. There are different possible solutions here. One of them would be to simply convert the compound region to a polygon region (which would need to support multiple disjointed polygons) and then use to_mask on the polygon region class.

This issue is meant to be a space for brainstorming about this, so just add a comment if you have other ideas on how to do this properly.

Region serialization formats: STC-S

A region format that exists and that we could implement is the IVOA (I think?) supported STC-S, as described here: http://adsabs.harvard.edu/abs/2010ASPC..434..213B

There was some discussion about putting the STC format into yaml files, which might make the i/o very nice & easy.

Use Pix or Pixel consistently

Currently we have a class PixCoord, and everywhere else the longer form "Pixel" is used, e.g. in PixelRegion.

See http://astropy-regions.readthedocs.io/en/latest/api.html

We should make it consistent now and the question is which way to go?

• "Pix" - short and sweet, same length as the corresponding "Sky", used in many parts of the API in Astropy already (see here).
• "Pixel" - more explicit, used in many parts of the API in Astropy already (see here).

@keflavich @astrofrog @eteq @larrybradley @joleroi - Please leave a comment mentioning your preference.

to_mask method

I think the to_mask method needs to have an input shape parameter to define the shape of the output mask image (which presumably would be the same as the data image):
https://github.com/astropy/regions/blob/master/regions/core/core.py#L135

Or am I missing something?

Feature Request: CASA region reader/writer

See http://stackoverflow.com/questions/43761841/astropy-table-with-source-positions-save-in-casa-region-format

cc @vilhelmp

Split up getting started into multiple pages?

As discussed with @astrofrog in #87 (comment), the http://astropy-regions.readthedocs.io/en/latest/getting_started.html page is getting too long and we should probably split it up.

It's not quite clear how to best do it. At the moment there's ~ 16 sections.
Some are very short, is putting each on a sub-page a good solution?
Or maybe just move some of the longer ones (like masks and plotting) on sub-sections?

One point to keep in mind is that we want this to become astropy.regions, so the docs should be as similar as possible to the existing structure of Astropy core sub-package docs:
http://astropy.readthedocs.io/en/latest/

I'm pretty sure we do need docs sub-pages, because we'll also add things like MOC (healpix-based regions) here (see #62), so astropy.regions will grow in the coming months.

I'm putting this under the 0.2 milestone, and can spend some time on it, but not much.
So comments on what we should do or even help welcome!

ds9 region parsing should handle whitespace

As per astropy/pyregion#73, there are some regions that are valid for ds9 but are not included in the test cases now and are not properly parsed.

Document "meta", "visual" and "vizmeta" for regions

I saw that all regions (e.g. CircleSkyRegion) have meta and visual arguments in __init__ and data members:

    def __init__(self, center, radius, meta=None, visual=None):
        # TODO: test that center is a 0D SkyCoord
        self.center = center
        self.radius = radius
        self.meta = meta or {}
        self.visual = visual or {}

As far as I know these are not documented anywhere (not mentioned as parameters in the docstring), not included in the str representation of the region and not explained here:
http://astropy-regions.readthedocs.io/en/latest/getting_started.html#ds9

I tried this one example ... in this case apparently an extra vizmeta attribute is populated with info from the DS9 file:

>>> from regions import read_ds9
>>> regions = read_ds9('regions/io/tests/data/ds9.color.reg')
>>> regions[0].__dict__
{'center': <FK5 Coordinate (equinox=J2000.000): (ra, dec) in deg
     (202.46947917, 47.19583889)>,
 'meta': {'include': ''},
 'radius': <Quantity 1.0 arcsec>,
 'visual': {},
 'vizmeta': {'color': 'blue'}}

Personally my motivation to work on the DS9 aspect of regions is small, I want to focus on using regions for analysis, i.e. implement polygons etc.

@keflavich or anyone else familiar with regions/io -- could you please write up a page of info and examples that explain how the I/O and these attributes work?
Either extend http://astropy-regions.readthedocs.io/en/latest/getting_started.html#ds9 or better yet, just make a new separate page in the high-level docs.
That could also include a comparison with pyregion, how it represents the info from ds9 files and how regions is similar or different.

Use "Shapely" or "sphere" for Astropy regions?

Should we use Shapely and / or Sphere and / or neither (i.e. re-implement or copy over things like polygon computations) as a dependency for this to-be astropy.regions package?

I don't remember if this important question was discussed in detail or decided at PyAstro16!?

Currently the API has shapely in many places, but nothing is really implemented and @astrofrog, I think it might just be the left-over of some API brainstorming a year or two ago?
https://github.com/astropy/regions/search?utf8=%E2%9C%93&q=shapely

@eteq @astrofrog @keflavich @larrybradley, all - thoughts?

Pull regions code from photutils, Ginga or LSST?

At ADASS 2016 @ejeschke and I had a chat about regions and I wanted to leave some notes here.

There's a pretty complete set of regions implemented in Ginga (list). They have a contains_arr method with containment implemented using Numpy array expressions. See polygon as example.

Ginga only has pixel regions, no sky regions, and the regions code there contains GUI stuff. @ejeschke might be interested in re-using astropy.regions from Ginga, if it's done in an extensible way so that the Ginga GUI code can be added e.g. by holding astropy.region data members or by subclassing. Also @ejeschke isn't a fan of the double class hierarchy we have in regions and photutils where the data members are complex and non-uniform objects like SkyCoord or Angle. I think in Ginga he has something more uniform where every region can be expressed as a list of points. Maybe it's similar to how pyregion.Shape represents regions? @ejeschke, could you elaborate on this point and how the double class hierarchy could be avoided and then we'll try to do a pro-con of the options?

There's also photutils.aperture where so far the plan was to pull the code for ellipse, rectangle from into this regions package and then in the far future photutils would switch to astropy.regions. photutils is Cython-backed code and has sub-pixel stuff, which Ginga doesn't have. Do we want sub-pixel contains fractions in astropy.regions? It's extra work to develop / test for all regions.

@timj has written up (in Section 4.2) some info about he LSST regions code and thoughts on how it could be added or interfaced to astropy.regions here: https://www.lsst.org/scientists/publications/investigating-interoperability-lsst-data-management-software-stack-astropy

Personally I'm inclined to start by pulling the pixel polygon code from Ginga, because that's what we need for data analysis in Gammapy. But if we find "the right way" forward, I'll spend dev time to help implement whatever solution we decide to go with.

@astropy/regions-developers - Thoughts on what we should do? Anyone have time to work on this in the coming months?

Update astropy-helpers to get rid of test fail?

I'm getting this test fail

____________________________________________ test_plot ____________________________________________
E       astropy.utils.exceptions.AstropyDeprecationWarning: astropy.utils.compat.odict.OrderedDict is now deprecated - import OrderedDict from the collections module instead

because of a deprecation warning from a dependency package.

Full log: https://gist.github.com/cdeil/25d2b653a36b6d9216fe222253bfe036#file-gistfile1-txt-L59

@bsipocz @astrofrog - I think this has been fixed in astropy-helpers?
Can we update the astropy/regions package to the latest ah version?
Should I do it now?

Defining regions without centers

It would be nice to be able to define regions without specifying the center positions (or have a default center of e.g. (0,0)). This issue came up when trying to define an object-oriented interface for local background subtraction for photutils PSF fitting, where the positions of the stars would be determined in a downstream function, e.g.:

from photutils import MMMBackground, CircularAnnulus, psf_photometry
aper = CircularAnnulus(r_in=15, r_out=30)       # position of stars to be determined later
bkg = MMMBackground( sigma=3.)
psf_phot_table = psf_photometry(data, ...., background_sub=bkg, background_aperture=aper)

Inside the psf_photometry function, the apertures positions could then be defined by setting the object center attribute.

SkyCircleRegion matplotlib plot issue

In #74 @joleroi added docs/plot_compound.py which generates this plot:
http://astropy-regions.readthedocs.io/en/latest//plot_compound.png

As discussed in #74, there is an issue, the region is not drawn correctly.
To @joleroi and me the script looks OK, so we don't know what's wrong.

@astrofrog or @larrybradley or anyone - if you could have a look, that would be great!

Adapt travis-ci build matrix

The travis-ci builds for this repo are currently broken since I merged #42 yesterday:
https://travis-ci.org/astropy/regions?branch=master

The reason is that we have Astropy 1.0 LTS tests in the build matrix.
Those builds should be removed.
The plan with this code is that it's added to astropy master and becomes part of Astropy core 1.3.
So IMO there's no point in testing and supporting old Astropy versions.

@bsipocz - Do you have time to adapt the build matrix or should I?
(What's the best way ... delete lines or comment them out in .travis.yml?)

test arraydiff error

@astrofrog - I updated to regions master just now and got this error:

$ python setup.py test -V
/opt/local/Library/Frameworks/Python.framework/Versions/3.5/lib/python3.5/site-packages/Cython/Distutils/old_build_ext.py:30: UserWarning: Cython.Distutils.old_build_ext does not properly handle dependencies and is deprecated.
  "Cython.Distutils.old_build_ext does not properly handle dependencies "
running test
running build
running build_py
copying regions/_compiler.c -> build/lib.macosx-10.12-x86_64-3.5/regions
copying regions/_geometry/circular_overlap.c -> build/lib.macosx-10.12-x86_64-3.5/regions/_geometry
copying regions/_geometry/core.c -> build/lib.macosx-10.12-x86_64-3.5/regions/_geometry
copying regions/_geometry/elliptical_overlap.c -> build/lib.macosx-10.12-x86_64-3.5/regions/_geometry
copying regions/_geometry/rectangular_overlap.c -> build/lib.macosx-10.12-x86_64-3.5/regions/_geometry
running build_ext
skipping 'regions/_geometry/circular_overlap.c' Cython extension (up-to-date)
skipping 'regions/_geometry/core.c' Cython extension (up-to-date)
skipping 'regions/_geometry/elliptical_overlap.c' Cython extension (up-to-date)
skipping 'regions/_geometry/rectangular_overlap.c' Cython extension (up-to-date)
usage: -c [options] [file_or_dir] [file_or_dir] [...]
-c: error: unrecognized arguments: --arraydiff
  inifile: /private/var/folders/sb/4qv5j4m90pz1rw7m70rj1b1r0000gn/T/regions-test-c0nb7we5/setup.cfg
  rootdir: /private/var/folders/sb/4qv5j4m90pz1rw7m70rj1b1r0000gn/T/regions-test-c0nb7we5

Eventually I did remember that --arraydiff is https://github.com/astrofrog/pytest-arraydiff that you added in #71, so I'll install that now.

My question is if you can make the error message better?

Instead of

-c: error: unrecognized arguments: --arraydiff

actually printing something like this would be good:

https://github.com/astrofrog/pytest-arraydiff not found.
Please `pip install pytest-arraydiff`

Also maybe mention and link to https://github.com/astrofrog/pytest-arraydiff here?
http://astropy-regions.readthedocs.io/en/latest/installation.html#optional-dependencies

PyPI releases!

At PyAstro16 we discussed that this astropy/regions package should be developed quickly in this repo at https://github.com/astropy/regions/ and then be merged in the Astropy core repo.

There hasn't been much development on astropy/regions after PyAstro16 though, there isn't much functionality, tests, docs yet ... it's not clear if it's feasible to get this done and stable before for Astropy 1.3.

I'd like to propose that we start doing releases on PyPI and announce them on astropy-dev, starting with 0.1 very soon (in a week or two).

A personal motivation for that is that I don't like having to update the bundled version of this package at gammapy.extern.regions because we have started using it for circles and need it to be available to end users. The main reason is that I think releases on PyPI and announcements on astropy-dev might attract some co-developers to this package and having had users means that the API and implementation is likely more robust when the time comes to move this to Astropy core.

I'd be happy to make the releases, and if someone else (@joleroi, @keflavich) wants to, even better!

Concerning package name, I propose plain regions (which amazing wasn't taken, so I reserved it right now: https://pypi.python.org/pypi/regions ) This is nice because it's the same as the current repo and package name, i.e. no confusion by users or developers.

I did consider astropy-regions as package name. That's more explicit, but also longer and then some people get confused if PyPI package and installed package names are different.

@keflavich @astrofrog @joleroi @eteq @larrybradley - Thoughts?

Dropping old numpy versions

Astropy v2.0 is going to drop support for numpy 1.7 and 1.8, so I propose to drop support for them here, too. I'll convert this to a PR if you agree with this.

Implement support for polygons with holes

(like shapely does)

Implement support for multi-polygons

Like spherical_geometry and shapely do

Correctness and speed comparison to pyregion

As mentioned by @keflavich in #9, it would be nice to as some point have a

• correctness comparion with pyregion
• speed comparison with pyregion

to make sure this regions package is a full replacement.

Put docs on readthedocs

To include in the frontpage:

• a timeline for inclusion in astropy core (>=3 months, but the goal is to have it in core)
• correctness comparison to pyregion
• speed comparison to pyregion

Pixel Representations

I'm looking at porting my ply-based parsing from https://github.com/sargas/pyregion/blob/regions-submodule/pyregion/regions/_ply_helper.py , which I think is more flexible (would fix #65 , for instance, and I have many tests)

One issue I notice is that regions can be defined in various frames - FK5, galactic, etc - but pixel regions lose all information of how they are defined. If I write in a DS9 file:

circle 50 50 5

This is referring to some coordinate system defined by a FITS file header (names of these include image, physical, detector, pane, gap, amplifier, ccd, primary, etc). Do subclasses of PixelRegion include this information?

If not, it seems like someone could easily get confused trying to display a region defined by a FITS file with non-trivial LTM/LTV values and getting the region at a different place then in CIAO or DS9.

Have a registry of regions?

Would it be helpful to keep track of all region classes? We can do that with a simple meta-class (I could add it)

Simplify region base classes

In December 2016 @joleroi @astrofrog and I had a Google hangout where we discussed astropy.regions, the minutes are here:
https://docs.google.com/document/d/1u-WjsP4wLWx4g1-om7imstjngOmwpAJQ8EyVZxvhxV4/edit#heading=h.wf1hdss3eefb

I dropped the ball on implementing the changes discussed there, but I'd like to come back to that now. Actually, if this is non-controversial, I'd like to make the changes this week, before the regions 0.2 release, because it's not a lot of work, just removing a bunch of stuff instead of leaving dummy methods that return NotImplementedError at the moment.

Before going ahead, I'd like to ask @astrofrog and @joleroi again, and also @keflavich and @larrybradley for input!

---

Basically we said that area and contains should be removed from the base sky region class:
http://astropy-regions.readthedocs.io/en/latest/api/regions.SkyRegion.html

The reason is that area and contains aren't well-defined concepts for all sky regions.
We argued about this for quite a while, but in the end I think there was agreement that it's not well-defined and thus doesn't belong in the base class.
E.g. how exactly would you implement area and contains for
http://astropy-regions.readthedocs.io/en/latest/api/regions.RectangleSkyRegion.html
so that it's valid for very large rectangles (say width = 100 deg)?

So we'd like to propose basically that we adopt the DS9 model of having regions mainly defined as pixel regions, and having sky regions mostly as convenience, but not with separate definitions of contains methods. Instead contains would be implemented in the following generic way on the base class for sky regions, and only be well-defined if the user has a WCS:

class SkyRegion(object):
    def contains(self, sky_coord, wcs):
         Reg = self.to_pixel(wcs)
         Pix_coord = foo(sky_coord)
         Return reg.contains(pix_coord)

In the future, we would add the special cases (circle & polygon) back where contains is well-defined in sky coordinates, either as separate classes or on the existing classes.

This brings us to the other major change we'd like to propose, which is to get rid of the different modes in the pixel to sky transformation:

• http://astropy-regions.readthedocs.io/en/latest/api/regions.SkyRegion.html#regions.SkyRegion.to_pixel
• http://astropy-regions.readthedocs.io/en/latest/api/regions.PixelRegion.html#regions.PixelRegion.to_sky

This was never implemented, it was just an idea, there will be no functionality lost.

So for now, we'd remove the modes from the base class, only leaving the "mode" how DS9 transforms back and forth, and we'd remove all the checks and NotImplementedError from the derived classes.

---

Note that regions will remain experimental, and based on user and dev feedback, we can always do it differently in the end. So basically -- if there's agreement on this I would make the change tomorrow, before the 0.2 release. And if it's controversial, I would just make the release as-is, and we take our time to discuss here.

Implement to_shapely and from_shapely for pixel regions

This will then make it easy to do unions/intersections/symmetric differences

Multi-order coverage MOC HEALPIX

It would be nice to have Multi-order coverage (MOC) in this astropy.regions package (which is supposed to go in the Astropy core package in a few month).

http://ivoa.net/documents/MOC/ describes it like this:

This document describes the Multi-Order Coverage map method (MOC) to specify arbitrary sky regions. The goal is to be able to provide a very fast comparison mechanism between coverage maps. The mechanism is based on the HEALPix sky tessellation algorithm. It is essentially a simple way to map regions of the sky into hierarchically grouped predefined cells.

There's two Python package for MOC:

1. pymoc by @grahambell - Github, Readthedocs, PyPI
2. mocpy by @tboch - Github, example notebooks, PyPI

@grahambell @tboch - Are there big differences in design or philosophy between the two Python packages? Or does collaboration / merging of efforts seem possible? Are you interested to collaborate in that direction?

If there is interest in making this happen, one issue to watch out for is license. Both pymoc and mocpy are currently implemented using healpy, which uses HEALPIX and is GPL licensed, not compatible with the BSD license Astropy core and most other packages use.
There is talk of having a subset of HEALPIX re-implemented in BSD and use that, starting with the BSD-licensed HEALPIX code e.g. here or here and here.
I think having such basic HEALPIX functionality in Astropy core and using it for MOC and other applications would be nice.

• @astropy/regions-developers - Agreed that MOC would be in scope and nice to have for astropy.regions
• @grahambell @tboch - Do you support this? Or would you prefer your Python MOC packages stay as-is (not integrated in Astropy, GPL licensed)?
• Anyone besides me have time / interest to work in this in the coming weeks or months?

regions version 0.2

This is an overview issue to have a place to discuss about scope, timescale, tasks for the regions version 0.2 release.

Here's the list of issues and pull requests with the 0.2 milestone:
https://github.com/astropy/regions/milestone/4

Of course this is up for debate, any pull request that's ready can go in, and we might put some tasks off to 0.3 if no-one has time to implement them.

Is source in FoV

Hello,

I'm working on the SVOM mission and I'm really interested in the astropy/region package.

We have a squared fov (89*89deg) centered on a known (ra_0,dec_0) position and I would like to determine if a source located at (ra_s, de_s) would be present in the fov. We also know the roll angle.

I've seen that method contains.RectangleSkyRegion is not yet implemented. Do you have an idea to achieve that ? I think that it as to deal with spherical trigonometry.

Thanks for your help,
Cheers,

Nicolas

Polygon region vertices

The PolygonPixelRegion is initialized with a vertices input, which it appears are absolute positions. That makes it a bit more difficult to move the region to different positions. Instead, should the vertices define a shape relative to (0, 0) and then have an additional position (or center?) parameter that defines the absolute position (i.e. a shift from (0, 0))?

Improve ellipse regions

I'd like to propose a few changes to the ellipse regions, EllipsePixelRegion and EllipseSkyRegion, that I don't have time for now to implement in #85.

• Rename parameter major -> a and minor -> b. These are the names that were previously chosen for astropy.modeling.functional_models.Ellipse2D and photutils.aperture.EllipticalAperture.
• The ellipse mask test in regions/shapes/tests/test_masks.py currently uses EllipsePixelRegion(PixCoord(3.981987, 4.131378), major=2.2233, minor=3.3411, angle=32 * u.deg), i.e. minor > major, probably due to a misunderstanding in the argument order. I suggest we change this test to use a > b and update the reference results files, even if a and b are no longer called major and minor.
• The description of a and b should not claim they are the major and minor axis. That's a can of worms, because sometimes a > b and b < a, we don't have any control over that in the code. This should also be fixed in the astropy.modeling.functional_models.Ellipse2D docstring, I think there's already an issue with no action discussing that. We can expose extra attributes major and minor if people want, or a method that returns a new shape where always a>b if people think that's useful.

Just overall, I think it's important that we finish the photutils aperture -> astropy regions code transition soon and systematically and someone spend a week to do that. We're wasting time looking at the same issues that have already been discussed, sorted out and are coded up and tested in photutils. (I'm not saying we have to do everything the same, this is a chance to fix inconsistencies and mistakes we made in photutils if any.)

Putting this on the 0.3 milestone. Help wanted!

regions version 0.3

I think we should make a regions 0.3 release next week.
We can use this issue to discuss.

There is a 0.3 and 0.4 milestone, so anyone feel free to add or move issues / PRs to those:
https://github.com/astropy/regions/milestones

There already are some new features and fixes since the 0.2 release, and more are coming this week. A release is not much work and in my experience helps to focus the work and make sure discussions conclude, issues get closed and PRs finished and merged.

I would prefer if someone else does it! @joleroi @keflavich ?
If no, I could do it Thursday, May 18. Let me know.
In any case, I can spend a few hours to work on regions early next week.

If some has plans to work a lot on regions in the coming weeks, we can also postpone for a few weeks. (But why do 0.3 next week and 0.4 in a month or two?)

Remove wcsaxes as a dependency

It looks like that all the imports of wcsaxes have been removed, so we may want to remove it from the dependency lists and CI configs, too.

Write a regions notebook in astropy-tutorials

As suggested by @astrofrog and me at #87 (comment), we should write a "getting started" notebook for regions, and put it in astropy-tutorials.

I think a 5 to 10 min read would be appropriate, and start and end by pointing at the longer Sphinx docs.

I'm putting this under the 0.2 milestone, but this can happen after the release. It should happen before the 0.2 announcement to astropy-dev though, so that this can be mentioned.

Anyone interested to do this?

If no, I'll write it on Monday latest.

Remove 'all' and 'any' models from to_mask API?

The 'all' and 'any' modes are maybe not needed - one can just use 'exact' and check the result compared to 0 and 1. In fact, this is hard to implement internally because for 'all', the exact mode can sometimes give results are are extremely close but not exactly 1 - so then we have to introduce a tolerance, which gets messy. I'd actually vote to remove these modes and just keep 'center', 'subpixels', and 'exact'. What do others think?

Sphinx API warning / error

After merging #32 the Sphinx build on travis-ci now fails ... I think because of this warning:

/home/travis/build/astropy/regions/docs/api.rst:12: WARNING: toctree references unknown document u'api/regions.pixel_to_skycoord'

Full log: https://travis-ci.org/astropy/regions/jobs/139781170#L701

I'm not sure why that's happening or how to fix it.
@larrybradley @bsipocz - Help!?

Remove PixCoord.isscalar?

@astrofrog @larrybradley @keflavich - Should we remove PixCoord.isscalar?

It's currently implemented as np.isscalar(self.x):
https://github.com/astropy/regions/pull/106/files#diff-23129064d4c4f77992faa0ddb1fcabe8R91

I just noticed that this doesn't really do what I expected:
https://github.com/astropy/regions/pull/106/files#diff-6d4df9d4594341f07b19601a398cde45R104

Someone else (I think) also used it incorrectly here:
https://github.com/astropy/regions/pull/106/files#diff-23129064d4c4f77992faa0ddb1fcabe8R147

Basically what we sometimes want is to check if pixcoord represents a single point or multiple points, but because np.isscalar(np.array(42)) == False this doesn't represent that question, and e.g. when we run pixcoord = skycoord.to_pix(wcs) we get pixcoord objects that have 0-dim numpy arrays (like what you get from np.array(42).

So I could try to remove pixcoord.isscalar and all callers (and if needed tests) and post a commit here for review. Or do we want / need it and there's some way to make the current situation better?

(my time is very limited this week, if someone else can make a PR for this, it would be much appreciated)

Attribute validation for astropy.regions?

In #81 (comment) and other places in astropy.regions before the question came up whether we should do input validation (for PixCoord, BoundingBox, region classes with float or Angle or SkyCoord attributes, ....

I'm +1 to do it. It's some extra effort for us, but especially for interactive work it really helps users catch many little mistakes.

My preference would be to use something like attrs or numtraits instead of re-implementing something similar again here in astropy.regions.

@astrofrog @larrybradley or anyone - Thoughts?

Is there something available or proposed in Astropy core?
Should we bundle or add dependency here?
Should we discuss on the Astropy mailing list or issue tracker now, or just go ahead and start using something here and discuss later / hope they accept it in Astropy core?

Add CI test for sdist and coda package

I've been bitten a few times last year with making releases and only after noticing little mistakes.

So starting here with regions and then Gammapy, I would like to take the time this week and add CI builds that generate sdist and conda packages, and install and test those, before making the upcoming releases.

@bsipocz @astrofrog - How would you recommend to add this? As a lengthly multi-line string in the .travis.yml, or a bash script somewhere that I execute from .travis.yml or a Makefile?

In any case, I guess I should use the existing setup and use a MAIN_CMD and empty SETUP_CMD like here?

env: MAIN_CMD='pycodestyle regions --count' SETUP_CMD=''

https://github.com/astropy/regions/blob/master/.travis.yml#L92

Build fails in master due to coordinate repr changes

The astropy/regions tests on travis-ci in master are failing for the two builds using Astropy dev:

https://travis-ci.org/astropy/regions/jobs/175035799#L743
https://travis-ci.org/astropy/regions/jobs/175035801#L745

Those are doctest changed because apparently the repr changed for SkyCoord. Example:

_______________________________ test_circle_sky ________________________________
    def test_circle_sky():
        center = SkyCoord(3 * u.deg, 4 * u.deg)
        reg = CircleSkyRegion(center, 2 * u.arcsec)
    
>       assert str(reg) == 'CircleSkyRegion\ncenter: <SkyCoord (ICRS): (ra, dec) in deg\n    (3.0, 4.0)>\nradius: 2.0 arcsec'
E       assert 'CircleSkyReg...s: 2.0 arcsec' == 'CircleSkyRegi...s: 2.0 arcsec'
E         Skipping 54 identical leading characters in diff, use -v to show
E            deg
E         -     ( 3.,  4.)>
E         ?      -   -
E         +     (3.0, 4.0)>
E         ?        +    +
E           radius: 2.0 arcsec

This is annoying because it makes the tests fail for all open PRs.

@bsipocz @astrofrog or anyone: suggestion how to modify (or remove?) the tests to fix this?
(I might have time to fix this on the weekend or Monday if it's clear what to do, but not today.)

How to convert between pixel & sky?

What approach will be the default for converting between pixel and sky? Probably all of these should be implemented, but one should be the default:

• convert all regions to polygons, convert sky coordinates to pixel and vice versa
• keep circles, rectangles, etc. "fixed", convert by assuming the projection is perfectly flat

Contained in option 1 is a question about how accurately we need to discretize continuous shapes when converting to polygons.

Also, which regions will get "abstract" representations allowing them to be rotated and manipulated with simple parameters? e.g., ellipse, rectangle have major/minor axes and angles that are their minimal representations, but these are not preserved through projection.