Astropy Documentation - Read the Docs · 5.3 Reference/API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22 6 Units and Quantities

Astropy DocumentationRelease 1.0.3

The Astropy Developers

June 26, 2015

Contents

I User Documentation 3

1 Whats New in Astropy 1.0? 51.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.2 About Long-term support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.3 Support for Alt/Az coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.4 New Galactocentric coordinate frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.5 New data visualization subpackage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.6 New analytic functions subpackage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.7 New ASCII features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.8 New modeling features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.9 New Table features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.10 Integration with WCSAxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101.11 Deprecation and backward-incompatible changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101.12 Full change log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2 Overview 112.1 Astropy Project Concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.2 astropy Core Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.3 Affiliated Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.4 Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3 Installation 133.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.2 Installing Astropy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.3 Building from source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4 Getting Started with Astropy 194.1 Importing Astropy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194.2 Getting started with subpackages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204.3 Command-line utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

5 Constants (astropy.constants) 215.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215.2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215.3 Reference/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

6 Units and Quantities (astropy.units) 276.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276.2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

i

6.3 Using astropy.units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296.4 See Also . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476.5 Reference/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486.6 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

7 N-dimensional datasets (astropy.nddata) 1117.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1117.2 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1117.3 Transition to astropy 1.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1137.4 Using nddata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1137.5 Reference/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

8 Data Tables (astropy.table) 1378.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1378.2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1378.3 Using table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1418.4 Reference/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

9 Time and Dates (astropy.time) 2239.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2239.2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2239.3 Using astropy.time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2249.4 Reference/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2359.5 Acknowledgments and Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

10 Astronomical Coordinate Systems (astropy.coordinates) 25710.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25710.2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25710.3 Overview of astropy.coordinates concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26010.4 Using astropy.coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26010.5 Migrating from pre-v0.4 coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29610.6 See Also . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29710.7 Reference/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

11 World Coordinate System (astropy.wcs) 36511.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36511.2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36511.3 Using astropy.wcs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36611.4 Supported projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36811.5 Subsetting and Pixel Scales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36911.6 Matplotlib plots with correct WCS projection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36911.7 Other information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37011.8 See Also . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37611.9 Reference/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37611.10 Acknowledgments and Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433

12 Models and Fitting (astropy.modeling) 43512.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43512.2 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43512.3 Using astropy.modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44112.4 Reference/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

13 Analytic Functions (astropy.analytic_functions) 58513.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58513.2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585

ii

13.3 Using astropy.analytic_functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58513.4 See Also . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58613.5 Reference/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587

14 Unified file read/write interface 58914.1 Getting started with Table I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58914.2 Built-in table readers/writers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589

15 FITS File handling (astropy.io.fits) 59515.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59515.2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59515.3 Using astropy.io.fits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60415.4 Other Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63415.5 Reference/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696

16 ASCII Tables (astropy.io.ascii) 78716.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78716.2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78716.3 Supported formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79016.4 Using astropy.io.ascii . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79016.5 Reference/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 810

17 VOTable XML handling (astropy.io.votable) 84917.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84917.2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84917.3 Using astropy.io.votable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85117.4 See Also . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85417.5 Reference/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854

18 Miscellaneous Input/Output (astropy.io.misc) 89518.1 astropy.io.misc Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89518.2 astropy.io.misc.hdf5 Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 896

19 Convolution and filtering (astropy.convolution) 89919.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89919.2 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89919.3 Using astropy.convolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90119.4 Reference/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 908

20 Data Visualization (astropy.visualization) 93920.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93920.2 Using astropy.visualization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93920.3 Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94220.4 Reference/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 942

21 Cosmological Calculations (astropy.cosmology) 96121.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96121.2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96121.3 Using astropy.cosmology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96221.4 For Developers: Using astropy.cosmology inside Astropy . . . . . . . . . . . . . . . . . . . . . . 96621.5 See Also . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96621.6 Range of validity and reliability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96621.7 Reference/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 967

22 Astrostatistics Tools (astropy.stats) 999

iii

22.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99922.2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99922.3 See Also . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99922.4 Reference/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999

23 Virtual Observatory Access (astropy.vo) 101323.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1013

24 Configuration system (astropy.config) 109124.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109124.2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109124.3 Using astropy.config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109224.4 Adding new configuration items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109324.5 See Also . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109624.6 Reference/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1099

25 I/O Registry (astropy.io.registry) 110925.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110925.2 Using astropy.io.registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110925.3 Reference/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1110

26 Logging system 111526.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111526.2 Configuring the logging system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111526.3 Context managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111626.4 Using the configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111626.5 Reference/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1117

27 Python warnings system 1121

28 Astropy Core Package Utilities (astropy.utils) 112328.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112328.2 Reference/API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1123

29 Current status of sub-packages 1167

30 Major Release History 116930.1 Whats New in Astropy 1.0? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116930.2 Whats New in Astropy 0.4? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117430.3 Whats New in Astropy 0.3? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117730.4 Whats New in Astropy 0.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117730.5 Whats New in Astropy 0.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1177

31 Known Issues 117931.1 Known deficiencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117931.2 Build/installation/test issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1182

32 Authors and Credits 118532.1 Astropy Project Coordinators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118532.2 Core Package Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118532.3 Other Credits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1189

33 Licenses 119133.1 Astropy License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119133.2 Other Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1191

iv

II Getting help 1193

III Reporting Issues 1197

34 For astropy-helpers 1201

IV Contributing 1203

35 Try the development version 120735.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120735.2 Step-by-step instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1208

36 How to make a code contribution 121336.1 Pre-requisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121336.2 Strongly Recommended, but not required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121336.3 New to git? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121336.4 Astropy Guidelines for git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121536.5 Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121536.6 Fetch the latest Astropy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121636.7 Make a new feature branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121636.8 Install your branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121636.9 The editing workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121736.10 Add a changelog entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121836.11 Copy your changes to GitHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121836.12 Ask for your changes to be reviewed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121836.13 Revise and push as necessary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121936.14 Rebase, but only if asked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1219

V Developer Documentation 1221

37 How to make a code contribution 122537.1 Pre-requisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122537.2 Strongly Recommended, but not required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122537.3 New to git? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122537.4 Astropy Guidelines for git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122737.5 Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122737.6 Fetch the latest Astropy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122837.7 Make a new feature branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122837.8 Install your branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122837.9 The editing workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122937.10 Add a changelog entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123037.11 Copy your changes to GitHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123037.12 Ask for your changes to be reviewed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123037.13 Revise and push as necessary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123137.14 Rebase, but only if asked . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1231

38 Coding Guidelines 123338.1 Interface and Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123338.2 Documentation and Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123438.3 Data and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123438.4 Standard output, warnings, and errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123438.5 Coding Style/Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1235

v

38.6 Unicode guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123638.7 Including C Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123738.8 Writing portable code for Python 2 and 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123738.9 Compatibility between versions of Numpy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124038.10 Requirements Specific to Affiliated Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124038.11 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124038.12 Additional Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1244

39 Writing Documentation 124739.1 Building the Documentation from source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124739.2 Astropy Documentation Rules and Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124739.3 Sphinx Documentation Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125539.4 Sphinx extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1255

40 Testing Guidelines 125940.1 Testing Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125940.2 Running Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125940.3 Writing tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126240.4 Writing doctests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1269

41 Writing Command-Line Scripts 127341.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1273

42 Building Astropy and its Subpackages 127542.1 Astropy-helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127542.2 Customizing setup/build for subpackages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1275

43 C or Cython Extensions 127743.1 Installing C header files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127743.2 Preventing importing at build time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1277

44 Release Procedures 127944.1 Release Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127944.2 Maintaining Bug Fix Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128244.3 Creating a GPG Signing Key and a Signed Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128544.4 Creating a MacOS X Installer on a DMG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1286

45 Workflow for Maintainers 128945.1 Integrating changes via the web interface (recommended) . . . . . . . . . . . . . . . . . . . . . . . 128945.2 Integrating changes manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128945.3 Using Milestones and Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129045.4 Updating and Maintaining the Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1291

46 How to create and maintain an Astropy affiliated package 129346.1 Managing the template files manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129346.2 Managing the template files via git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129646.3 Releasing an affiliated package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1299

47 Full Changelog 130147.1 1.0.3 (2015-06-05) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130147.2 0.4.6 (2015-05-29) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130247.3 1.0.2 (2015-04-16) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130247.4 1.0.1 (2015-03-06) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130447.5 1.0 (2015-02-18) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130547.6 0.4.4 (2015-01-21) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1313

vi

47.7 0.4.3 (2015-01-15) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131447.8 0.4.2 (2014-09-23) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131547.9 0.4.1 (2014-08-08) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131747.10 0.4 (2014-07-16) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131847.11 0.3.2 (2014-05-13) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132747.12 0.3.1 (2014-03-04) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132947.13 0.3 (2013-11-20) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133247.14 0.2.5 (2013-10-25) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134247.15 0.2.4 (2013-07-24) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134447.16 0.2.3 (2013-05-30) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134547.17 0.2.2 (2013-05-21) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134647.18 0.2.1 (2013-04-03) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134847.19 0.2 (2013-02-19) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135047.20 0.1 (2012-06-19) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1354

VI Indices and Tables 1355

Bibliography 1359

Python Module Index 1361

vii

Astropy Documentation, Release 1.0.3

Welcome to the Astropy documentation! Astropy is a community-driven package intended to contain much of the corefunctionality and some common tools needed for performing astronomy and astrophysics with Python.

Contents 1


2 Contents

Part I

User Documentation

3

CHAPTER 1

Whats New in Astropy 1.0?

1.1 Overview

Astropy 1.0 is a major release that adds significant new functionality since the 0.4.x series of releases.

In particular, coordinate conversions to/from Altitude/Azimuth are now supported (see Support for Alt/Az coordinates),a new package to help with data visualization has been added (see New data visualization subpackage), and a newpackage for common analytic functions is now also included (see New analytic functions subpackage).

The ASCII Tables (astropy.io.ascii) sub-package now includes fast C-based readers/writers for common formats, andalso supports a new ASCII format that better preserves meta-data (see New ASCII features), the modeling package hasbeen significantly improved and now supports composite models (see New modeling features), and the Table classcan now include SkyCoord and Time objects containing arrays (see New Table features).

In addition to these major changes, Astropy 1.0 includes a large number of smaller improvements and bug fixes, whichare described in the Full Changelog. By the numbers:

681 issues have been closed since v0.4

419 pull requests have been merged since v0.4

122 distinct people have contributed code

1.2 About Long-term support

Astropy v1.0 is a long-term support (LTS) release. This means v1.0 will be supported with bug fixes for 2 years fromits release, rather than 6 months like the non-LTS releases. More details about this, including a wider rationale forAstropys version numbering scheme, can be found in Astropy Proposal for Enhancement 2.

Note that different sub-packages in Astropy have different stability levels. See the Current status of sub-packages pagefor an overview of the status of major components. LTS can be expected for anything with green or blue (stable ormature) status on that page. For yellow (in development) subpackages, LTS may be provided, but major changes mayprevent backporting of complex changes, particularly if they are connected to new features.

1.3 Support for Alt/Az coordinates

The coordinates package now supports conversion to/from AltAz coordinates. This means coordinates can nowbe used for planning observations. For example:

5

https://github.com/astropy/astropy-APEs/blob/master/APE2.rst


>>> from astropy import units as u>>> from astropy.time import Time>>> from astropy.coordinates import SkyCoord, EarthLocation, AltAz>>> greenwich = EarthLocation(lat=51.477*u.deg,lon=0*u.deg)>>> albireo = SkyCoord('19h30m43.2805s +27d57m34.8483s')>>> altaz = albireo.transform_to(AltAz(location=greenwich, obstime=Time('2014-6-21 0:00')))>>> print altaz.alt, altaz.az60d32m28.4576s 133d45m36.4967s

For a more detailed outline of this new functionality, see the Example: Observation Planning and the AltAz docu-mentation.

To enable this functionality, coordinates now also contains the full IAU-sanctioned coordinate transformation stackfrom ICRS to AltAz. To view the full set of coordinate frames now available, see the coordinates Reference/API.

1.4 New Galactocentric coordinate frame

Added a new, customizable Galactocentric coordinate frame. The other coordinate frames (e.g., ICRS, Galactic)are all Heliocentric (or barycentric). The center of this new coordinate frame is at the center of the Galaxy, withcustomizable parameters allowing the user to specify the distance to the Galactic center (galcen_distance), theICRS position of the Galactic center (galcen_ra, galcen_dec), the height of the Sun above the Galactic midplane(z_sun), and a final roll angle that allows for specifying the orientation of the z axis (roll):

>>> from astropy import units as u>>> from astropy.coordinates import SkyCoord, Galactocentric>>> c = SkyCoord(ra=152.718 * u.degree,... dec=-11.214 * u.degree,... distance=21.5 * u.kpc)>>> c.transform_to(Galactocentric)

>>> c.transform_to(Galactocentric(galcen_distance=8*u.kpc, z_sun=15*u.pc))

1.5 New data visualization subpackage

The new Data Visualization package is intended to collect functionality that can be helpful when visualizing data.At the moment, the main functionality is image normalizing (including both scaling and stretching) but this will beexpanded in future. Included in the image normalization functionality is the ability to compute interval limits on data,(such as percentile limits), stretching with non-linear functions (such as square root or arcsinh functions), and theability to use custom stretches in Matplotlib that are correctly reflected in the colorbar:

import numpy as npimport matplotlib.pyplot as plt

from astropy.visualization import SqrtStretchfrom astropy.visualization.mpl_normalize import ImageNormalize

# Generate test imageimage = np.arange(65536).reshape((256, 256))

# Create normalizer object

6 Chapter 1. Whats New in Astropy 1.0?

http://www.matplotlib.org


norm = ImageNormalize(vmin=0., vmax=65536, stretch=SqrtStretch())

fig = plt.figure(figsize=(6,3))ax = fig.add_subplot(1,1,1)im = ax.imshow(image, norm=norm, origin='lower', aspect='auto')fig.colorbar(im)

0 50 100 150 200 2500

50

100

150

200

250

0

8000

16000240003200040000480005600064000

1.6 New analytic functions subpackage

This subpackage provides analytic functions that are commonly used in astronomy. These already understandQuantity, i.e., they can handle units of input and output parameters. For instance, to calculate the blackbody fluxfor 10000K at 6000 Angstrom:

>>> from astropy import units as u>>> from astropy.analytic_functions import blackbody_lambda, blackbody_nu>>> blackbody_lambda(6000 * u.AA, 10000 * u.K)

>>> blackbody_nu(6000 * u.AA, 10000 * u.K)


By default, read() and write() will attempt to use the fast C engine when dealing with compatible formats. Certainfeatures of the full read / write interface are not available in the fast version, in which case the pure-Python versionwill automatically be used.

For full details including extensive performance testing, see Fast ASCII I/O.

1.7.2 Enhanced CSV format

One of the problems when storing a table in an ASCII format is preserving table meta-data such as comments, key-words and column data types, units, and descriptions. Using the newly defined Enhanced Character Separated Valuesformat it is now possible to write a table to an ASCII-format file and read it back with no loss of information. TheECSV format has been designed to be both human-readable and compatible with most simple CSV readers.

In the example below we show writing a table that has float32 and bool types. This illustrates the simple look of theformat which has a few header lines (starting with #) in YAML format and then the data values in CSV format.

>>> t = Table()>>> t['x'] = Column([1.0, 2.0], unit='m', dtype='float32')>>> t['y'] = Column([False, True], dtype='bool')

>>> from astropy.extern.six.moves import StringIO>>> fh = StringIO()>>> t.write(fh, format='ascii.ecsv')>>> table_string = fh.getvalue()>>> print(table_string)# %ECSV 0.9# ---# columns:# - {name: x, unit: m, type: float32}# - {name: y, type: bool}x y1.0 False2.0 True

Without the header this table would get read back with different types (float64 and string respectively) and no unitvalues. Instead with the automatically-detected ECSV we get:

>>> Table.read(table_string, format='ascii')

x ym

float32 bool------- -----

1.0 False2.0 True

Note that using the ECSV reader requires the PyYAML package to be installed.

1.8 New modeling features

New subclasses of Model are now a bit easier to define, requiring less boilerplate code in general. Now all that is nec-essary to define a new model class is an evaluate method that computes the model. Optionally one can define fittableparameters, a fit_deriv, and/or an inverse. The new, improved custom_model decorator reduces the boilerplateneeded for many models even more. See Defining New Model Classes for more details.


https://github.com/astropy/astropy-APEs/blob/master/APE6.rsthttps://github.com/astropy/astropy-APEs/blob/master/APE6.rsthttp://www.yaml.org/http://pyyaml.org


Array broadcasting has also been improved, enabling a broader range of possibilities for the values of model parame-ters and inputs. Support has also been improved for Model Sets (previously referred to as parameter sets) which canbe thought of like an array of models of the same class, each with different sets of parameters, which can be fittedsimultaneously either to the same data, or to different data sets per model. See Instantiating and Evaluating Modelsfor more details.

It is now possible to create compound models by combining existing models using the standard arithmetic operatorssuch as + and *, as well as functional composition using the | operator. This provides a powerful and flexible new wayto create more complex models without having to define any special classes or functions. For example:

>>> from astropy.modeling.models import Gaussian1D>>> gaussian1 = Gaussian1D(1, 0, 0.2)>>> gaussian2 = Gaussian1D(2.5, 0.5, 0.1)>>> sum_of_gaussians = gaussian1 + gaussian2

The resulting model works like any other model, and also works with the fitting framework. See the introduction tocompound models and full compound models documentation for more examples.

1.9 New Table features

1.9.1 Refactor of table infrastructure

The underlying data container for the Astropy Table object has been changed in Astropy v1.0. Previously, tables werestored internally as a Numpy structured array object, with column access being a memory view of the correspondingNumpy array field. Starting with this release the fundamental data container is an ordered dictionary of individualcolumn objects and each Column object is the sole owner of its data.

The biggest impact to users is that operations such as adding or removing table columns is now significantly fasterbecause there is no structured array to rebuild each time.

For details please see Table implementation change in 1.0.

1.9.2 Support for mixin columns

Version v1.0 of Astropy introduces a new concept of the Mixin Column in tables which allows integration of ap-propriate non-Column based class objects within a Table object. These mixin column objects are not converted in anyway but are used natively.

The available built-in mixin column classes are Quantity, SkyCoord, and Time. User classes for array-like objectsthat support the Mixin protocol can also be used in tables as mixin columns.

Warning: While the Astropy developers are excited about this new capability and intend to improve it, theinterface for using mixin columns is not stable at this point and it is not recommended for use in production code.

As an example we can create a table and add a time column:

>>> from astropy.table import Table>>> from astropy.time import Time>>> t = Table()>>> t['index'] = [1, 2]>>> t['time'] = Time(['2001-01-02T12:34:56', '2001-02-03T00:01:02'])>>> print(t)index time----- -----------------------

1.9. New Table features 9


1 2001-01-02T12:34:56.0002 2001-02-03T00:01:02.000

The important point here is that the time column is a bona fide Time object:

>>> t['time']

>>> t['time'].mjdarray([ 51911.52425926, 51943.00071759])

For all the details, including a new QTable class, please see Mixin columns.

1.10 Integration with WCSAxes

The WCS class can now be used as a Matplotlib projection to make plots of images with WCS coordinates overlaid,making use of the WCSAxes affiliated package behind the scenes. More information on using this functionality canbe found in the WCSAxes documentation.

1.11 Deprecation and backward-incompatible changes

Astropy is now no longer supported on Python 3.1 and 3.2. Python 3.x users should use Python 3.3 or 3.4. In addition,support for Numpy 1.5 has been dropped, and users should make sure they are using Numpy 1.6 or later.

1.12 Full change log

To see a detailed list of all changes in version v1.0, including changes in API, please see the Full Changelog.

Astropy at a glance


http://www.matplotlib.orghttp://wcsaxes.readthedocs.orghttp://wcsaxes.readthedocs.org

CHAPTER 2

Overview

Here we describe a broad overview of the Astropy project and its parts.

2.1 Astropy Project Concept

The Astropy Project is distinct from the astropy package. The Astropy Project is a process intended to facilitatecommunication and interoperability of python packages/codes in astronomy and astrophysics. The project thus encom-passes the astropy core package (which provides a common framework), all affiliated packages (described belowin Affiliated Packages), and a general community aimed at bringing resources together and not duplicating efforts.

2.2 astropy Core Package

The astropy package (alternatively known as the core package) contains various classes, utilities, and a packagingframework intended to provide commonly-used astronomy tools. It is divided into a variety of sub-packages, which aredocumented in the remainder of this documentation (see User Documentation for documentation of these components).

The core also provides this documentation, and a variety of utilities that simplify starting other python astron-omy/astrophysics packages. As described in the following section, these simplify the process of creating affiliatedpackages.

2.3 Affiliated Packages

The Astropy project includes the concept of affiliated packages. An affiliated package is an astronomy-related pythonpackage that is not part of the astropy core source code, but has requested to be included in the general communityeffort of the Astropy project. Such a package may be a candidate for eventual inclusion in the main astropy package(although this is not required). Until then, however, it is a separate package, and may not be in the astropy namespace.

The authoritative list of current affiliated packages is available at http://affiliated.astropy.org, including a machine-readable JSON file.

If you are interested in starting an affiliated package, or have a package you are interested in making more compatiblewith astropy, the astropy core package includes features that simplify and homogenize package management. Astropyprovides a package template that provides a common way to organize a package, to make your life simpler. You canuse this template either with a new package you are starting or an existing package to give it most of the organizationaltools Astropy provides, including the documentation, testing, and Cython-building tools. See the usage instructions inthe template for further details.

11

http://affiliated.astropy.orghttp://affiliated.astropy.org/registry.jsonhttp://github.com/astropy/package-templatehttps://github.com/astropy/package-template/blob/master/README.rsthttps://github.com/astropy/package-template/blob/master/README.rst


To then get your package listed on the registry, take a look at the guidelines for becoming an affiliated package, andthen post your intent on the astropy-dev mailing list. The Astropy coordination committee, in consultation with thecommunity, will provide you feedback on the package, and will add it to the registry when it is approved.

2.4 Community

Aside from the actual code, Astropy is also a community of astronomy- associated users and developers that agreethat sharing utilities is healthy for the community and the science it produces. This community is of course centralto accomplishing anything with the code itself. We follow the Python Software Foundation Code of Conduct andwelcome anyone who wishes to contribute to the project.

12 Chapter 2. Overview

http://affiliated.astropy.org#affiliated-instructionshttp://groups.google.com/group/astropy-devhttp://www.python.org/psf/codeofconduct/

CHAPTER 3

Installation

3.1 Requirements

Astropy has the following strict requirements:

Python 2.6 (>=2.6.5), 2.7, 3.3, or 3.4

Prior to Astropy v1.0 Python 3.1 and 3.2 are also supported.

Numpy 1.6.0 or later

Astropy also depends on other packages for optional features:

h5py: To read/write Table objects from/to HDF5 files

BeautifulSoup: To read Table objects from HTML files

PyYAML: To read/write Table objects from/to the Enhanced CSV ASCII table format.

scipy: To power a variety of features (currently mainly cosmology-related functionality)

xmllint: To validate VOTABLE XML files.

matplotlib: To provide plotting functionality that astropy.visualization enhances.

WCSAxes: To use astropy.wcs to define projections in Matplotlib.

However, note that these only need to be installed if those particular features are needed. Astropy will import even ifthese dependencies are not installed.

3.2 Installing Astropy

3.2.1 Using pip

To install Astropy with pip, simply run:

pip install --no-deps astropy

Warning: Users of the Anaconda python distribution should follow the instructions for Anaconda python distri-bution.

Note: You will need a C compiler (e.g. gcc or clang) to be installed (see Building from source below) for theinstallation to succeed.

13

http://www.python.org/http://numpy.scipy.orghttp://h5py.org/http://www.crummy.com/software/BeautifulSoup/http://pyyaml.orghttp://www.scipy.orghttp://www.xmlsoft.org/http://matplotlib.org/http://wcsaxes.readthedocs.org/en/latest/http://www.pip-installer.org/en/latest/


Note: The --no-deps flag is optional, but highly recommended if you already have Numpy installed, since otherwisepip will sometimes try to help you by upgrading your Numpy installation, which may not always be desired.

Note: If you get a PermissionError this means that you do not have the required administrative access to installnew packages to your Python installation. In this case you may consider using the --user option to install the packageinto your home directory. You can read more about how to do this in the pip documentation.

Alternatively, if you intend to do development on other software that uses Astropy, such as an affiliated package,consider installing Astropy into a virtualenv.

Do not install Astropy or other third-party packages using sudo unless you are fully aware of the risks.

3.2.2 Anaconda python distribution

Astropy is installed by default with Anaconda. To update to the latest version run:

conda update astropy

Note: There may be a delay of a day or two between when a new version of Astropy is released and when a packageis available for Anaconda. You can check for the list of available versions with conda search astropy.

Note: Attempting to use pip to upgrade your installation of Astropy may result in a corrupted installation.

3.2.3 Binary installers

Binary installers are available on Windows for Python 2.6, 2.7, and >= 3.3 at PyPI.

3.2.4 Testing an installed Astropy

The easiest way to test your installed version of astropy is running correctly is to use the astropy.test() function:

import astropyastropy.test()

The tests should run and print out any failures, which you can report at the Astropy issue tracker.

Note: This way of running the tests may not work if you do it in the astropy source distribution. See Testing a sourcecode build of Astropy for how to run the tests from the source code directory, or Running Tests for more details.

Note: Running the tests this way is currently disabled in the IPython REPL due to conflicts with some commondisplay settings in IPython. Please run the Astropy tests under the standard Python command-line interpreter.

14 Chapter 3. Installation

http://www.pip-installer.org/en/1.2.1/other-tools.html#using-pip-with-the-user-schemehttps://pypi.python.org/pypi/astropyhttp://github.com/astropy/astropy/issues


3.3 Building from source

3.3.1 Prerequisites

You will need a compiler suite and the development headers for Python and Numpy in order to build Astropy. OnLinux, using the package manager for your distribution will usually be the easiest route, while on MacOS X you willneed the XCode command line tools.

The instructions for building Numpy from source are also a good resource for setting up your environment to buildPython packages.

You will also need Cython (v0.15 or later) and jinja2 (v2.7 or later) installed to build from source, unless you areinstalling a numbered release. (The releases packages have the necessary C files packaged with them, and hence donot require Cython.)

Note: If you are using MacOS X, you will need to the XCode command line tools. One way to get them is to installXCode. If you are using OS X 10.7 (Lion) or later, you must also explicitly install the command line tools. You can dothis by opening the XCode application, going to Preferences, then Downloads, and then under Components, click onthe Install button to the right of Command Line Tools. Alternatively, on 10.7 (Lion) or later, you do not need to in-stall XCode, you can download just the command line tools from https://developer.apple.com/downloads/index.action(requires an Apple developer account).

3.3.2 Obtaining the source packages

Source packages

The latest stable source package for Astropy can be downloaded here.

Development repository

The latest development version of Astropy can be cloned from github using this command:

git clone git://github.com/astropy/astropy.git

Note: If you wish to participate in the development of Astropy, see Developer Documentation. This document coversonly the basics necessary to install Astropy.

3.3.3 Building and Installing

Astropy uses the Python distutils framework for building and installing and requires the distribute extensionthe lateris automatically downloaded when running python setup.py if it is not already provided by your system.

If Numpy is not already installed in your Python environment, the astropy setup process will try to download andinstall it before continuing to install astropy.

To build Astropy (from the root of the source tree):

python setup.py build

To install Astropy (from the root of the source tree):

3.3. Building from source 15

http://docs.scipy.org/doc/numpy/user/install.htmlhttp://cython.org/http://jinja.pocoo.org/docs/dev/https://developer.apple.com/xcode/https://developer.apple.com/downloads/index.actionhttps://pypi.python.org/pypi/astropyhttp://docs.python.org/install/index.htmlhttp://pypi.python.org/pypi/distribute


python setup.py install

3.3.4 Troubleshooting

If you get an error mentioning that you do not have the correct permissions to install Astropy into the defaultsite-packages directory, you can try installing with:

python setup.py install --user

which will install into a default directory in your home directory.

External C libraries

The Astropy source ships with the C source code of a number of libraries. By default, these internal copies are usedto build Astropy. However, if you wish to use the system-wide installation of one of those libraries, you can pass oneor more of the --use-system-X flags to the setup.py build command.

For example, to build Astropy using the system libexpat, use:

python setup.py build --use-system-expat

To build using all of the system libraries, use:

python setup.py build --use-system-libraries

To see which system libraries Astropy knows how to build against, use:

python setup.py build --help

As with all distutils commandline options, they may also be provided in a setup.cfg in the same directory assetup.py. For example, to use the system libexpat, add the following to the setup.cfg file:

[build]use_system_expat=1

The required version of setuptools is not available

If upon running the setup.py script you get a message like

The required version of setuptools (>=0.9.8) is not available, and cant be installed while this script isrunning. Please install a more recent version first, using easy_install -U setuptools.

(Currently using setuptools 0.6c11 (/path/to/setuptools-0.6c11-py2.7.egg))

this is because you have a very outdated version of the setuptools package which is used to install Python packages.Normally Astropy will bootstrap newer version of setuptools via the network, but setuptools suggests that you firstuninstall the old version (the easy_install -U setuptools command).

However, in the likely case that your version of setuptools was installed by an OS system package (on Linux check yourpackage manager like apt or yum for a package called python-setuptools), trying to uninstall with easy_installand without using sudo may not work, or may leave your system package in an inconsistent state.

As the best course of action at this point depends largely on the individual system and how it is configured, if you arenot sure yourself what do please ask on the Astropy mailing list.


http://www.libexpat.org/http://www.libexpat.org/https://pythonhosted.org/setuptools/


The Windows installer cant find Python in the registry

This is a common issue with Windows installers for Python packages that do not support the new User Access Control(UAC) framework added in Windows Vista and later. In particular, when a Python is installed for all users (asopposed to for a single user) it adds entries for that Python installation under the HKEY_LOCAL_MACHINE (HKLM)hierarchy and not under the HKEY_CURRENT_USER (HKCU) hierarchy. However, depending on your UAC settings, ifthe Astropy installer is not executed with elevated privileges it will not be able to check in HKLM for the requiredinformation about your Python installation.

In short: If you encounter this problem its because you need the appropriate entries in the Windows registry forPython. You can download this script and execute it with the same Python as the one you want to install Astropy into.For example to add the missing registry entries to your Python 2.7:

C:\>C:\Python27\python.exe C:\Path\To\Downloads\win_register_python.py

3.3.5 Building documentation

Note: Building the documentation is in general not necessary unless you are writing new documentation or donot have internet access, because the latest (and archive) versions of astropys documentation should be available atdocs.astropy.org .

Building the documentation requires the Astropy source code and some additional packages:

Sphinx (and its dependencies) 1.0 or later

Graphviz

Astropy-helpers (Astropy and most affiliated packages include this as a submodule in the source repository, soit does not need to be installed separately.)

Note: Sphinx also requires a reasonably modern LaTeX installation to render equations. Per the Sphinx documenta-tion, for the TexLive distribution the following packages are required to be installed:

latex-recommended

latex-extra

fonts-recommended

For other LaTeX distributions your mileage may vary. To build the PDF documentation using LaTeX, the fonts-extraTexLive package or the inconsolata CTAN package are also required.

There are two ways to build the Astropy documentation. The most straightforward way is to execute the command(from the astropy source directory):

python setup.py build_sphinx

The documentation will be built in the docs/_build/html directory, and can be read by pointing a web browser todocs/_build/html/index.html.

The LaTeX documentation can be generated by using the command:

python setup.py build_sphinx -b latex

The LaTeX file Astropy.tex will be created in the docs/_build/latex directory, and can be compiled usingpdflatex.

The above method builds the API documentation from the source code. Alternatively, you can do:

3.3. Building from source 17

https://gist.github.com/embray/6042780#file-win_register_python-pyhttp://docs.astropy.orghttp://sphinx.pocoo.orghttp://www.graphviz.orghttps://github.com/astropy/astropy-helpershttp://sphinx-doc.org/builders.html?highlight=latex#sphinx.builders.latex.LaTeXBuilderhttp://sphinx-doc.org/builders.html?highlight=latex#sphinx.builders.latex.LaTeXBuilder


cd docsmake html

And the documentation will be generated in the same location, but using the installed version of Astropy.

3.3.6 Testing a source code build of Astropy

The easiest way to test that your Astropy built correctly (without installing astropy) is to run this from the root of thesource tree:

python setup.py test

There are also alternative methods of Running Tests.


CHAPTER 4

Getting Started with Astropy

4.1 Importing Astropy

In order to encourage consistency amongst users in importing and using Astropy functionality, we have put togetherthe following guidelines.

Since most of the functionality in Astropy resides in sub-packages, importing astropy as:

>>> import astropy

is not very useful. Instead, it is best to import the desired sub-package with the syntax:

>>> from astropy import subpackage

For example, to access the FITS-related functionality, you can import astropy.io.fits with:

>>> from astropy.io import fits>>> hdulist = fits.open('data.fits')

In specific cases, we have recommended shortcuts in the documentation for specific sub-packages, for example:

>>> from astropy import units as u>>> from astropy import coordinates as coord>>> coord.SkyCoord(ra=10.68458*u.deg, dec=41.26917*u.deg, frame='icrs')

Finally, in some cases, most of the required functionality is contained in a single class (or a few classes). In thosecases, the class can be directly imported:

>>> from astropy.cosmology import WMAP7>>> from astropy.table import Table>>> from astropy.wcs import WCS

Note that for clarity, and to avoid any issues, we recommend to never import any Astropy functionality using *, forexample:

>>> from astropy.io.fits import * # NOT recommended

Some components of Astropy started off as standalone packages (e.g. PyFITS, PyWCS), so in cases where Astropyneeds to be used as a drop-in replacement, the following syntax is also acceptable:

>>> from astropy.io import fits as pyfits

19


4.2 Getting started with subpackages

Because different subpackages have very different functionality, further suggestions for getting started are in thedocumentation for the subpackages, which you can reach by browsing the sections listed in the User Documentation.

Or, if you want to dive right in, you can either look at docstrings for particular a package or object, or access theirdocumentation using the find_api_page function. For example, doing this:

>>> from astropy import find_api_page>>> from astropy.units import Quantity>>> find_api_page(Quantity)

Will bring up the documentation for the Quantity class in your browser.

4.3 Command-line utilities

For convenience, several of Astropys subpackages install utility programs on your system which allow common tasksto be performed without having to open a Python interpreter. These utilities include:

fitsheader: prints the headers of a FITS file.

fitscheck: verifies and optionally re-writes the CHECKSUM and DATASUM keywords of a FITS file.

fitsdiff : compares two FITS files and reports the differences.

Scripts: converts FITS images to bitmaps, including scaling and stretching.

samp_hub: starts a SAMP hub.

volint: checks a VOTable file for compliance against the standards.

wcslint: checks the WCS keywords in a FITS file for compliance against the standards.

Core data structures and transformations

20 Chapter 4. Getting Started with Astropy

CHAPTER 5

Constants (astropy.constants)

5.1 Introduction

astropy.constants contains a number of physical constants useful in Astronomy. Constants are Quantity objectswith additional meta-data describing their provenance and uncertainties.

5.2 Getting Started

To use the constants in S.I. units, you can import the constants directly from the astropy.constants sub-package:

>>> from astropy.constants import G

or, if you want to avoid having to explicitly import all the constants you need, you can simply do:

>>> from astropy import constants as const

and then subsequently use for example const.G. Constants are fully-fledged Quantity objects, so you can easilyconvert them to different units for example:

>>> print const.cName = Speed of light in vacuumValue = 299792458.0Error = 0.0Units = m / sReference = CODATA 2010

>>> print const.c.to('km/s')299792.458 km / s

>>> print const.c.to('pc/yr')0.306601393788 pc / yr

and you can use them in conjunction with unit and other non-constant Quantity objects:

>>> from astropy import units as u>>> F = (const.G * 3. * const.M_sun * 100 * u.kg) / (2.2 * u.au) ** 2>>> print F.to(u.N)0.367669392028 N

It is possible to convert most constants to cgs using e.g.:

21


>>> const.c.cgs

However, some constants are defined with different physical dimensions in cgs and cannot be directly converted.Because of this ambiguity, such constants cannot be used in expressions without specifying a system:

>>> 100 * const.eTraceback (most recent call last):

...TypeError: Constant u'e' does not have physically compatible unitsacross all systems of units and cannot be combined with othervalues without specifying a system (eg. e.emu)>>> 100 * const.e.esu

5.3 Reference/API

5.3.1 astropy.constants Package

Contains astronomical and physical constants for use in Astropy or other places.

A typical use case might be:

>>> from astropy.constants import c, m_e>>> # ... define the mass of something you want the rest energy of as m ...>>> m = m_e>>> E = m * c**2>>> E.to('MeV')

The following constants are available:

Name Value Unit DescriptionG 6.67384e-11 m3 / (kg s2) Gravitational constantL_sun 3.846e+26 W Solar luminosityM_earth 5.9742e+24 kg Earth massM_jup 1.8987e+27 kg Jupiter massM_sun 1.9891e+30 kg Solar massN_A 6.02214129e+23 1 / (mol) Avogadros numberR 8.3144621 J / (K mol) Gas constantR_earth 6378136 m Earth equatorial radiusR_jup 71492000 m Jupiter equatorial radiusR_sun 695508000 m Solar radiusRyd 10973731.6 1 / (m) Rydberg constanta0 5.29177211e-11 m Bohr radiusalpha 0.00729735257 Fine-structure constantatmosphere 101325 Pa Atmosphereau 1.49597871e+11 m Astronomical Unitb_wien 0.0028977721 m K Wien wavelength displacement law constantc 299792458 m / (s) Speed of light in vacuume 1.60217657e-19 C Electron chargeeps0 8.85418782e-12 F/m Electric constant

Continued on next page

22 Chapter 5. Constants (astropy.constants)


Table 5.1 continued from previous pageName Value Unit Descriptiong0 9.80665 m / s2 Standard acceleration of gravityh 6.62606957e-34 J s Planck constanthbar 1.05457173e-34 J s Reduced Planck constantk_B 1.3806488e-23 J / (K) Boltzmann constantkpc 3.08567758e+19 m Kiloparsecm_e 9.10938291e-31 kg Electron massm_n 1.67492735e-27 kg Neutron massm_p 1.67262178e-27 kg Proton massmu0 1.25663706e-06 N/A2 Magnetic constantmuB 9.27400968e-24 J/T Bohr magnetonpc 3.08567758e+16 m Parsecsigma_sb 5.670373e-08 W / (K4 m2) Stefan-Boltzmann constantu 1.66053892e-27 kg Atomic mass

Classes

Constant A physical or astronomical constant.EMConstant An electromagnetic constant.

Constant

class astropy.constants.ConstantBases: astropy.units.quantity.Quantity

A physical or astronomical constant.

These objects are quantities that are meant to represent physical constants.

Attributes Summary

abbrev A typical ASCII text abbreviation of the constant, also generally the same as the Python variable used for this constant.cgs If the Constant is defined in the CGS system return that instance of the constant, else convert to a Quantity in the appropriate CGS units.name The full name of the constant.reference The source used for the value of this constant.si If the Constant is defined in the SI system return that instance of the constant, else convert to a Quantity in the appropriate SI units.system The system of units in which this constant is defined (typically None so long as the constants units can be directly converted between systems).uncertainty The known uncertainty in this constants value.

Methods Summary

Attributes Documentation

abbrevA typical ASCII text abbreviation of the constant, also generally the same as the Python variable used forthis constant.

5.3. Reference/API 23

http://docs.python.org/library/constants.html#None


cgsIf the Constant is defined in the CGS system return that instance of the constant, else convert to a Quantityin the appropriate CGS units.

nameThe full name of the constant.

referenceThe source used for the value of this constant.

siIf the Constant is defined in the SI system return that instance of the constant, else convert to a Quantityin the appropriate SI units.

systemThe system of units in which this constant is defined (typically None so long as the constants units can bedirectly converted between systems).

uncertaintyThe known uncertainty in this constants value.

Methods Documentation

copy()Return a copy of this Constant instance. Since they are by definition immutable, this merely returnsanother reference to self.

EMConstant

class astropy.constants.EMConstantBases: astropy.constants.Constant

An electromagnetic constant.

Attributes Summary

cgs Overridden for EMConstant to raise a TypeError emphasizing that there are multiple EM extensions to CGS.

Attributes Documentation

cgsOverridden for EMConstant to raise a TypeError emphasizing that there are multiple EM extensions toCGS.


http://docs.python.org/library/constants.html#Nonehttp://docs.python.org/library/exceptions.html#exceptions.TypeErrorhttp://docs.python.org/library/exceptions.html#exceptions.TypeError


Class Inheritance Diagram

Constant EMConstantQuantityndarray

5.3. Reference/API 25

CHAPTER 6

Units and Quantities (astropy.units)

6.1 Introduction

astropy.units handles defining, converting between, and performing arithmetic with physical quantities. Examplesof physical quantities are meters, seconds, Hz, etc.

astropy.units does not know spherical geometry or sexagesimal (hours, min, sec): if you want to deal with celestialcoordinates, see the astropy.coordinates package.

6.2 Getting Started

Most users of the astropy.units package will work with quantities: the combination of a value and a unit. Theeasiest way to create a Quantity is to simply multiply or divide a value by one of the built-in units. It works withscalars, sequences and Numpy arrays:

>>> from astropy import units as u>>> 42.0 * u.meter

>>> [1., 2., 3.] * u.m

>>> import numpy as np>>> np.array([1., 2., 3.]) * u.m

You can get the unit and value from a Quantity using the unit and value members:

>>> q = 42.0 * u.meter>>> q.value42.0>>> q.unitUnit("m")

From this simple building block, its easy to start combining quantities with different units:

>>> 15.1 * u.meter / (32.0 * u.second)

>>> 3.0 * u.kilometer / (130.51 * u.meter / u.second)

>>> (3.0 * u.kilometer / (130.51 * u.meter / u.second)).decompose()

27


Unit conversion is done using the to() method, which returns a new Quantity in the given unit:

>>> x = 1.0 * u.parsec>>> x.to(u.km)

It is also possible to work directly with units at a lower level, for example, to create custom units:

>>> from astropy.units import imperial

>>> cms = u.cm / u.s>>> # ...and then use some imperial units>>> mph = imperial.mile / u.hour

>>> # And do some conversions>>> q = 42.0 * cms>>> q.to(mph)

Units that cancel out become a special unit called the dimensionless unit:

>>> u.m / u.mUnit(dimensionless)

astropy.units is able to match compound units against the units it already knows about:

>>> (u.s ** -1).compose()[Unit("Bq"), Unit("Hz"), Unit("3.7e+10 Ci")]

And it can convert between unit systems, such as SI or CGS:

>>> (1.0 * u.Pa).cgs

astropy.units also handles equivalencies, such as that between wavelength and frequency. To use that feature, equiv-alence objects are passed to the to() conversion method. For instance, a conversion from wavelength to frequencydoesnt normally work:

>>> (1000 * u.nm).to(u.Hz)Traceback (most recent call last):

...UnitConversionError: 'nm' (length) and 'Hz' (frequency) are not convertible

but by passing an equivalency list, in this case spectral(), it does:

>>> (1000 * u.nm).to(u.Hz, equivalencies=u.spectral())

Quantities and units can be printed nicely to strings using the Format String Syntax, the preferred string formattingsyntax in recent versions of python. Format specifiers (like 0.03f) in new-style format strings will used to format thequantity value:

>>> q = 15.1 * u.meter / (32.0 * u.second)>>> q

>>> "{0:0.03f}".format(q)'0.472 m / s'

The value and unit can also be formatted separately. Format specifiers used on units can be used to choose the unitformatter:

28 Chapter 6. Units and Quantities (astropy.units)

http://docs.python.org/library/string.html#format-string-syntax


>>> q = 15.1 * u.meter / (32.0 * u.second)>>> q

>>> "{0.value:0.03f} {0.unit:FITS}".format(q)'0.472 m s-1'

6.3 Using astropy.units

6.3.1 Quantity

The Quantity object is meant to represent a value that has some unit associated with the number.

Creating Quantity instances

Quantity objects are created through multiplication or division with Unit objects. For example, to create a Quantityto represent 15 m/s:

>>> import astropy.units as u>>> 15 * u.m / u.s

Note: Quantity objects are converted to float by default.

As another example:

>>> 1.25 / u.s

You can also create instances using the Quantity constructor directly, by specifying a value and unit:

>>> u.Quantity(15, u.m / u.s)

Quantity objects can also be created automatically from Numpy arrays or Python sequences:

>>> [1, 2, 3] * u.m

>>> import numpy as np>>> np.array([1, 2, 3]) * u.m

Quantity objects can also be created from sequences of Quantity objects, as long as all of their units are equivalent,and will automatically convert to Numpy arrays:

>>> qlst = [60 * u.s, 1 * u.min]>>> u.Quantity(qlst, u.minute)

Finally, the current unit and value can be accessed via the unit and value attributes:

>>> q = 2.5 * u.m / u.s>>> q.unitUnit("m / s")>>> q.value2.5

6.3. Using astropy.units 29


Converting to different units

Quantity objects can be converted to different units using the to() method:

>>> q = 2.3 * u.m / u.s>>> q.to(u.km / u.h)

For convenience, the si and cgs attributes can be used to convert the Quantity to base S.I. or c.g.s units:

>>> q = 2.4 * u.m / u.s>>> q.si

>>> q.cgs

Arithmetic

Addition and Subtraction

Addition or subtraction between Quantity objects is supported when their units are equivalent. When the units areequal, the resulting object has the same unit:

>>> 11 * u.s + 30 * u.s

>>> 30 * u.s - 11 * u.s

If the units are equivalent, but not equal (e.g. kilometer and meter), the resulting object has units of the object on theleft:

>>> 1100.1 * u.m + 13.5 * u.km

>>> 13.5 * u.km + 1100.1 * u.m

>>> 1100.1 * u.m - 13.5 * u.km

>>> 13.5 * u.km - 1100.1 * u.m

Addition and subtraction is not supported between Quantity objects and basic numeric types:

>>> 13.5 * u.km + 19.412Traceback (most recent call last):

...UnitsError: Can only apply 'add' function to dimensionlessquantities when other argument is not a quantity (unless thelatter is all zero/infinity/nan)

except for dimensionless quantities (see Dimensionless quantities).

Multiplication and Division

Multiplication and division is supported between Quantity objects with any units, and with numeric types. For theseoperations between objects with equivalent units, the resulting object has composite units:



>>> 1.1 * u.m * 140.3 * u.cm

>>> 140.3 * u.cm * 1.1 * u.m

>>> 1. * u.m / (20. * u.cm)

>>> 20. * u.cm / (1. * u.m)

For multiplication, you can change how to represent the resulting object by using the to() method:

>>> (1.1 * u.m * 140.3 * u.cm).to(u.m**2)

>>> (1.1 * u.m * 140.3 * u.cm).to(u.cm**2)

For division, if the units are equivalent, you may want to make the resulting object dimensionless by reducing theunits. To do this, use the decompose() method:

>>> (20. * u.cm / (1. * u.m)).decompose()

This method is also useful for more complicated arithmetic:

>>> 15. * u.kg * 32. * u.cm * 15 * u.m / (11. * u.s * 1914.15 * u.ms)

>>> (15. * u.kg * 32. * u.cm * 15 * u.m / (11. * u.s * 1914.15 * u.ms)).decompose()

Numpy functions

Quantity objects are actually full Numpy arrays (the Quantity object class inherits from and extends thenumpy.ndarray class), and we have tried to ensure that most Numpy functions behave properly with quantities:

>>> q = np.array([1., 2., 3., 4.]) * u.m / u.s>>> np.mean(q)

>>> np.std(q)

including functions that only accept specific units such as angles:

>>> q = 30. * u.deg>>> np.sin(q)

or dimensionless quantities:

>>> from astropy.constants import h, k_B>>> nu = 3 * u.GHz>>> T = 30 * u.K>>> np.exp(-h * nu / (k_B * T))

(see Dimensionless quantities for more details).



Dimensionless quantities

Dimensionless quantities have the characteristic that if they are added or subtracted from a Python scalar or unitlessndarray, or if they are passed to a Numpy function that takes dimensionless quantities, the units are simplified so thatthe quantity is dimensionless and scale-free. For example:

>>> 1. + 1. * u.m / u.km

which is different from:

>>> 1. + (1. * u.m / u.km).value2.0

In the latter case, the result is 2.0 because the unit of (1. * u.m / u.km) is not scale-free by default:

>>> q = (1. * u.m / u.km)>>> q.unitUnit("m / km")>>> q.unit.decompose()Unit(dimensionless with a scale of 0.001)

However, when combining with a non-quantity object, the unit is automatically decomposed to be scale-free, givingthe expected result.

This also occurs when passing dimensionless quantities to functions that take dimensionless quantities:

>>> nu = 3 * u.GHz>>> T = 30 * u.K>>> np.exp(- h * nu / (k_B * T))

The result is independent from the units the different quantities were specified in:

>>> nu = 3.e9 * u.Hz>>> T = 30 * u.K>>> np.exp(- h * nu / (k_B * T))

Converting to plain Python scalars

Converting Quantity objects does not work for non-dimensionless quantities:

>>> float(3. * u.m)Traceback (most recent call last):

...TypeError: Only dimensionless scalar quantities can be convertedto Python scalars

Instead, only dimensionless values can be converted to plain Python scalars:

>>> float(3. * u.m / (4. * u.m))0.75>>> float(3. * u.km / (4. * u.m))750.0>>> int(6. * u.km / (2. * u.m))3000


http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html#numpy.ndarray


Functions Accepting Quantities

Validation of quantity arguments to functions can lead to many repetitons of the same checking code. A decorator isprovided which verifies that certain arguments to a function are Quantity objects and that the units are compatiblewith a desired unit.

The decorator does not convert the unit to the desired unit, say arcseconds to degrees, it merely checks that such aconversion is possible, thus verifying that the Quantity argument can be used in calculations.

The decorator quantity_input accepts keyword arguments to spcifiy which arguments should be validated and whatunit they are expected to be compatible with:

>>> @u.quantity_input(myarg=u.deg)... def myfunction(myarg):... return myarg.unit

>>> myfunction(100*u.arcsec)Unit("arcsec")

Under Python 3 you can use the annotations syntax to provide the units:

>>> @u.quantity_input... def myfunction(myarg: u.arcsec):... return myarg.unit

>>> myfunction(100*u.arcsec)Unit("arcsec")

Known issues with conversion to numpy arrays

Since Quantity objects are Numpy arrays, we are not able to ensure that only dimensionless quantities are convertedto Numpy arrays:

>>> np.array([1, 2, 3] * u.m)array([ 1., 2., 3.])

Similarly, while most numpy functions work properly, a few have known issues, either ignoring the unit (e.g.,np.dot) or not reinitializing it properly (e.g., np.hstack). This propagates to more complex functions such asnp.linalg.norm and scipy.integrate.odeint.

Subclassing Quantity

To subclass Quantity, one generally proceeds as one would when subclassing ndarray, i.e., one typically needs tooverride __new__ (rather than __init__) and uses the numpy.ndarray.__array_finalize__ method to update at-tributes. For details, see the numpy documentation on subclassing. For examples, one can look at Quantity itself,where, e.g., the astropy.units.Quantity.__array_finalize__ method is used to pass on the unit, at Angle,where strings are parsed as angles in the astropy.coordinates.Angle.__new__ method and at Longitude, wherethe astropy.coordinates.Longitude.__array_finalize__ method is used to pass on the angle at which longi-tudes wrap.

Another method that is meant to be overridden by subclasses, one specific to Quantity, isastropy.units.Quantity.__quantity_subclass__. This is called to decide which type of subclass to re-turn, based on the unit of the quantity that is to be created. It is used, e.g., in Angle to return a Quantity if acalculation returns a unit other than an angular one.


http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html#numpy.ndarrayhttp://docs.scipy.org/doc/numpy/user/basics.subclassing.html


6.3.2 Standard units

Standard units are defined in the astropy.units package as object instances.

All units are defined in term of basic irreducible units. The irreducible units include:

Length (meter)

Time (second)

Mass (kilogram)

Current (ampere)

Temperature (Kelvin)

Angular distance (radian)

Solid angle (steradian)

Luminous intensity (candela)

Stellar magnitude (mag)

Amount of substance (mole)

Photon count (photon)

(There are also some more obscure base units required by the FITS standard that are no longer recommended for use.)

Units that involve combinations of fundamental units are instances of CompositeUnit. In most cases, one does notneed to worry about the various kinds of unit classes unless one wants to design a more complex case.

There are many units already predefined in the module. One may use the find_equivalent_units method to list allthe existing predefined units of a given type:

>>> from astropy import units as u>>> u.g.find_equivalent_units()Primary name | Unit definition | Aliases

[M_e | 9.10938e-31 kg | ,M_p | 1.67262e-27 kg | ,g | 0.001 kg | gram ,kg | irreducible | kilogram ,solMass | 1.9891e+30 kg | M_sun, Msun ,t | 1000 kg | tonne ,u | 1.66054e-27 kg | Da, Dalton ,

]

The dimensionless unit

In addition to these units, astropy.units includes the concept of the dimensionless unit, used to indicate quantitiesthat dont have a physical dimension. This is distinct in concept from a unit that is equal to None: that indicates thatno unit was specified in the data or by the user.

For convenience, there is a unit that is both dimensionless and unscaled: the dimensionless_unscaled object:

>>> from astropy import units as u>>> u.dimensionless_unscaledUnit(dimensionless)

Dimensionless quantities are often defined as products or ratios of quantities that are not dimensionless, but whosedimensions cancel out when their powers are multiplied. For example:


http://docs.python.org/library/constants.html#None


>>> u.m / u.mUnit(dimensionless)

For compatibility with the supported unit string formats, this is equivalent to Unit() and Unit(1), though usingu.dimensionless_unscaled in Python code is preferred for readability:

>>> u.dimensionless_unscaled == u.Unit('')True>>> u.dimensionless_unscaled == u.Unit(1)True

Note that in many cases, a dimensionless unit may also have a scale. For example:

>>> (u.km / u.m).decompose()Unit(dimensionless with a scale of 1000.0)>>> (u.km / u.m).decompose() == u.dimensionless_unscaledFalse

To determine if a unit is dimensionless (but regardless of the scale), use the physical_type property:

>>> (u.km / u.m).physical_typeu'dimensionless'>>> # This also has a scale, so it is not the same as u.dimensionless_unscaled>>> (u.km / u.m) == u.dimensionless_unscaledFalse>>> # However, (u.m / u.m) has a scale of 1.0, so it is the same>>> (u.m / u.m) == u.dimensionless_unscaledTrue

Enabling other units

By default, only the default units are searched by find_equivalent_units and similar methods that do searching.This includes SI, CGS and astrophysical units. However, one may wish to enable the imperial or other user-definedunits.

For example, to enable Imperial units, simply do:

>>> from astropy.units import imperial>>> imperial.enable()>>> u.m.find_equivalent_units()Primary name | Unit definition | Aliases

[AU | 1.49598e+11 m | au ,Angstrom | 1e-10 m | AA, angstrom ,cm | 0.01 m | centimeter ,ft | 0.3048 m | foot ,inch | 0.0254 m | ,lyr | 9.46073e+15 m | lightyear ,m | irreducible | meter ,mi | 1609.34 m | mile ,micron | 1e-06 m | ,nmi | 1852 m | nauticalmile, NM ,pc | 3.08568e+16 m | parsec ,solRad | 6.95508e+08 m | R_sun ,yd | 0.9144 m | yard ,

]

This may also be used with the with statement, to temporarily enable additional units:



>>> from astropy import units as u>>> from astropy.units import imperial>>> with imperial.enable():... u.m.find_equivalent_units()...

To enable just specific units, use add_enabled_units:

>>> from astropy import units as u>>> from astropy.units import imperial>>> with u.add_enabled_units_context([imperial.knot]):... u.m.find_equivalent_units()...

6.3.3 Combining and defining units

Units and quantities can be combined together using the regular Python numeric operators. For example:

>>> from astropy import units as u>>> fluxunit = u.erg / (u.cm ** 2 * u.s)>>> fluxunitUnit("erg / (cm2 s)")>>> 52.0 * fluxunit

>>> 52.0 * fluxunit / u.s

Units support fractional powers, which retain their precision through complex operations. To do this, it is recom-mended to use fractions.Fraction objects. For example:

>>> from astropy.utils.compat.fractions import Fraction>>> Franklin = u.g ** Fraction(1, 2) * u.cm ** Fraction(3, 2) * u.s ** -1

Note: Floating-point powers that are effectively the same as fractions with a denominator less than 10 are implicitlyconverted to Fraction objects under the hood. Therefore the following are equivalent:

>>> x = u.m ** Fraction(1, 3)>>> x.powers[Fraction(1, 3)]>>> x = u.m ** (1. / 3.)>>> x.powers[Fraction(1, 3)]

Users are free to define new units, either fundamental or compound using the def_unit function. For example:

>>> bakers_fortnight = u.def_unit('bakers_fortnight', 13 * u.day)

The addition of a string gives the new unit a name that will show up when the unit is printed.

Creating a new fundamental unit is simple:

>>> titter = u.def_unit('titter')>>> chuckle = u.def_unit('chuckle', 5 * titter)>>> laugh = u.def_unit('laugh', 4 * chuckle)>>> guffaw = u.def_unit('guffaw', 3 * laugh)>>> rofl = u.def_unit('rofl', 4 * guffaw)>>> death_by_laughing = u.def_unit('death_by_laughing', 10 * rofl)


http://docs.python.org/library/fractions.html#fractions.Fractionhttp://docs.python.org/library/fractions.html#fractions.Fraction


>>> rofl.to(titter, 1)240.0

By default, custom units are not searched by methods such as find_equivalent_units. However, they can beenabled by calling add_enabled_units:

>>> kmph = u.def_unit('kmph', u.km / u.h)>>> (u.m / u.s).find_equivalent_units()[]>>> u.add_enabled_units([kmph])

>>> (u.m / u.s).find_equivalent_units()Primary name | Unit definition | Aliases

[kmph | 0.277778 m / s | ,

]

6.3.4 Decomposing and composing units

Reducing a unit to its irreducible parts

A unit or quantity can be decomposed into its irreducibl

Documents

Astropy Documentation - Read the Docs · 5.3 Reference/API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22 6 Units and Quantities