Getting Started

General

AstroPack is a general-purpose package for astronomy & astrophysics using MATLAB. AstroPack contains a large number of classes and functions image analysis, celestial coordinates and ephemeris, astrophysics and cosmology, databases, and general utilities. It is recommended to start by reading the manuals. Main and manuals. Install documentation.

Basic structure of the toolbox

Directory structure

The functionality is contained within packages and classes. These packages and classes are available in several directories in the matlab directory. The directories are mainly to separate topics and since all these directories should be added to the matlab path (using the startup.m file; see manuals. Install) they should not concern the user. The packages directory starts with "+", while the classes directory starts with "@".

Naming and coding conventions

Throughout the toolbox we tried to use the following conventions (there are a few exceptions):

• Function and method names start with lowercase letters.
• Packages names start with lower-case letters (an exception +VO).
• Classes names start with upper-case letters (an exception is the static class @ds9).
• Properties in classes start with an upper-case letter. This enables to identify properties vs. method when typing <class_name>.
• Variable names start with upper-case letters.

Packages structure

In many cases, the packages contains sub packages (e.g., celestial.coo; astro.cosmo). Packages typically have a help function (e.g., imProc.help) that presents some basic help for the package. Classes structure The classes usually contain only basic functionality, while more advanced functionality is stored in some specialized packages. An example, the AstroImage class has methods like plus, filter and julday, while more advanced functionality like astrometry and photometry on AstroImage objects is available in the imProc package. The logic for this separation is to make it possible to navigate and find specific functions. For example, if AstroImage would include all the advance methods, then writing AstroImage. will result in a very long list that is hard to search. Instead, the imProc package contains sub-packages according to topics (e.g., astrometry, statistics), that allows the user to navigate and find functionality faster. Each class typically has several static functions that are available outside the scope of the class. All classes usually have a unitTest static method and a help static method. The unitTest can be used to test the class integrity, while the help presents the corresponding mlx (LiveEditor) file in the manuals package.

Navigation and how to find functions

List of all functions, classes, and methods is available in the function list page.

Display all the packages and classes

To search for all the classes and packages in the AstroPack toolbox you can use the following commands:

List = tools.code.listClasses
List = tools.code.listPackages

Similar commands (although output is a bit different) are available, within matlab, for all the packages and classes identified in the search path:

P = meta.package.getAllPackages
P = meta.class.getAllClasses

Display the content of a package

Each package and sub-package contains a function allFunList. This function is automatically generated using the tools.code.genPackage_allFunList. This function displays all the functions and classes under the specific package.

Finding a function

To find a function you can use the sortable table of all functions and methods available through the WWW or the tools.code.classifyAllFiles function. The easiest way to find a function is to guess in which package or class the function is located. A few examples:

• Looking for a function that calculates the angular diameter distance. Start with the astro package, astro. will reveal all the sub-packages, one of them is cosmo (for cosmology), and next astro.cosmo. will reveal several functions, one of them is the ad_dist function.
• Looking for a function to calculate the angular distance between two points on the celestial sphere. This will reside in the celestial.coo subpackage that hosts functions related to spherical coordinates. Inspecting the functions in this subpackage will reveal several functions starting with sphere_dist*. You can inspect the help of these functions to understand the differences.
• For image reduction functions it is good to start looking for methods in the AstroImage class, imProc package, or lcUtil package. Another place to look is the imUtil package. While imUtil contains functions that works directly on matrices, the rest works on images in AstroImage objects.

How to read the help files

All the functions have a help section. The help section will be displayed when typing help <fun_name>. For classes there is also, in some cases, a static class named help that will open the relevant LiveEditor file. A similar shortcut to such LiveEditor files for packages is also available. All the LiveEditor help files reside in the manuals package. The help section typically starts with a short description of the function, followed by the input and output arguments. The symbol "-" is reserved for input/output arguments, while "*" indicate an arbitrary list of arguments (typically keyword, value pairs). In many cases, there are several examples for how to execute the function in the Examples section. Additional examples may be found in the unitTest function.

Packages and Classes by topic

Celestial coordinates and ephemeris

The functions and classes under this category reside mostly in the celestial package, which includes several sub-packages: celestial.coo - Functions to manipulate celestial coordinates, including coordinate conversion, precession, angular distances, searches, refraction, etc.

• celestial.Earth - Geodetic to geocentric conversion and Earth gravity field.
• celestial.htm - Hierarchical Triangular Mesh functions.
• celestial.Kepler - Two body motions, kepler law, and orbital elements functions (see also celestial.OrbitalEl class).
• celestial.map - Map plotting, including monthly maps and finding charts.
• celestial.meteors - Meteors related functions.
• celestial.pm - Fit proper motion.
• celestial.proj - Map projections.
• celestial.scheduling - Observations scheduling (see also the celestial.Targets class).
• celestial.search - Coordinate search.
• celestial.SolarSys - Solar System ephemeris, including Sun Moon, Planets, Jovian satellites, Saturn rings, Moon phase, rise and set, etc. (eee also celestial.INPOP class)
• celestial.time - Time conversion and manipulation including Julian day and sidereal time. and classes:
• celestial.INPOP - A class to download, read, and use the (https://www.imcce.fr/inpop) planetary ephmeris. This can be used for accurate positional predictions of Solar System bodies.
• celestial.OrbitalEl - A class for downloading, reading, and using orbital elements. Can be used to store orbital elements, and use them to calculate positions and ephemeris. The class also supports orbital integration from initial conditions provided by the orbital elements.
• celestial.Targets - A class to store astronomical targets, calculate their visibility, and weight functions by observational history and observing strategy and target selection.

Astronomy & astrophysics

The functions in this category mainly include astrophysics, cosmology, and physics-related functions. These functions reside mainly under the astro package and some specific classes (see below). The astro package includes the following sub packages:

• astro.cosmo
• astro.binary
• astro.grb
• astro.lensing
• astro.microlensing
• astro.mag
• astro.spec
• astro.occultation
• astro.stars
• astro.supernova

Additional functionality ia available in the TimeDelay package. This package provides tools for measuring time delays using photometry and astrometry based on the methods described in Ofek & Springer (2021a, 2021b).

Constants and conversions

The static class constant allows to access physical, astrophysical and astronomical constants. The user can load a specific constant in either cgs (default) or SI system, or upload all constants to the workspace or into a structure. See help constant for details and examples. Unit conversions is mainly available in the static class convert, where some additional conversion tools are available in the celestial.time package.

Telescopes & siignal-to-noise

The telescope package contains functions related to telescope optics, observatories, and signal-to-noise calculations. The following subpacakage are available:

• telescope.obs - Observability tools (see also celestial.Targets)
• telescope.Optics - Telescopes optics and speckle simulations.
• telescope.sn - S/N calculators.

Image reduction and analysis

There are several classes and packages designed for basic and advanced astronomical image processing. The classes are designed mainly as data containers (e.g., a PSF, catalog and image), they also contain basic methods (functions) for the objects, while advance functionality is typically available in the packages. The following high-level classes are available:

• AstroImage - A high-level class for storing image arrays and their meta data. AstroIormage contains properties that are of some more basic classes (like ImageComponent, AstroPSF, AstroCatalog, AstroHeader, etc.). AstroImage provides basic functionality on images like some operators, catalog, header, and PSF access.
• CalibImages - A high-level class for storing calibration images (bias, dark, flat, fringe). It includes functionality to generate calibration images, as well as the processImage method that uses the calibration images and apply them to a set of science images.
• MatchedSources - A high-level class for storing matrices (matrix per property like, RA, Mag, etc.) of epochs vs. sources. Functionality includes relative calibration, matching, and more. There are several packages that are used for image processing:
• imProc - Advance functionality that can operate on AstroImage and AstroCatalog objects. This includes, background estimation, source detection, astrometry, calibration, and many more.
• lcUtil - Advance functionality that can operate on MatchedSources objects (e.g., relative photometry).
• imUtil - Low-level image reduction functionality that can operate directly on matrices (not objects). For modularity, all the high-level functionality are implemented in this package.
• pipeline - This package contains high-level scripts that perform some sort of full image analysis. For example, reducing as ingle image for start to end, or reducing a list of images.

Spectra reduction and analysis

TBD

Astronomical Filters

AstroTransmission (new) and AstFilter (old) are containers for the transmission curves of astronomical filter (bands).

Time series analysis

Functions related to time series analyses can be found in the following packages:

• timeseries - General utilities for time series analysis including periodogram and more.
• TimeDelay - functionality for searching and measuring for time delays for photometric and photometric-astrometric time series (following Springer & Ofek 2021a,b).

Virtual Observatory and catalogs

Excess to some online astronomical databases is available using the VO package. Sub packages in VO include:

• Chandra
• CoRoT
• DECaLS
• Fermi
• GALEX
• HST
• IRSA
• Kepler
• MAST
• name - Astronomical name servers.
• NED
• NIST
• POSS
• prep - Internal Tools for preparing catalogs (e.g., catsHTM).
• PS1
• PTF
• SDSS
• search
• SkyMapper
• Swift
• TNS
• Util
• VizieR
• VLA
• WISE
• ZTF

Local large catalogs (catsHTM)

The catsHTM static class (Sougmanac & Ofek 2018) is a format for storing large astronomical catalogs (e.g., billions of lines) in order to provide fast coordinate access (e.g., fast cone searches). catsHTM was designed for cases in which very fast access is required and sql-like queries (especially over the net) are too slow. catsHTM includes functionality to access these catalogs. Use the Installer class to download the catalogs.

Local small catalogs (cats)

cats support locally installed small catalogs and databases. Using the Installer class you can install the +cats directory under the matlab/data directory. This is a collection of small astronomical catalogs (up to a few milion lines). Each catalog is saved as an AstroCatalog (or AstCat) object and one can download the catalog by calling it (e.g., cats.X.ChandraObs).

Plot tools

The plot package contains some spatial plotting tools.

General tools

Some general tools are available in the tools package. Additional tools related to worldwide web access are available in the www package. The tools package includes the following sub-packages:

• tools.array - Functions related to array manipulations.
• tools.cell - Functions related to cell manipulations.
• tools.code - Functions related to code and documentation generation.
• tools.deriv - Numerical derivatives.
• tools.gui - Graphic user interface.
• tools.install - Installation.
• tools.interp - Interpolation.
• tools.latex - Latex.
• tools.math.fft - FFT.
• tools.math.filter - Filtering.
• tools.math.fit - Fitting tools.
• tools.math.fun - Spatial functions.
• tools.math.geometry - Geometry.
• tools.math.integral - Numerical integration.
• tools.math.stat - Statistics.
• tools.math.symbolic - Symbolic functions.
• tools.os - Operating system.
• tools.rand - Random numbers.
• tools.string - Strings.
• tools.struct - Structure manipulations.
• tools.table - Table manipulations.