=========================
An Introduction to ndcube
=========================

N-dimensional Data in Astronomy
-------------------------------
N-dimensional data sets are common in all areas of science and beyond.  For example, a series of images taken sequentially with a CCD camera can be stored as a single 3-D array with two spatial axes and one temporal axis.  Each array-element can represent a pixel and the value in that array-element can represent the reading in that pixel at a given time.  In astronomy, the relationship between the pixel coordinate and the location and time in the Universe being observed is often represented by a World Coordinate System (WCS) transformation described by a set of well-defined parameters with standarized names.  This, coupled with WCS's ability to handle many different types (e.g. spatial, temporal, spectral, etc.) of transformations make it a succinct, standard and powerful way to relate pixels from an observation or cells in a simulation grid to the location in the Universe to which they correspond.  Due of the prevalence of N-D data and the importance of the transformations, there exist mature scientific Python packages (e.g. numpy and astropy) that contain powerful tools to handle N-D arrays and WCS transformations.

What is ndcube?
---------------
ndcube is a free, open-source, community-developed Python package whose purpose is to combine the above-mentioned functionalities for handling N-D arrays and WCS coordinate transformations into a single package of objects.  These objects provide unified slicing, visualization, coordinate conversion and inspection of the data, WCS transformations and metadata.  ndcube does this in a way that is not specific to any number or physical type of axis, and so can in principle be used for any type of data (e.g. images, spectra, timeseries, etc.) so long as the data are represented by an array and a set of WCS transformations.  This makes ndcube ideal to subclass when creating classes for specific types of data, while keeping the non-data-specific functionalities (e.g. slicing) common between classes.

The ndcube package is composed of two basic classes: `~ndcube.NDCube` and `~ndcube.NDCubeSequence`.  The former is for managing a single array and set of WCS transformations, while the latter is for handling multiple arrays, each described by their own set of WCS transformations.  They share similar APIs to enable the user to think more about their data in an intuitive way, rather than focusing on the format in which that data happens to be stored.  The functionality of these classes in outlined in detail in the :ref:`ndcube` and :ref:`ndcubesequence` sections of this guide.
