API Documentation

• load(filename) loads the contents of a formatted file, trying to infer the format from filename and/or magic bytes in the file (see query).
• load(strm) loads from an IOStream or similar object. In this case, there is no filename extension, so we rely on the magic bytes for format identification.
• load(File{format"PNG"}(filename)) specifies the format directly, and bypasses the format query.
• load(Stream{format"PNG"}(io)) specifies the format directly, and bypasses the format query.
• load(f; options...) passes keyword arguments on to the loader.

• save(filename, data...) saves the contents of a formatted file, trying to infer the format from filename.
• save(Stream{format"PNG"}(io), data...) specifies the format directly, and bypasses the format query.
• save(File{format"PNG"}(filename), data...) specifies the format directly, and bypasses the format query.
• save(f, data...; options...) passes keyword arguments on to the saver.

query(filename; checkfile=true)

Return a File object with information about the format inferred from the file's extension and/or magic bytes. If filename already exists, the file's magic bytes will take priority unless checkfile is false.

query(io, [filename]) returns a Stream object with information about the format inferred from the magic bytes.

AstroImage

Provides access to a FITS image along with its accompanying header and WCS information, if applicable.

imview(img; clims=Percent(99.5), stretch=identity, cmap=:magma, contrast=1.0, bias=0.5)

Create a read only view of an array or AstroImageMat mapping its data values to Colors according to clims, stretch, and cmap.

The data is first clamped to clims, which can either be a tuple of (min, max) values or a function accepting an iterator of pixel values that returns (min, max). By default, clims=Percent(99.5) which sets the display min and max to the central 99.5 percentile range of pixel values. Convenient functions to use for clims are: extrema, Zscale, and Percent(p)

Next, the data is rescaled to [0,1] and remapped according to the function stretch. Stretch can be any monotonic fuction mapping values in the range [0,1] to some range [a,b]. Note that log(0) is not defined so is not directly supported. For a list of convenient stretch functions, see: logstretch, powstretch, squarestretch, asinhstretch, sinhstretch, powerdiststretch

Finally the data is mapped to RGB values according to cmap. If cmap is nothing, grayscale is used. ColorSchemes.jl defines hundreds of colormaps. A few nice ones for images include: :viridis, :magma, :plasma, :thermal, and :turbo.

Crucially, this function returns a view over the underlying data. If img is updated then those changes will be reflected by this view with the exception of clims which is not recalculated.

Note: if clims or stretch is a function, the pixel values passed in are first filtered to remove non-finite or missing values.

Defaults

The default values of clims, stretch, and cmap are extrema, identity, and nothing respectively. You may alter these defaults using AstroImages.set_clims!, AstroImages.set_stretch!, and AstroImages.set_cmap!.

Automatic Display

Arrays wrapped by AstroImageMat() get displayed as images automatically by calling imview on them with the default settings when using displays that support showing PNG images.

Missing data

Pixels that are NaN or missing will be displayed as transparent when cmap is set or black if. +/- Inf will be displayed as black or white respectively.

Exporting Images

The view returned by imview can be saved using general FileIO.save methods. Example:

v = imview(data, cmap=:magma, stretch=asinhstretch, clims=Percent(95))
save("output.png", v)

imview(img::AbstractArray{<:Complex}; ...)

When applied to an image with complex values, display the magnitude of the pixels using imview and display the phase angle as a panel below using a cyclical color map. For more customatization, you can create a view like this yourself:

vcat(
    imview(abs.(img)),
    imview(angle.(img)),
)

implot(
    img::AbstractArray;
    clims=Percent(99.5),
    stretch=identity,
    cmap=:magma,
    bias=0.5,
    contrast=1,
    wcsticks=true,
    grid=true,
    platescale=1
)

Create a read only view of an array or AstroImageMat mapping its data values to an array of Colors. Equivalent to:

implot(
    imview(
        img::AbstractArray;
        clims=Percent(99.5),
        stretch=identity,
        cmap=:magma,
        bias=0.5,
        contrast=1,
    ),
    wcsn=1,
    wcsticks=true,
    wcstitle=true,
    grid=true,
    platescale=1
)

Image Rendering

See imview for how data is mapped to RGBA pixel values.

WCS & Image Coordinates

If provided with an AstroImage that has WCS headers set, the tick marks and plot grid are calculated using WCS.jl. By default, use the first WCS coordinate system. The underlying pixel coordinates are those returned by dims(img) multiplied by platescale. This allows you to overplot lines, regions, etc. using pixel coordinates. If you wish to compute the pixel coordinate of a point in world coordinates, see world_to_pix.

• wcsn (default 1) select which WCS transform in the headers to use for ticks & grid
• wcsticks (default true if WCS headers present) display ticks and labels, and title using world coordinates
• wcstitle (default true if WCS headers present and length(refdims(img))>0). When slicing a cube, display the location along unseen axes in world coordinates instead of pixel coordinates.
• grid (default true) show a grid over the plot. Uses WCS coordinates if wcsticks is true, otherwise pixel coordinates multiplied by platescale.
• platescale (default 1). Scales the underlying pixel coordinates to ease overplotting, etc. If wcsticks is false, the displayed pixel coordinates are also scaled.

Defaults

The default values of clims, stretch, and cmap are extrema, identity, and nothing respectively. You may alter these defaults using AstroImages.set_clims!, AstroImages.set_stretch!, and AstroImages.set_cmap!.

Index for accessing a comment associated with a header keyword or COMMENT entry.

Example:

img = AstroImage(randn(10,10))
img["ABC"] = 1
img["ABC", Comment] = "A comment describing this key"

push!(img, Comment, "The purpose of this file is to demonstrate comments")
img[Comment] # ["The purpose of this file is to demonstrate comments"]

Allows accessing and setting HISTORY header entries

img = AstroImage(randn(10,10))
push!(img, History, "2023-04-19: Added history entry.")
img[History] # ["2023-04-19: Added history entry."]

pix_to_world(wcs, pixcoords)

Convert the array of pixel coordinates pixcoords to world coordinates according to the WCSTransform wcs. pixcoords should be a 2-d array where "pixcoords[:, i]" is the i-th set of coordinates, or a 1-d array representing a single set of coordinates.

The return value is the same shape as pixcoords.

pix_to_world(img::AstroImage, pixcoords; all=false)

Given an astro image, look up the world coordinates of the pixels given by pixcoords. World coordinates are resolved using WCS.jl and a WCSTransform calculated from any FITS header present in img. If no WCS information is in the header, or the axes are all linear, this will just return pixel coordinates.

pixcoords should be the coordinates in your current selection of the image. For example, if you select a slice like this:

julia> cube = load("some-3d-cube.fits")
julia> slice = cube[10:20, 30:40, 5]

Then to look up the coordinates of the pixel in the bottom left corner of slice, run:

julia> world_coords = pix_to_world(img, [1, 1])
[10, 30]

If WCS information was present in the header of cube, then those coordinates would be resolved using axis 1, 2, and 3 respectively.

To include world coordinates in all axes, pass all=true

julia> world_coords = pix_to_world(img, [1, 1], all=true)
[10, 30, 5]

!! Coordinates must be provided in the order of dims(img). If you transpose an image, the order you pass the coordinates should not change.

world_to_pix(wcs, worldcoords)

Convert the array of world coordinates worldcoords to pixel coordinates according to the WCSTransform wcs. worldcoords is a 2-d array where "worldcoords[:, i]" is the i-th set of coordinates, or a 1-d array representing a single set of coordinates.

The return value is the same size as worldcoords.

X <: XDim

X(val=:)

X Dimension. X <: XDim <: IndependentDim

Examples

xdim = X(2:2:10)

val = A[X(1)]

mean(A; dims=X)

Y <: YDim

Y(val=:)

Y Dimension. Y <: YDim <: DependentDim

Examples

ydim = Y(['a', 'b', 'c'])

val = A[Y(1)]

mean(A; dims=Y)

Z <: ZDim

Z(val=:)

Z Dimension. Z <: ZDim <: Dimension

Example:

zdim = Z(10:10:100)

val = A[Z(1)]

mean(A; dims=Z)

Dim{S}(val=:)

A generic dimension. For use when custom dims are required when loading data from a file. Can be used as keyword arguments for indexing.

Dimension types take precedence over same named Dim types when indexing with symbols, or e.g. creating Tables.jl keys.

julia> dim = Dim{:custom}(['a', 'b', 'c'])
custom ['a', 'b', 'c']

At <: IntSelector

At(x, atol, rtol)
At(x; atol=nothing, rtol=nothing)

Selector that exactly matches the value on the passed-in dimensions, or throws an error. For ranges and arrays, every intermediate value must match an existing value - not just the end points.

x can be any value or Vector of values.

atol and rtol are passed to isapprox. For Number rtol will be set to Base.rtoldefault, otherwise nothing, and wont be used.

Example

using DimensionalData

A = DimArray([1 2 3; 4 5 6], (X(10:10:20), Y(5:7)))
A[X(At(20)), Y(At(6))]

# output

5

Near <: IntSelector

Near(x)

Selector that selects the nearest index to x.

With Points this is simply the index values nearest to the x, however with Intervals it is the interval center nearest to x. This will be offset from the index value for Start and End locus.

Example

using DimensionalData

A = DimArray([1 2 3; 4 5 6], (X(10:10:20), Y(5:7)))
A[X(Near(23)), Y(Near(5.1))]

# output
4

dims(x, query) => Tuple{Vararg{Dimension}}
dims(x, query...) => Tuple{Vararg{Dimension}}

Get the dimension(s) matching the type(s) of the query dimension.

Lookup can be an Int or an Dimension, or a tuple containing any combination of either.

Arguments

• x: any object with a dims method, or a Tuple of Dimension.
• query: Tuple or a single Dimension or Dimension Type.

Example

julia> using DimensionalData

julia> A = DimArray(ones(2, 3, 2), (X, Y, Z))
╭───────────────────────────╮
│ 2×3×2 DimArray{Float64,3} │
├───────────────────── dims ┤
  ↓ X, → Y, ↗ Z
└───────────────────────────┘
[:, :, 1]
 1.0  1.0  1.0
 1.0  1.0  1.0

julia> dims(A, (X, Y))
↓ X, → Y

dims(x, [dims::Tuple]) => Tuple{Vararg{Dimension}}
dims(x, dim) => Dimension

Return a tuple of Dimensions for an object, in the order that matches the axes or columns of the underlying data.

dims can be Dimension, Dimension types, or Symbols for Dim{Symbol}.

The default is to return nothing.

refdims(x, [dims::Tuple]) => Tuple{Vararg{Dimension}}
refdims(x, dim) => Dimension

Reference dimensions for an array that is a slice or view of another array with more dimensions.

slicedims(a, dims) returns a tuple containing the current new dimensions and the new reference dimensions. Refdims can be stored in a field or discarded, as it is mostly to give context to plots. Ignoring refdims will simply leave some captions empty.

The default is to return an empty Tuple ().

header(img::AstroImage)

Return the underlying FITSIO.FITSHeader object wrapped by an AstroImage. Note that this object has less flexible getindex and setindex methods. Indexing by symbol, Comment, History, etc are not supported.

header(array::AbstractArray)

Returns an empty FITSIO.FITSHeader object when called with a non-AstroImage abstract array.

wcs(img)

Computes and returns a list of World Coordinate System WCSTransform objects from WCS.jl. The resultss are cached after the first call, so subsequent calls are fast. Modifying a WCS header invalidates this cache automatically, so users should call wcs(...) each time rather than keeping the WCSTransform object around.

wcs(img, index)

Computes and returns a World Coordinate System WCSTransform objects from WCS.jl by index. This is to support files with multiple WCS transforms specified. wcs(img,1) is useful for selecting selecting the first WCSTranform object. The resultss are cached after the first call, so subsequent calls are fast. Modifying a WCS header invalidates this cache automatically, so users should call wcs(...) each time rather than keeping the WCSTransform object around.

wcs(array)

Returns a list with a single basic WCSTransform object when called with a non-AstroImage abstract array.

WCSGrid(img::AstroImageMat, ax=(1,2), coords=(first(axes(img,ax[1])),first(axes(img,ax[2]))))

Given an AstroImageMat, return information necessary to plot WCS gridlines in physical coordinates against the image's pixel coordinates. This function has to work on both plotted axes at once to handle rotation and general curvature of the WCS grid projected on the image coordinates.

composecolors(
    images,
    cmap=["#F00", "#0F0", "#00F"];
    clims,
    stretch,
    contrast,
    bias,
    multiplier
)

Create a color composite of multiple images by applying imview and blending the results. This function can be used to create RGB composites using any number of channels (e.g. red, green, blue, and hydrogen alpha) as well as more exotic images like blending radio and optical data using two different colormaps.

cmap should be a list of colorants, named colors (see Colors.jl), or colorschemes (see ColorSchemes.jl). clims, stretch, contrast, and bias are passed on to imview. They can be a single value or a list of different values for each image.

The headers of the returned image are copied from the first image.

Examples:

# Basic RGB
composecolors([redimage, greenimage, blueimage])
# Non-linear stretch before blending
composecolors([redimage, greenimage, blueimage], stretch=asinhstretch)
# More than three channels are allowed (H alpha in pink)
composecolors(
    [antred, antgreen, antblue, anthalp],
    ["red", "green", "blue", "maroon1"],
    multiplier=[1,2,1,1]
)
# Can mix
composecolors([radioimage, xrayimage], [:ice, :magma], clims=extrema)
composecolors([radioimage, xrayimage], [:magma, :viridis], clims=[Percent(99), Zscale()])

Zscale(options)(data)

Wraps PlotUtils.zscale in a callable with default parameters. This is a common algorithm for agressively stretching astronomical data to see faint structure that originated in IRAF: https://iraf.net/forum/viewtopic.php?showtopic=134139 but is now seen in many other applications/libraries (DS9, Astropy, etc.)

Usage:

imview(img, clims=Zscale())
implot(img, clims=Zscale(contrast=0.1))

Default parameters:

nsamples::Int=1000
contrast::Float64=0.25
max_reject::Float64=0.5
min_npixels::Float64=5
k_rej::Float64=2.5
max_iterations::Int=5

Percent(99.5)

Returns a callable that calculates display limits that include the given percent of the image data. Reproduces the behaviour of the SAO DS9 scale menu.

Example:

julia> imview(img, clims=Percent(90))

This will set the limits to be the 5th percentile to the 95th percentile.

logstretch(num,a=1000)

A log-stretch as defined by the SAO DS9 application: http://ds9.si.edu/doc/ref/how.html

powstretch(num, a=1000)

A power-stretch as defined by the SAO DS9 application: http://ds9.si.edu/doc/ref/how.html

sqrtstretch(num)

A square root stretch (simply defined as Base.sqrt)

squarestretch(num)

A squarestretch-stretch as defined by the SAO DS9 application: http://ds9.si.edu/doc/ref/how.html

asinhstretch(num)

A hyperbolic arcsin stretch as defined by the SAO DS9 application: http://ds9.si.edu/doc/ref/how.html

sinhstretch(num)

A hyperbolic sin stretch as defined by the SAO DS9 application: http://ds9.si.edu/doc/ref/how.html

powerdiststretch(num, a=1000)

A power distance stretch as defined by astropy.

copyheader(img::AstroImage, data) -> imgnew

Create a new image copying the header of img but using the data of the AbstractArray data. Note that changing the header of imgnew does not affect the header of img. See also: shareheader.

shareheader(img::AstroImage, data) -> imgnew

Create a new image reusing the header dictionary of img but using the data of the AbstractArray data. The two images have synchronized header; modifying one also affects the other. See also: copyheader.

recenter(img::AstroImage)
recenter(img::AstroImage, newcentx, newcenty, ...)

Adjust the dimensions of an AstroImage so that they are centered on the pixel locations given by newcentx, .. etc. This does not affect the underlying array, it just updates the dimensions associated with it by the AstroImage. If no newcent arguments are provided, center the image in all dimensions to the middle pixel (or fractional pixel).

Example:

a = AstroImage(randn(11,11))
a[1,1] # Bottom left
a[At(1),At(1)] # Bottom left
r = recenter(a, 6, 6)
r[1,1] # Still bottom left
r[At(1),At(1)] # Center pixel