././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1663951649.514253 ndcube-2.0.3/0000755000175100001710000000000014313361442012354 5ustar00runnerdocker././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1663951631.0 ndcube-2.0.3/.sunpy-template.yml0000644000175100001710000000072414313361417016151 0ustar00runnerdockerdefault_context: package_name: ndcube module_name: ndcube short_description: A package for multi-dimensional contiguious and non-contiguious coordinate aware arrays. author_name: The SunPy Community author_email: sunpy@googlegroups.com license: BSD 2-Clause project_url: http://docs.sunpy.org/projects/ndcube/ github_repo: sunpy/ndcube minimum_python_version: 3.7 use_compiled_extensions: n include_example_code: n _provide_setuppy_fallback: y ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1663951631.0 ndcube-2.0.3/CHANGELOG.rst0000644000175100001710000005174714313361417014415 0ustar00runnerdockerv2.0.3 (2022-09-23) =================== Bug Fixes --------- - Dynamically copy docstring and function signature from `NDCube.plotter.plot()` to `NDCube.plot()`. (`#534 `__) - Fixed a bug where the `plot_axes` key was not respected when passing `axes` to `plot` for 2D cubes. (`#551 `__) - Limit maximum reproject version to 0.9 due to API changes. ndcube 2.1 will support the new reproject keyword arguments. (`#564 `__) v2.0.2 (2022-05-10) =================== Bug Fixes --------- - Fix a bug in the ``NDCube._as_mpl_axes`` implementation, allowing cubes with compatible dimensions to be passed as the ``projection=`` keyword argument to certain matplotlib functions again. (`#509 `__) Trivial/Internal Changes ------------------------ - Remove use of deprecated ``distutils`` module. (`#520 `__) 2.0.1 (2021-11-19) ================== Bug Fixes --------- - Enable `~ndcube.NDCollection` to accept aligned axes inputs in any integer type. (`#495 `__) - Patch to convert quantity objects passed to ``crop_by_coords`` to the units given in the ``wcs.world_axis_units``. (`#497 `__) - Fix a bug which prevented the ``axes_units=`` kwarg from working when using the matplotlib animators. (`#498 `__) - Add support for length-1 lookup table coords within extra coords. (`#499 `__) - Bump the minimum version of astropy to 4.2 to correctly support capturing dropped world dimensions into global coords when slicing the WCS. (`#500 `__) 2.0.0 (2021-10-29) ================== Backwards Incompatible Changes ------------------------------ - Remove unused util functions and the ndcube WCS class. Refactor util functions for converting between between data and WCS indices to reflect the APE14 nomenclature that distinguishes between array, pixel and world axes. (`#280 `__) - NDCubeSequence animation axes can no longer be set by extra coords. (`#294 `__) - ImageAnimatorNDCubeSequence, ImageAnimatorCubeLikeNDCubeSequence, LineAnimatorNDCubeSequence and LineAnimatorCubeLikeNDCubeSequence have been removed and replaced by NDCubeSequenceAnimator. (`#294 `__) - Change type of output of `.NDCollection.aligned_world_axis_physical_types` from tuple to list. This is to be consistent with output of `astropy.wcs.WCS.world_axis_physical_types`. (`#302 `__) - Change output type when common axis item is a slice that covers only one subcube. Previously this would return an NDCube. Now an NDCubeSequence is always returned unless the common axis item is an integer. Also, refactor NDCubeSequence.index_as_cube so codebase is simpler. (`#311 `__) - Replace NDCube.crop_by_coords and NDCube.crop_by_extra_coords with new method, NDCube.crop (`#316 `__) - Remove NDCubeSequence plotting. (`#322 `__) - Update `.NDCube.array_axis_physical_types` return physical types from extra coords as well as the WCS. (`#338 `__) - Rename `.ExtraCoords.add` method from previous name "add_coordinate". (`#394 `__) - The `~.NDcube` object no longer inherits from `astropy.nddata.NDArithmeticMixin` as the methods were not coordinate aware. (`#457 `__) Deprecations and Removals ------------------------- - Remove `NDCube.pixel_to_world` and `NDCube.world_to_pixel`. (`#300 `__) - Remove ``world_axis_physical_types`` methods from `.NDCube` and `.NDCubeSequence`. (`#302 `__) - Remove NDCubeSequence.sequence_axis_extra_coords. This is replaced by NDCubeSequence.sequence_axis_coords. (`#335 `__) - Remove `ndcube.NDCubeSequence.common_axis_extra_coords`. Will be replaced by `ndcube.NDCubeSequence.common_axis_coords`. (`#344 `__) - Remove NDCollection.aligned_world_axis_physical_types. It will be replaced by `~ndcube.NDCollection.aligned_axis_physical_types`. (`#347 `__) Features -------- - Implement a new `.ExtraCoords` class which allows the specification of extra coordinates via lookup tables or WCS. This class exposes the extra coords as an APE 14 WCS object. (`#271 `__) - Add new method, `~ndcube.NDCube.axis_world_coord_values`, to return world coords for all pixels for all axes in WCS as quantity objects. (`#279 `__) - Added a new method `ndcube.NDCube.array_axis_physical_types` to show which physical types are associated with each array axis. (`#281 `__) - Add properties to NDCubeSequence giving the world physical types for each array axis. (`#301 `__) - Add as_mpl_axes method to NDCube plotting mixin so the an NDCube can be provided to astropy WCSAxes as a projection. (`#314 `__) - Make pyplot colorbar work with the output on NDCube.plot when it is a 2D image. (`#314 `__) - Introduce a new class, `~ndcube.global_coords.GlobalCoords`, for holding scalar coordinates that don't apply to any pixel axes. (`#323 `__) - Implement `.NDCube.world_axis_coords` which returns high level coordinate objects for all, or a subset of, axes. (`#327 `__) - New property, NDCubeSequence.sequence_axis_coords creates lists of GlobalCoords from each NDCube in the sequence. This replaces NDCubeSequence.sequence_axis_extra_coords, but because it uses the GlobaCoords infrastructure, can handle more than just coords that began as extra coords. (`#335 `__) - Implement `ndcube.NDCubeSequence.common_axis_coords` to replace `~ndcube.NDCubeSequence.common_axis_extra_coords`. In contrast to old property, this new property collates coordinates from the wcs as well as extra_coords. (`#344 `__) - New property, `ndcube.NDCollection.aligned_axis_physical_types`. This replaces `~ndcube.NDCollection.aligned_world_axis_physical_types` and returns a list of tuples, where each tuple gives the physical types common between all memebers of the collection for a given aligned axis. (`#347 `__) - Allow `ndcube.NDCubeSequence.explode_along_axis` to explode sequence along any axis, not just the common axis. (`#358 `__) - Plotting functionality on `NDCube` has been refactored to use pluggable "plotter" classes. All plotting functionality can now be accessed via the `.NDCube.plotter` attribute, with `.NDCube.plot` becoming an alias for `.NDCube.plotter.plot`. Advanced users, or package maintainers that which to customise the plotting functionality of an ``NDCube`` instance can set the ``.plotter`` attribute of a cube to be a subclass of `ndcube.visualization.BasePlotter` which then customises the behaviour of the ``NDCube.plot()`` method and provides any other methods implemented on the plotter. (`#401 `__) - Preserve sliced-out coordinates from WCS in the GlobalCoords instance. (`#402 `__) - Enable instantiating an NDCube from an existing NDCube by copying extra/global coords. (`#404 `__) - Support exposing dropped dimensions when `.ExtraCoords` is sliced. (`#411 `__) - `~ExtraCoords` is now explicitly limited to one dimensional tables because of a limitation in our use of `astropy.modeling`. (`#414 `__) - Adds functionality to reproject an `~.NDCube` object to coordinates described by another WCS or FITS Header by calling the new `~.NDCube.reproject_to` method. (`#434 `__) - Change the ``edges=`` keyword to ``pixel_corners=`` in `NDCube.axis_world_coords` and `NDCube.axis_world_coords_values` to make its meaning clearer based on SEP feedback. (`#437 `__) - `~.NDCube.axis_world_coords` and `~.NDCube.axis_world_coords_values` now use a different, substantially faster and more memory efficient algorithm to generate the coordinates along all axes. (`#442 `__) - Extends `~.NDCube.reproject_to` functionality by supporting ``adaptive`` and ``exact`` algorithms for an `~NDCube` with 2D celestial WCS. (`#448 `__) - Introduce optional offset between old and new pixel grids in `~ndcube.wcs.wrappers.resampled_wcs.ResampledLowLevelWCS`. (`#449 `__) - `.ExtraCoords.from_lookup_table` accepts (a seqence of) ``physical_types`` as kwarg to set the types of its ``lookup_tables``. (`#451 `__) - Create new plotter class for animating `~ndcube.NDCubeSequence` is the 2.0 framework. This class always sets the sequence axis as a slider and leverages `ndcube.NDCube.plot`. (`#456 `__) - Add ``__len__`` method to `~ndcube.NDCubeSequence` which makes ``len(sequence)`` return the number of cubes in the sequence. (`#464 `__) - Add ``__iter__`` method to `~ndcube.NDCubeSequence` which iterates through the cubes within the sequence. (`#465 `__) - Add property to `~ndcube.extra_coords.ExtraCoords` that returns a WCS of extra coords that describes all axes of associated cube. (`#472 `__) Bug Fixes --------- - Fix NDCollection.aligned_dimensions so it doesnt crash when components of collection are NDCubeSequences. (`#264 `__) - Generalize int type checking so it is independent of the bit-type of the OS. (`#269 `__) - Fix axis_world_coord_values when the WCS is 1D and ensure it always returns Quantities (`#287 `__) - Change name of NDCube.axis_world_coord_values to NDCube.axis_world_coords_values to be consistent with NDCube.axis_world_coords (`#293 `__) - Remove NDCubeSequence animation dependence of deprecated sunpy ImageAnimator and LineAnimator classes in favour of ArrayAnimatorWCS class. (`#294 `__) - Fix bug whereby common axis was not updated appropriately when slicing an NDCubeSequence. (`#310 `__) - Fix bug in NDCube.axis_world_coords_values when number of pixel and world dimensions differ. (`#319 `__) - Fixes bug in `~ndcube.utils.wcs.array_indices_for_world_objects` when the WCS input does not have a world_axis_object_components attribute. The fix causes the low_level_wcs version is tried before the code fails. This enables `ndcube.NDCube.combined_wcs` to be used with this function. (`#344 `__) - Fixes IndexError in `~ndcube.utils.wcs.array_indices_for_world_objects` which occurred when some of the world axes are dependent. (`#344 `__) - Stop `ndcube.NDCube.explode_along_axis` setting a common axis to the output `~ndcube.NDCubeSequence`. The output sequence should have no common axis. (`#358 `__) - Enable 2-D NDCubes to be visualized as a 1-D animated line. (`#381 `__) - Ensure corner inputs to `ndcube.NDCube.crop` are converted to units stored in WCS as `~astropy.wcs.WCS.world_to_array_index_values` does not handle units. (`#382 `__) - updated ndcube github repository link in `ndcube.docs.installation.rst`. (`#392 `__) - Fix bug in NDCube.axis_world_coords_values when axes_coords is initially a bare astropy coordinate object rather than a list/tuple of coordinate objects. (`#400 `__) - Change the implementation of `.NDCube.crop` so that it takes into account all the corners of the world region specified by the upper and lower corners, not just those two points. (`#438 `__) - Ensure `NDCube` init forces WCS to become high level. This patches a bug in astropy. (`#447 `__) - Fix bug in `~ndcube.NDCube.axis_world_coords_values` which caused the units to be stripped when an ``axes`` input was given. (`#461 `__) - Fix bug in `~ndcube.utils.wcs.get_dependent_world_axes` where an erroneous matrix transpose caused an error for non-square axis correlation matrices and wrong results for diagonally non-symmetric ones. (`#471 `__) - Extend support for cropping an `~ndcube.NDCube` using an `~ndcube.extra_coords.ExtraCoords` instance as the wcs. (`#472 `__) - Fix check as to whether user inputs to `ndcube.wcs.wrappers.CompoundLowLevelWCS.world_to_pixel_values` result in consistent pixel values when world dimensions share pixel dimensions. Previously this check was unreliable when non-trivial mapping between world and pixel dimensions was used. (`#472 `__) - Fix slicing `~ndcube.ExtraCoords` made of lookup tables. This bug meant that mapping of coords to arrays axes was not adjusted when an axis was dropped. (`#482 `__) Improved Documentation ---------------------- - Document accepted input to ``lookup_table`` in `.ExtraCoords` setting its ``physical_types``. (`#451 `__) - Improved information and formatting of ``__str__`` methods. (`#453 `__) Trivial/Internal Changes ------------------------ - Simplify and speed up implementation of NDCubeSequence slicing. (`#251 `__) - Fix docstring formatting to help docs build. (`#262 `__) - Use pytest-mpl for figure tests. (`#312 `__) - Port the tests for NDCube to use pytest fixtures (`#318 `__) - Allow corner inputs to `~ndcube.NDCube.crop` to not be wrapped in a `tuple` is only one high level coordinate objects required. (`#380 `__) - Make sunpy an optional dependence. Without it, the _animate_cube plotting functionality will be disabled. (`#393 `__) - Adds a function to compare the physical types of two WCS objects. (`#433 `__) - Propagate reference to NDCube object through `~ndcube.extra_coords.ExtraCoords` string slicing. (`#454 `__) - Adds a function to identify invariant axes between two WCS objects. (`#459 `__) - The matplotlib animators code has been moved from `sunpy` to a new package `mpl_animators` so ndcube no longer has an optional dependancy on sunpy. (`#484 `__) 1.3.0 (2020-03-27) ================== Features -------- - Add new NDCollection class for linking and manipulating partially or non-aligned NDCubes or NDCubeSequences. (`#238 `__) Bug Fixes --------- - Fixed the files included and excluded from the tarball. (`#212 `__) - Fix crashing bug when an NDCube axis after the first is sliced with a numpy.int64. (`#223 `__) - Raises error if NDCube is sliced with an Ellipsis. (`#224 `__) - Changes behavior of NDCubeSequence slicing. Previously, a slice item of interval length 1 would cause an NDCube object to be returned. Now an NDCubeSequence made up of 1 NDCube is returned. This is consistent with how interval length 1 slice items slice arrays. (`#241 `__) 1.2.0 (2019-09-10) ================== Features -------- - Changed all instances of "missing_axis" to "missing_axes" (`#157 `__) - Added a feature to get the pixel_edges from `ndcube.NDCube.axis_world_coords` (`#174 `__) Bug Fixes --------- - `ndcube.NDCube.world_axis_physical_types` now sets the axis label to the WCS CTYPE if no corresponding IVOA name can be found. (`#164 `__) - Fixed the bug of using `pixel_edges` instead of `pixel_values` in plotting (`#176 `__) - Fix 2D plotting from crashing when both data and WCS are 2D. (`#182 `__) - Fix the ability to pass a custom Axes to `ndcube.NDCube.plot` for a 2D cube. (`#204 `__) Trivial/Internal Changes ------------------------ - Include more helpful error when invalid item type is used to slice an `~ndcube.NDCube`. (`#158 `__) 1.1 === API-Breaking Changes -------------------- - `~ndcube.NDCubeBase.crop_by_extra_coord` API has been broken and replaced. Old version: ``crop_by_extra_coord(min_coord_value, interval_width, coord_name)``. New version: ``crop_by_extra_coord(coord_name, min_coord_value, max_coord_value)``. [#142] New Features ------------ - Created a new `~ndcube.NDCubeBase` which has all the functionality of `~ncube.NDCube` except the plotting. The old ``NDCubeBase`` which outlined the ``NDCube`` API was renamed ``NDCubeABC``. `~ndcube.NDCube` has all the same functionality as before except is now simply inherits from `~ndcube.NDCubeBase` and `~ndcube.mixins.plotting.NDCubePlotMixin`. [#101] - Moved NDCubSequence plotting to a new mixin class, NDCubSequencePlotMixin, making the plotting an optional extra. All the non-plotting functionality now lives in the NDCubeSequenceBase class. [#98] - Created a new `~ndcube.NDCubeBase.explode_along_axis` method that breaks an NDCube out into an NDCubeSequence along a chosen axis. It is equivalent to `~ndcube.NDCubeSequenceBase.explode_along_axis`. [#118] - NDCubeSequence plot mixin can now animate a cube as a 1-D line if a single axis number is supplied to plot_axis_indices kwarg. API Changes ----------- - Replaced API of what was previously ``utils.wcs.get_dependent_axes``, with two new functions, ``utils.wcs.get_dependent_data_axes`` and ``utils.wcs.get_dependent_wcs_axes``. This was inspired by a new implementation in ``glue-viz`` which is intended to be merged into ``astropy`` in the future. This API change helped fix the ``NDCube.world_axis_physical_type`` bug listed below. [#80] - Give users more control in plotting both for NDCubePlotMixin and NDCubeSequencePlotMixin. In most cases the axes coordinates, axes units, and data unit can be supplied manually or via supplying the name of an extra coordinate if it is wanted to describe an axis. In the case of NDCube, the old API is currently still supported by will be removed in future versions. [#98 #103] Bug Fixes --------- - Allowed `~ndcube.NDCubeBase.axis_world_coords` to accept negative axis indices as arguments. [#106] - Fixed bug in ``NDCube.crop_by_coords`` in case where real world coordinate system was rotated relative to pixel grid. [#113]. - `~ndcube.NDCubeBase.world_axis_physical_types` is now not case-sensitive to the CTYPE values in the WCS. [#109] - `~ndcube.NDCubeBase.plot` now generates a 1-D line animation when image_axis is an integer. 1.0.1 ===== New Features ------------ - Added installation instructions to docs. [#77] Bug Fixes --------- - Fixed bugs in ``NDCubeSequence`` slicing and ``NDCubeSequence.dimensions`` in cases where sub-cubes contain scalar ``.data``. [#79] - Fixed ``NDCube.world_axis_physical_types`` in cases where there is a ``missing`` WCS axis. [#80] - Fixed bugs in converting between negative data and WCS axis numbers. [#91] - Add installation instruction to docs. [#77] - Fix function name called within NDCubeSequence.plot animation update plot. [#95] ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1663951631.0 ndcube-2.0.3/LICENSE.rst0000644000175100001710000000241314313361417014172 0ustar00runnerdockerCopyright (c) 2019-2021, The SunPy Community Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1663951631.0 ndcube-2.0.3/MANIFEST.in0000644000175100001710000000105014313361417014110 0ustar00runnerdocker# Exclude specific files # All files which are tracked by git and not explicitly excluded here are included by setuptools_scm exclude .codecov.yaml exclude .mailmap exclude .editorconfig exclude .gitattributes exclude .gitignore exclude .pep8speaks.yml exclude .pre-commit-config.yaml exclude .test_package_pins.txt exclude azure-pipelines.yml exclude .readthedocs.yml # Prune folders prune .circleci prune .github prune changelog # This subpackage is only used in development checkouts and should not be included in built tarballs prune ndcube/_dev ././@PaxHeader0000000000000000000000000000003300000000000010211 xustar0027 mtime=1663951649.514253 ndcube-2.0.3/PKG-INFO0000644000175100001710000000773714313361442013467 0ustar00runnerdockerMetadata-Version: 2.1 Name: ndcube Version: 2.0.3 Summary: A package for multi-dimensional contiguious and non-contiguious coordinate aware arrays. Home-page: https://docs.sunpy.org/projects/ndcube/ Author: The SunPy Community Author-email: sunpy@googlegroups.com License: BSD 2-Clause Keywords: nddata,science,sun,wcs,gwcs,coordinates,sunpy,astropy,solar,spectroscopy Platform: any Classifier: Development Status :: 5 - Production/Stable Classifier: Intended Audience :: Science/Research Classifier: License :: OSI Approved :: BSD License Classifier: Natural Language :: English Classifier: Operating System :: OS Independent Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.7 Classifier: Programming Language :: Python :: 3.8 Classifier: Programming Language :: Python :: 3.9 Classifier: Topic :: Scientific/Engineering :: Physics Provides: ndcube Requires-Python: >=3.7 Description-Content-Type: text/x-rst Provides-Extra: tests Provides-Extra: docs Provides-Extra: plotting Provides-Extra: reproject Provides-Extra: all Provides-Extra: dev License-File: LICENSE.rst ****** ncdube ****** |Latest Version| |codecov| |matrix| |Powered by NumFOCUS| |Powered by SunPy| .. |Latest Version| image:: https://img.shields.io/pypi/v/ndcube.svg :target: https://pypi.python.org/pypi/ndcube/ :alt: It is up to date, we promise .. |matrix| image:: https://img.shields.io/matrix/ndcube:openastronomy.org.svg?colorB=%23FE7900&label=Chat&logo=matrix&server_fqdn=openastronomy.modular.im :target: https://openastronomy.element.io/#/room/#ndcube:openastronomy.org :alt: join us on #ndcube:openastronom.org on matrix .. |codecov| image:: https://codecov.io/gh/sunpy/sunpy/branch/main/graph/badge.svg :target: https://codecov.io/gh/sunpy/sunpy :alt: Best code cov this side of mars .. |Powered by NumFOCUS| image:: https://img.shields.io/badge/powered%20by-NumFOCUS-orange.svg?style=flat&colorA=E1523D&colorB=007D8A :target: https://numfocus.org :alt: Go give them money .. |Powered by SunPy| image:: http://img.shields.io/badge/powered%20by-SunPy-orange.svg?style=flat :target: http://www.sunpy.org :alt: SunPy ndcube is an open-source SunPy affiliated package for manipulating, inspecting and visualizing multi-dimensional contiguous and non-contiguous coordinate-aware data arrays. It combines data, uncertainties, units, metadata, masking, and coordinate transformations into classes with unified slicing and generic coordinate transformations and plotting/animation capabilities. It is designed to handle data of any number of dimensions and axis types (e.g. spatial, temporal, spectral, etc.) whose relationship between the array elements and the real world can be described by World Coordinate System (WCS) translations. Installation ============ For detailed installation instructions, see the `installation guide`_ in the ndcube docs. .. _installation guide: https://docs.sunpy.org/projects/ndcube/en/stable/installation.html Getting Help ============ For more information or to ask questions about ndcube, check out: - `ndcube Documentation`_ - `ndcube Element Channel`_ .. _ndcube Documentation: https://docs.sunpy.org/projects/ndcube/ .. _ndcube Element Channel: https://app.element.io/#/room/#sunpy:openastronomy.org Contributing ============ If you would like to get involved, check out the `Newcomers Guide`_ section of the SunPy docs. This shows how to get setup with a "sunpy" workflow but the same applies for ndcube, you will just need to replace sunpy with ndcube. Help is always welcome so let us know what you like to work on, or check out the `issues page`_ for the list of known outstanding items. .. _Newcomers Guide: https://docs.sunpy.org/en/latest/dev_guide/contents/newcomers.html .. _issues page: https://github.com/sunpy/ndcube/issues Code of Conduct =============== When you are interacting with the SunPy community you are asked to follow our `Code of Conduct`_. .. _Code of Conduct: https://sunpy.org/coc ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1663951631.0 ndcube-2.0.3/README.rst0000644000175100001710000000552614313361417014055 0ustar00runnerdocker****** ncdube ****** |Latest Version| |codecov| |matrix| |Powered by NumFOCUS| |Powered by SunPy| .. |Latest Version| image:: https://img.shields.io/pypi/v/ndcube.svg :target: https://pypi.python.org/pypi/ndcube/ :alt: It is up to date, we promise .. |matrix| image:: https://img.shields.io/matrix/ndcube:openastronomy.org.svg?colorB=%23FE7900&label=Chat&logo=matrix&server_fqdn=openastronomy.modular.im :target: https://openastronomy.element.io/#/room/#ndcube:openastronomy.org :alt: join us on #ndcube:openastronom.org on matrix .. |codecov| image:: https://codecov.io/gh/sunpy/sunpy/branch/main/graph/badge.svg :target: https://codecov.io/gh/sunpy/sunpy :alt: Best code cov this side of mars .. |Powered by NumFOCUS| image:: https://img.shields.io/badge/powered%20by-NumFOCUS-orange.svg?style=flat&colorA=E1523D&colorB=007D8A :target: https://numfocus.org :alt: Go give them money .. |Powered by SunPy| image:: http://img.shields.io/badge/powered%20by-SunPy-orange.svg?style=flat :target: http://www.sunpy.org :alt: SunPy ndcube is an open-source SunPy affiliated package for manipulating, inspecting and visualizing multi-dimensional contiguous and non-contiguous coordinate-aware data arrays. It combines data, uncertainties, units, metadata, masking, and coordinate transformations into classes with unified slicing and generic coordinate transformations and plotting/animation capabilities. It is designed to handle data of any number of dimensions and axis types (e.g. spatial, temporal, spectral, etc.) whose relationship between the array elements and the real world can be described by World Coordinate System (WCS) translations. Installation ============ For detailed installation instructions, see the `installation guide`_ in the ndcube docs. .. _installation guide: https://docs.sunpy.org/projects/ndcube/en/stable/installation.html Getting Help ============ For more information or to ask questions about ndcube, check out: - `ndcube Documentation`_ - `ndcube Element Channel`_ .. _ndcube Documentation: https://docs.sunpy.org/projects/ndcube/ .. _ndcube Element Channel: https://app.element.io/#/room/#sunpy:openastronomy.org Contributing ============ If you would like to get involved, check out the `Newcomers Guide`_ section of the SunPy docs. This shows how to get setup with a "sunpy" workflow but the same applies for ndcube, you will just need to replace sunpy with ndcube. Help is always welcome so let us know what you like to work on, or check out the `issues page`_ for the list of known outstanding items. .. _Newcomers Guide: https://docs.sunpy.org/en/latest/dev_guide/contents/newcomers.html .. _issues page: https://github.com/sunpy/ndcube/issues Code of Conduct =============== When you are interacting with the SunPy community you are asked to follow our `Code of Conduct`_. .. _Code of Conduct: https://sunpy.org/coc ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1663951631.0 ndcube-2.0.3/RELEASE.rst0000644000175100001710000000150414313361417014170 0ustar00runnerdockerThe SunPy project is very happy to announce the 2.0 release of "ndcube"! This release of ndcube contains 912 commits in 38 merged pull requests closing 56 issues from 12 people, 6 of which are first-time contributors to ndcube. The people who have contributed to the code for this release are: - Adwait Bhope * - Daniel Ryan - David Stansby - Derek Homeier * - Dr Matthieu Wes * - Kris Stern * - Kritika Ranjan * - Laura Hayes - Nabil Freij - Ricky O'Steen * - Stuart Mumford - Yash Sharma Where a * indicates that this release contains their first contribution to ndcube. For more information about ndcube see the `documentation `__. ndcube can be installed from pip or conda using the following commands:: $ conda install -c conda-forge ndcube $ pip install ndcube ././@PaxHeader0000000000000000000000000000003400000000000010212 xustar0028 mtime=1663951649.5022528 ndcube-2.0.3/docs/0000755000175100001710000000000014313361442013304 5ustar00runnerdocker././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1663951631.0 ndcube-2.0.3/docs/Makefile0000644000175100001710000000117214313361417014747 0ustar00runnerdocker# Minimal makefile for Sphinx documentation # # You can set these variables from the command line, and also # from the environment for the first two. SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build SOURCEDIR = . BUILDDIR = _build # Put it first so that "make" without argument is like "make help". help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) .PHONY: help Makefile # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1663951631.0 ndcube-2.0.3/docs/api.rst0000644000175100001710000000100214313361417014602 0ustar00runnerdocker.. _api: API Reference ============= .. automodapi:: ndcube :inherited-members: .. automodapi:: ndcube.extra_coords.table_coord :headings: ^# .. automodapi:: ndcube.mixins .. automodapi:: ndcube.visualization .. automodapi:: ndcube.visualization.mpl_plotter :headings: ^# .. automodapi:: ndcube.utils .. automodapi:: ndcube.utils.sequence :headings: ^# .. automodapi:: ndcube.utils.wcs :headings: ^# .. automodapi:: ndcube.utils.misc :headings: ^# .. automodapi:: ndcube.tests.helpers ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1663951631.0 ndcube-2.0.3/docs/conf.py0000644000175100001710000000632014313361417014606 0ustar00runnerdocker# # Configuration file for the Sphinx documentation builder. # -- Project information ----------------------------------------------------- project = 'ndcube' copyright = '2021, The SunPy Community' author = 'The SunPy Community' # The full version, including alpha/beta/rc tags from ndcube import __version__ release = __version__ is_development = '.dev' in __version__ # -- General configuration --------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ 'matplotlib.sphinxext.plot_directive', 'sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.inheritance_diagram', 'sphinx.ext.viewcode', 'sphinx.ext.napoleon', 'sphinx.ext.doctest', 'sphinx.ext.mathjax', 'sphinx_automodapi.automodapi', 'sphinx_automodapi.smart_resolver', 'ndcube.utils.sphinx.code_context', 'sphinx_changelog', 'pytest_doctestplus.sphinx.doctestplus', ] # Define code to be run by doctest in front of every code block. # Add any paths that contain templates here, relative to this directory. # templates_path = ['_templates'] # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: source_suffix = '.rst' # The master toctree document. master_doc = 'index' # The reST default role (used for this markup: `text`) to use for all # documents. Set to the "smart" one. default_role = 'obj' # -- Options for intersphinx extension --------------------------------------- # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { 'python': ('https://docs.python.org/3/', (None, 'http://data.astropy.org/intersphinx/python3.inv')), 'numpy': ('https://docs.scipy.org/doc/numpy/', (None, 'http://data.astropy.org/intersphinx/numpy.inv')), 'matplotlib': ('https://matplotlib.org/', (None, 'http://data.astropy.org/intersphinx/matplotlib.inv')), 'astropy': ('http://docs.astropy.org/en/stable/', None), 'sunpy': ('https://docs.sunpy.org/en/stable/', None), 'mpl_animators': ('https://docs.sunpy.org/projects/mpl-animators/en/stable/', None), 'gwcs': ('https://gwcs.readthedocs.io/en/stable/', None)} # -- Options for HTML output ------------------------------------------------- # Load the theme config from the theme package from sunpy_sphinx_theme.conf import * # Use the ndcube logo rather than the sunpy one html_logo = png_icon = 'logo/ndcube.png' html_favicon = 'logo/favicon.png' # Render inheritance diagrams in SVG graphviz_output_format = 'svg' graphviz_dot_args = [ '-Nfontsize=10', '-Nfontname=Helvetica Neue, Helvetica, Arial, sans-serif', '-Efontsize=10', '-Efontname=Helvetica Neue, Helvetica, Arial, sans-serif', '-Gfontsize=10', '-Gfontname=Helvetica Neue, Helvetica, Arial, sans-serif' ] ././@PaxHeader0000000000000000000000000000002600000000000010213 xustar0022 mtime=1663951631.0 ndcube-2.0.3/docs/coordinates.rst0000644000175100001710000006052114313361417016356 0ustar00runnerdocker.. _coordinates: ========================== Coordinate Transformations ========================== Introduction to WCS =================== To describe the mapping between array elements/pixels and real world coordinates, ndcube heavily leverages the World Coordinate System (WCS) framework, specifically the tools written by Astropy that implement this framework in Python. WCS allows a wide variety of projections, rotations and transformations be stored and executed. Because it allows coordinates transformations to be stored functionally, rather than in memory-heavy lookup tables, and because it caters for both astronomy-specific coordinate systems (e.g. RA & Dec.) as well as simpler, more common ones (e.g. wavelength), WCS has become the most common coordinate transformation framework in astronomy. The most commonly used WCS implementation in Python is the `astropy.wcs.WCS` object, which stores critical information describing the coordinate transformations as required by the FITS data model (e.g. the reference pixel and its corresponding coordinate values, ``CRPIX`` and ``CRVAL``, and the projection type, ``CTYPE`` etc.). It also executes these transformations via methods like `~astropy.wcs.WCS.world_to_pixel` and `~astropy.wcs.WCS.pixel_to_world` which convert between pixel indices and world coordinate values. However, these methods are independent of the data array and the `~astropy.wcs.WCS` object carries little or no information about the data itself. That is why the ndcube package is needed. Nonetheless, astropy's WCS implementation is a crucial pillar of ndcube, as is the more generalized offshoot, `gWCS `__, which provides greater generalization outside of the FITS data model. Crucially though for ndcube, both implementations adhere to the `Astropy WCS API `__. A familiarity with WCS and the Astropy and gWCS Python implementations will be helpful (although hopefully not essential) in understanding this guide. We therefore encourage users to read `Astropy's WCS guide `__ and the `gWCS documentation `__ to learn more. In this section we will discuss the features ndcube has built upon these implementations to support the integration of data and coordinates. NDCube Coordinates ================== Although WCS objects are a powerful and concise way of storing complex functional coordinate transformations, their API can be cumbersome when the coordinates along a whole axis are desired. Making this process easy and intuitive is the purpose of the `ndcube.NDCube.axis_world_coords` method. Using the attached WCS object, information on the data dimensions, and optional inputs from the user, this method returns high level coordinate objects --- e.g. `~astropy.coordinates.SkyCoord`, `~astropy.time.Time`, `~astropy.coordinates.SpectralCoord`, `~astropy.units.Quantity` --- containing the coordinates for each array element. Say we have a 3-D `~ndcube.NDCube` with a shape of ``(4, 4, 5)`` and physical types of space, space, wavelength. Now let's say we want the wavelength values along the spectral axis. We can do this in a couple ways. First we can provide `~ndcube.NDCube.axis_world_coords` with the array axis number of the spectral axis. .. expanding-code-block:: python :summary: Click to reveal/hide instantiation of the NDCube. >>> import astropy.wcs >>> import numpy as np >>> from ndcube import NDCube >>> # Define data array. >>> data = np.random.rand(4, 4, 5) >>> # Define WCS transformations in an astropy WCS object. >>> wcs = astropy.wcs.WCS(naxis=3) >>> wcs.wcs.ctype = 'WAVE', 'HPLT-TAN', 'HPLN-TAN' >>> wcs.wcs.cunit = 'Angstrom', 'deg', 'deg' >>> wcs.wcs.cdelt = 0.2, 0.5, 0.4 >>> wcs.wcs.crpix = 0, 2, 2 >>> wcs.wcs.crval = 10, 0.5, 1 >>> # Now instantiate the NDCube >>> my_cube = NDCube(data, wcs=wcs) .. code-block:: python >>> my_cube.axis_world_coords(2) (,) Alternatively we can provide a unique substring of the physical type of the coordinate, stored in `ndcube.NDCube.wcs.world_axis_physical_types`: .. code-block:: python >>> my_cube.wcs.world_axis_physical_types ['em.wl', 'custom:pos.helioprojective.lat', 'custom:pos.helioprojective.lon'] >>> # Since 'wl' is unique to the wavelength axis name, let's use that. >>> my_cube.axis_world_coords('wl') (,) As discussed above, some WCS axes are not independent. For those axes, `~ndcube.NDCube.axis_world_coords` returns objects with the same number of dimensions as dependent axes. For example, helioprojective longitude and latitude are dependent. Therefore if we ask for longitude, we will get back a `~astropy.coordinates.SkyCoord` containing 2-D latitude and longitude arrays with the same shape as the array axes to which they correspond. For example: .. code-block:: python >>> celestial = my_cube.axis_world_coords('lon')[0] # Must extract object from returned tuple with [0] >>> my_cube.dimensions >>> celestial.shape (4, 4) >>> celestial It is also possible to request more than one axis's world coordinates by setting ``axes`` to an iterable of data axis number and/or axis type strings. The coordinate objects are returned in world axis order. .. code-block:: python >>> my_cube.axis_world_coords(2, 'lon') (, ) If the user wants the world coordinates for all the axes, the ``axes`` arg can set to ``None`` or simply omitted. .. code-block:: python >>> my_cube.axis_world_coords() (, ) By default `~ndcube.NDCube.axis_world_coords` returns the coordinates at the center of each pixel. However, the coordinates at the edges of each pixel can be obtained by setting the ``pixel_corners`` kwarg to ``True``. For example: .. code-block:: python >>> my_cube.axis_world_coords(pixel_corners=True) (, ) Working with Raw Coordinates ---------------------------- If users would prefer not to deal with high level coordinate objects, they can elect to use `ndcube.NDCube.axis_world_coords_values`. The API for this method is the same as `~ndcube.NDCube.axis_world_coords`. The only difference is that a `~collections.namedtuple` of `~astropy.units.Quantity` objects are returned, one for each physical type requested. In the above case this means that there would be separate `~astropy.units.Quantity` objects for latitude and longitude, but they would both have the same 2-D shape. The `~astropy.units.Quantity` objects are returned in world order and correspond to the physical types in the `astropy.wcs.WCS.world_axis_physical_types`. The `~astropy.units.Quantity` objects do not contain important contextual information, such as reference frame, which is needed to fully interpret the coordinate values. However for some use cases this level of completeness is not needed. .. code-block:: python >>> my_cube.axis_world_coords_values() CoordValues(custom_pos_helioprojective_lon=, custom_pos_helioprojective_lat=, em_wl=) .. _extra_coords: ExtraCoords =========== So far we have seen how `~ndcube.NDCube` uses its WCS object (``NDCube.wcs``) to store and perform coordinates transformations. But what if we have alternative or additional coordinates that are not represented by the WCS? For example, say we have a raster scan from a scanning slit spectrograph whose x-axis is folded in with time. This occurs because the x-axis is built up over sequential exposures taken at different slit positions. Our ``NDCube.wcs`` might describe latitude and longitude, but omit time. So how can we represent time without having to construct a whole new custom WCS object? One way is to use the `ndcube.ExtraCoords` class located at ``NDCube.extra_coords``. It provides a mechanism of attaching coordinates to `~ndcube.NDCube` instances in addition to those in the primary WCS object. This may be desired because, as above, the primary WCS omits a physical type. Or it may be that the users have an alternative set of coordinates to the primary set at ``.wcs``. To demonstrate how to use `~ndcube.ExtraCoords`, let's start by creating a `~astropy.time.Time` object representing the time at each location along the first axis of ``my_cube``. .. code-block:: python >>> from astropy.time import Time, TimeDelta >>> base_time = Time('2000-01-01', format='fits', scale='utc') >>> timestamps = Time([base_time + TimeDelta(60 * i, format='sec') for i in range(data.shape[0])]) By default an `~ndcube.NDCube` is instantiated with an empty `~ndcube.ExtraCoords` object. So let's add a time coordinate to the `~ndcube.ExtraCoords` instance at ``my_cube.extra_coords``. To do this we need to supply the physical type of the coordinate, the array axis to which is corresponds, and the values of the coordinate. The number of values should equal the axis's length (or shape if it corresponds to more than one axis) and the physical type must be a valid `IVOA UCD1+ controlled words `__ word. If one does not exist for your coordinate, prepend the type with ``custom:``. .. code-block:: python >>> my_cube.extra_coords.add('time', (0,), timestamps) An indefinite number of coordinates can be added in this way. The names of the coordinates can be accessed via the `~ndcube.ExtraCoords.keys` method. .. code-block:: python >>> my_cube.extra_coords.keys() ('time',) The physical types of extra coordinates are also returned by `~ndcube.NDCube.array_axis_physical_types`. .. code-block:: python >>> my_cube.array_axis_physical_types [('custom:pos.helioprojective.lat', 'custom:pos.helioprojective.lon', 'time'), ('custom:pos.helioprojective.lat', 'custom:pos.helioprojective.lon'), ('em.wl',)] The values of the extra coordinates at each array index can be retrieved using and combination of `ndcube.NDCube.axis_world_coords` and `ndcube.NDCube.combined_wcs`. See :ref:`combined_wcs` below. .. _combined_wcs: Combined WCS ------------ The `~ndcube.NDCube.combined_wcs` generates a WCS that combines the extra coords with those stored in the primary WCS. Unlike `ndcube.ExtraCoords.wcs`, `~ndcube.NDCube.combined_wcs` is a valid WCS for describing the `~ndcube.NDCube` data array and so can be used with the `~ndcube.NDCube` coordinate transformation and plotting features, e.g: .. code-block:: python >>> my_cube.axis_world_coords(wcs=my_cube.combined_wcs) (, ,