AstroToolkit 1.3.1__tar.gz → 1.3.2__tar.gz

{AstroToolkit-1.3.1/src/AstroToolkit.egg-info → AstroToolkit-1.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: AstroToolkit
-Version: 1.3.1
+Version: 1.3.2
 Summary: A package for the gathering and plotting of astronomical data.
 Author-email: Ethan Moorfield <ethan.moorfield@hotmail.co.uk>
 Project-URL: Homepage, https://github.com/WD-planets/AstroToolkit
@@ -54,7 +54,7 @@ AstroToolkit (ATK) is a set of useful tools for fetching, plotting, and analysin
 	- 4.2 [plotlightcurve](#42-plotlightcurve)
 - 5 [SED Tools](#5-sed-tools)
 	- 5.1 [sedquery](#51-sedquery)
-	- 5.2 [sedquery](#52-plotsed)
+	- 5.2 [plotsed](#52-plotsed)
 - 6 [Spectrum Tools](#6-spectrum-tools)
 	- 6.1 [spectrumquery](#61-spectrumquery)
 	- 6.2 [plotspectrum](#62-plotspectrum)
@@ -76,10 +76,13 @@ AstroToolkit (ATK) is a set of useful tools for fetching, plotting, and analysin
 	- 10.4 [getdistance](#104-getdistance)
 	- 10.5 [convfromdeg](#105-convfromdeg)
 	- 10.6 [convtodeg](#106-convtodeg)
+	- 10.7 [getcolumn](#107-getcolumn)
+	- 10.8 [getsources](#108-getsources)
+	- 10.9 [getpositions](#109-getpositions)
 
 <br>
 
-## Installation
+## Installation<a id="installation"></a>
 
 The package can be installed as with any other package, e.g. using pip:
 ```
@@ -89,21 +92,21 @@ pip install AstroToolkit
 Once the package has been installed, you should navigate to the package install location. This should be located in: **.../Lib/site-packages/AstroToolkit**, where **...** is your python install location. If you wish to find this, you can use the following command from the terminal:
 
 ```
-python -c "from AstroToolkit import getpath; getpath()"
+python -c "from AstroToolkit.Tools import getpath; getpath()"
 ```
 
-In this directory, run either buildwin.bat (Windows) or build.sh (Linux).
+In this directory, run either buildwin.bat (Windows) or build.sh (Linux) depending on your operating system.
 
 **NOTE:** See _README.txt_ (Linux) or _README - Windows.txt_ (Windows) in the above directory for any additional dependencies.
 
 <br>
 
-## Introduction
+## Introduction<a id="introduction"></a>
 
 ATK uses Bokeh as its primary plotting library. The official documentation can be found at [https://bokeh.org/](https://bokeh.org/). A key property of Bokeh plots is that they can be saved as static .html files, which can then be shared/accessed while retaining all interactivity.
 
 Fundamentally, there are two types of tools in ATK:
-1. Fetching, used to obtain data from a given surveyF
+1. Fetching, used to obtain data from a given survey
 2. Plotting, used to plot the data acquired from the above
 
 In all fetching tools, there are two possible ways to target your system of interest:
@@ -125,7 +128,7 @@ from AstroToolkit.Tools import [tool name]
 
 <br>
 
-## Configuration
+## Configuration<a id="configuration"></a>
 Most default arguments within ATK can be modified through the use of a config file. This can be edited through use of the **editconfig** tool.
 
 **Usage:**
@@ -165,21 +168,55 @@ where options is a dictionary containing key : value pairs to set in the config.
 	- This sets the default radius to use for the Vizier button in the [getbuttons](#72-getbuttons) tool.
 - plot_size = 400
 	- This sets the default plot size for all plotting tools.
+- readfits_sourcename = source_id
+	- This sets the default column name to use in the [getsources](#108-getsources)
+
+**Example:**
+
+To set the default username and password to use for ATLAS queries:
+
+```
+from AstroToolkit.Tools import editconfig
+
+editconfig({'atlas_username':'USERNAME','atlas_password':'PASSWORD'})
+```
 
 <br>
 
+To see the current value of a config parameter, you can use the **getconfigvalue** tool. This will return the parameter's value, and print it to the terminal.
+
+**Usage:**
+
+```
+getconfigvalue(parameter)
+```
+
+where:
+
+```
+parameter = string, name of config parameter from above list
+```
+
+**Returns**: value of this parameter in the config.
+
+<br><br>
+
 ## Tools
 
 In this section, the available tools will be outlined. Note that if a parameter is listed as having a default parameter CONFIG, this means that this parameter is taken from the config as listed above. These parameters can still be passed to the tool, in which case the config value will be ignored.
 
-**Note:** most data returned from fetching tools takes the form of a dictionary. This dictionary contains the returned data, as well as basic information such as the pos/source used to acquire the data. This format is then used by other ATK functions (such as plotting tools, and file saving/reading).
+**Note:** most data returned from fetching/plotting tools takes the form of a dictionary. This dictionary contains the returned data, as well as basic information such as the pos/source used to acquire the data. This format is then used by other ATK functions (such as file showing/saving/reading).
+
+**Note:** All plots created by ATK can have their legends toggled by double clicking the plot, and individual data can be hidden by clicking them in the legend.
+
+<br>
 
-**Note:** Most plots created by ATK can have their legends toggled by double clicking the plot, and individual data can be hidden by clicking them in the legend.
+**In all data returned by querying tools, the value of the 'data' key will be set to None if no data was returned. Likewise, in all plotting tools, the value of the 'plot' key will be set to None.**
 
 <br>
 
-### 1. Raw Data Tools
-### 1.1. dataquery
+### 1. Raw Data Tools<a id="1-raw-data-tools"></a>
+### 1.1. dataquery<a id="11-dataquery"></a>
 
 Returns all available data for a given survey (e.g. magnitudes, positions, etc.).
 
@@ -204,19 +241,19 @@ survey = str, name of a supported survey
 pos = list, [ra,dec]
 ```
 ```
-source = int/float/str, Gaia source_id
+source = int/str, Gaia source_id
 ```
 ```
 radius = int/float, radius of query
 ```
 
-**Returns:** dict or None
+**Returns:** dict
 
 ```
 {
 'survey' : str, survey of data
 'type' : 'data'
-'source' : int/float/str, source used to get data (None if a pos was used)
+'source' : int/str, source used to get data (None if a pos was used)
 'pos' : [ra,dec], pos used to get data (None if a source was used)
 'data' : dict, the returned data
 }
@@ -239,7 +276,7 @@ wise_data = dataquery(survey='wise',source=source)['data']
 
 <br><br>
 
-### 1.2. photquery
+### 1.2. photquery<a id="12-photquery"></a>
 
 Returns data from a given survey, with columns filtered to only include photometry and other basic information.
 
@@ -264,19 +301,19 @@ survey = str, name of a supported survey
 pos = list, [ra,dec]
 ```
 ```
-source = int/float/str, Gaia source_id
+source = int/str, Gaia source_id
 ```
 ```
 radius = int/float, radius of query
 ```
 
-**Returns:** dict or None
+**Returns:** dict
 
 ```
 {
 'survey' : str, survey of data
 'type' : 'data'
-'source' : int/float/str, source used to get data (None if a pos was used)
+'source' : int/str, source used to get data (None if a pos was used)
 'pos' : [ra,dec], pos used to get data (None if a source was used)
 'data' : dict, the returned data
 }
@@ -295,7 +332,7 @@ data=photquery(survey='twomass',source=6050296829033196032)['data']
 
 <br>
 
-### 1.3. bulkphotquery
+### 1.3. bulkphotquery<a id="13-bulkphotquery"></a>
 
 Returns available photometry from all surveys supported by [photquery](#12-photquery).
 
@@ -313,18 +350,18 @@ where:
 pos = list, [ra,dec]
 ```
 ```
-source = int/float/str, Gaia source_id
+source = int/str, Gaia source_id
 ```
 ```
 radius = int/float, radius of query
 ```
 
-**Returns:** dict or None
+**Returns:** dict
 
 ```
 {
 'type' : 'bulkphot'
-'source' : int/float/str, source used to get data (None if a pos was used)
+'source' : int/str, source used to get data (None if a pos was used)
 'pos': [ra,dec], pos used to get data (None if a source was used)
 'data' : {
          'gaia' : dict, returned data (or None if no data returned)
@@ -335,6 +372,8 @@ radius = int/float, radius of query
 }
 ```
 
+**Note:** The value of each survey will be set to None if no data was returned. E.g. if no galex data was returned, the value of the ['galex'] key would be None.
+
 <br>
 
 **Example:**
@@ -352,7 +391,7 @@ galex_data=bulk_phot['galex']
 
 <br>
 
-### 1.4. getreddening
+### 1.4. getreddening<a id="14-getreddening"></a>
 
 Returns the reddening of a Gaia source.
 
@@ -369,31 +408,31 @@ getreddening(source)
 
 where:
 ```
-source = int/float/str, Gaia source_id
+source = int/str, Gaia source_id
 ```
 
 <br>
 
-**Returns:** dict or None
+**Returns:** dict
 
 ```
 {
 'type' : 'reddening'
-'source' : int/float/str, source used to get data (None if a pos was used)
+'source' : int/str, source used to get data (None if a pos was used)
 'data' : {
          'dist' : distance to source (1/parallax)
          'red_dist' : actual distance to which survey's reddening estimate refers
-		 'red_dist_err' : error on red_dist
-		 'red' : survey's reddening estimate
-		 'red_upper' : reddening upper limit
-		 'red_lower' : reddening lower limit
+         'red_dist_err' : error on red_dist
+         'red' : survey's reddening estimate
+         'red_upper' : reddening upper limit
+         'red_lower' : reddening lower limit
          }
 }
 ```
 
 <br><br>
 
-### 2. Imaging Tools
+### 2. Imaging Tools<a id="2-imaging-tools"></a>
 
 These functions retrieve and plotimages from supported surveys.
 
@@ -401,9 +440,19 @@ These functions retrieve and plotimages from supported surveys.
 
 <br>
 
-### 2.1. imagequery
+### 2.1. imagequery<a id="21-imagequery"></a>
+
+Retrieves an image from a given survey. Overlays  can be used to overlay detections from different surveys. There are two types of overlay: detections and tracers. Detections are proper motion-corrected circles that scale with the magnitude of the detection, and show that there is data available for a given object in a given survey. 
+
+Tracers (which are detections created from lightcurve surveys) can be used both to show that lightcurve data is available, but also to trace an object through time.
 
-Retrieves an image from a given survey
+**Note:** tracing an object through time works best with ZTF and CRTS overlays, as these give data with the necessary coordinate precision. Other tracer overlays are unlikely to work for this, and will hence only be useful to see where lightcurve data is available.
+
+**Note:** In the case of ATLAS overlays, the radius used is very small due to the time taken to perform ATLAS queries. Only data close to the focus of the image (i.e. at the location of the target object) will be shown. 
+
+**Example:**
+
+![](https://github.com/WD-planets/AstroToolkit/raw/latest/README_Images/tracer_example.png?raw=true)
 
 <br>
 
@@ -416,7 +465,7 @@ Supported surveys:
 
 <br>
 
-Supported overlays: gaia, galex_nuv, galex_fuv, rosat,sdss, twomass, wise, ztf, erosita ,atlas, gaia_lc, asassn
+Supported overlays: gaia, galex_nuv, galex_fuv, rosat,sdss, twomass, wise, ztf, erosita ,atlas, gaia_lc, asassn, crts
 
 **Note:** Can also use 'all', which will enable overlays for all supported surveys.
 
@@ -436,7 +485,7 @@ survey = str, name of a supported survey
 pos = list, [ra,dec]
 ```
 ```
-source = int/float/str, Gaia source_id
+source = int/str, Gaia source_id
 ```
 ```
 size = int/float, size of image in arcsec
@@ -448,25 +497,23 @@ band = str, string containing the required bands (e.g. for all panstarrs bands,
 overlays = str, required detection overlays (e.g. for gaia and wise detections, use overlays='gaia,wise') 
 ```
 
-**Returns:** dict or None
-
-**Returns:**
+**Returns:** dict
 
 ```
 {
 'type' : 'image'
-'data' : array, image data
-'header' : astropy header, image header
-'metadata' : {
-             'survey' : str, image survey
-             'source' : int/float/str, source used to get image (None if a pos was used)
-             'pos' : [ra,dec], pos used to get image (None if a source was used)
-             'location' : [ra,dec], actual location of the image
-             'size' : int/float, image size in arcsec
-             'image_time' : [year,month], image time
-             'wcs' : astropy wcs object of image
-             'overlay' : list of overlay entries
-             }
+'survey' : str, image survey
+'source' : int/str, source used to get image (None if a pos was used)
+'pos' : [ra,dec], pos used to get image (None if a source was used)
+'data' : {
+         'image_data' : array, image data
+         'image_header' : astropy header, image header
+         'location' : [ra,dec], actual location of the image
+         'size' : int/float, image size in arcsec
+         'image_time' : [year,month], image time
+         'wcs' : astropy wcs object of image
+         'overlay' : list of overlay entries
+         }
 }
 ```
 
@@ -474,7 +521,7 @@ overlays = str, required detection overlays (e.g. for gaia and wise detections,
 
 ```
 {
-'survey' : int/float/str, survey of detection
+'survey' : str, survey of detection
 'position: [ra,dec], coordinates of detection
 'radius' : float, radius of detection
 'corrected' : bool, whether or not the detection has been corrected for proper motion
@@ -485,7 +532,7 @@ overlays = str, required detection overlays (e.g. for gaia and wise detections,
 
 <br>
 
-### 2.2. plotimage
+### 2.2. plotimage<a id="22-plotimage"></a>
 
 Plots images in format returned by [imagequery](#21-imagequery).
 
@@ -502,7 +549,20 @@ where:
 data = dict in format returned by imagequery
 ```
 
-**Returns:** bokeh figure object
+**Returns:** dict
+
+```
+{
+'type' : 'image'
+'survey' : str, survey of image
+'source' : int/str, source used to get image (None if a pos was used)
+'pos' : [ra,dec], pos used to get image (None if a source was used)
+'plot' : bokeh figure object, the actual plot
+'ATKfilename' : the default filename given by ATK
+}
+```
+
+**Note:** if a plot is not returned (e.g. if no data was supplied to the plotting tool), the 'plot' key will be set to None.
 
 <br>
 
@@ -521,8 +581,8 @@ showplot(plot)
 
 <br><br>
 
-### 3. HRD Tools
-### 3.1. plothrd
+### 3. HRD Tools<a id="3-hrd-tools"></a>
+### 3.1. plothrd<a id="31-plothrd"></a>
 
 Returns a HRD with a source or list of sources overlayed over a Gaia 100pc background sample.
 
@@ -537,13 +597,23 @@ plothrd(source=None,sources=None)
 where:
 
 ```
-source = int/float/str, Gaia source_id
+source = int/str, Gaia source_id
 ```
 ```
 sources = list of sources
 ```
 
-**Returns:** bokeh figure object
+**Returns:** dict
+
+```
+{
+'type' : 'hrd'
+'source' : int/str, source overlayed in HRD
+'sources' : list, sources overlayed in HRD if multiple were given
+'plot' : bokeh figure object, the actual plot
+'ATKfilename' : the default filename given by ATK
+}
+```
 
 <br>
 
@@ -560,8 +630,8 @@ showplot(plot)
 
 <br><br>
 
-### 4. Lightcurve Tools
-### 4.1. lightcurvequery
+### 4. Lightcurve Tools<a id="4-lightcurve-tools"></a>
+### 4.1. lightcurvequery<a id="41-lightcurvequery"></a>
 
 Returns lightcurve data for a given survey.
 
@@ -572,8 +642,9 @@ Supported surveys:
 - ATLAS (atlas) - o, c, i
 - ASAS-SN (asassn) - g, v
 - Gaia (gaia) - g, bp, rp
+- CRTS (crts) - v
 
-**Note:**
+**Note:** CRTS' data server is not designed for scripted queries. As a result, queries are limited in the toolkit to one query per 15 seconds. This cooldown is managed using the CRTS_TIMER.txt file in the Settings directory of the package files, and hence this should not be edited.
 
 <br>
 
@@ -589,7 +660,7 @@ survey = str, name of a supported survey
 pos = list, [ra,dec]
 ```
 ```
-source = int/float/str, Gaia source_id
+source = int/str, Gaia source_id
 ```
 ```
 radius = int/float, radius of lightcurve query
@@ -604,30 +675,24 @@ password = str, ATLAS password, hence only used in ATLAS queries
 sigmaclip = int, performs sigma clipping on the data to this number of standard deviations
 ```
 
-**Returns:** list
-
-list of lightcurve data dictionaries with an entry for each band in that survey (see below). If no data is found for a given band, that entry will be set to None. The order of these entries matches the band listing for a given survey in 'supported surveys' above.
+**Returns:** list of dicts
 
-e.g. for ztf, if g and r data were found, but no i data was found, the result would be a list:
-
-```
-[g_entry,r_entry,None]
-```
-
-where each non-None entry has the format:
+list of lightcurve data dictionaries with an entry for each band in that survey (see below). Each entry has the format:
 
 ```
 {
 'type' : 'lightcurve'
-'source' : int/float/str, source used to get data (None if a pos was used)
+'source' : int/str, source used to get data (None if a pos was used)
 'pos': [ra,dec], pos used to get data (None if a source was used)
 'survey' : str, survey of data
 'band' : str, band of lightcurve data
 'data' : {
          'ra' : list of returned ra values
          'dec' : list of returned dec values
-         'hjd'/'mjd' : list of returned hjd/mjd values, with the minimum returned value subtracted from all values (i.e. is just a measure of days from the first observation)
-		 'hjd_ori'/'mjd_ori' : list of returned hjd/mjd values, unedited
+         'hjd'/'mjd' : list of returned hjd/mjd values, with the minimum returned
+          value subtracted from all values (i.e. is just a measure of days from the 
+          first observation)
+         'hjd_ori'/'mjd_ori' : list of returned hjd/mjd values, unedited
          'mag' : list of returned magnitude values
          'mag_err' : list of returned magnitude error values
          }
@@ -636,7 +701,7 @@ where each non-None entry has the format:
 
 <br>
 
-### 4.2. plotlightcurve
+### 4.2. plotlightcurve<a id="42-plotlightcurve"></a>
 
 Plots lightcurves in the format returned by [lightcurvequery](#41-lightcurvequery).
 
@@ -659,7 +724,18 @@ colour = str, name of a supported colour. Only used when passing a single lightc
 colours = list of strings denoting supported colours, e.g. ['green','red','blue']. Only used when passing multiple lightcurves
 ```
 
-**Returns:** bokeh figure object
+**Returns:** dict
+
+```
+{
+'type' : 'lightcurve'
+'survey' : str, survey of lightcurve
+'source' : int/str, source used to get data (None if a pos was used)
+'pos': [ra,dec], pos used to get data (None if a source was used)
+'plot' : bokeh figure object, the actual plot
+'ATKfilename' : the default filename given by ATK
+}
+```
 
 <br>
 
@@ -678,8 +754,8 @@ showplot(plotlightcurve(lightcurves,colours=['green','red','blue']))
 
 <br><br>
 
-### 5. SED Tools
-### 5.1. sedquery
+### 5. SED Tools<a id="5-sed-tools"></a>
+### 5.1. sedquery<a id="51-sedquery"></a>
 
 Queries all supported photometry surveys and returns SED data.
 
@@ -696,32 +772,32 @@ where:
 pos = list, [ra,dec]
 ```
 ```
-source = int/float/str, Gaia source_id
+source = int/str, Gaia source_id
 ```
 ```
 radius = int/float, radius of data query
 ```
 
-**Returns:** dict or None
+**Returns:** dict
 
 ```
 {
 'type' : 'sed'
-'source' : int/float/str, source used to get data (None if a pos was used)
+'source' : int/str, source used to get data (None if a pos was used)
 'pos': [ra,dec], pos used to get data (None if a source was used)
 'data': list of entries with each entry taking the form of a dict:
-		{
-        'survey' : str, survey of data point
-        'wavelength' : filter wavelength of data point
-        'flux' : flux through filter
-        'rel_err' : relative error on flux
-        }
+	{
+    'survey' : str, survey of data point
+    'wavelength' : filter wavelength of data point
+    'flux' : flux through filter
+    'rel_err' : relative error on flux
+    }
 }
 ```
 
 <br>
 
-### 5.2. plotsed
+### 5.2. plotsed<a id="52-plotsed"></a>
 
 Plots SEDs in the format returned by [sedquery](#51-sedquery).
 
@@ -739,7 +815,17 @@ where:
 data = dict in format returned by sedquery
 ```
 
-**Returns:** bokeh figure object
+**Returns:** dict
+
+```
+{
+'type' : 'sed'
+'source' : int/str, source used to get data (None if a pos was used)
+'pos': [ra,dec], pos used to get data (None if a source was used)
+'plot' : bokeh figure object, the actual plot
+'ATKfilename' : the default filename given by ATK
+}
+```
 
 <br>
 
@@ -755,8 +841,8 @@ showplot(plotsed(data))
 
 <br><br>
 
-### 6. Spectrum Tools
-### 6.1. spectrumquery
+### 6. Spectrum Tools<a id="6-spectrum-tools"></a>
+### 6.1. spectrumquery<a id="61-spectrumquery"></a>
 
 Returns spectrum data from a given survey.
 
@@ -776,19 +862,19 @@ survey = str, name of a supported survey
 pos = list, [ra,dec]
 ```
 ```
-source = int/float/str, Gaia source_id
+source = int/str, Gaia source_id
 ```
 ```
 radius = int/float, radius of data query
 ```
 
-**Returns:** dict or None
+**Returns:** dict
 
 ```
 {
 'type' : 'spectra'
-'survey' : int/float/str, survey of detection
-'source' : int/float/str, source used to get data (None if a pos was used)
+'survey' : str, survey of detection
+'source' : int/str, source used to get data (None if a pos was used)
 'pos': [ra,dec], pos used to get data (None if a source was used)
 'data': {
         'wavelength' : list of wavelength values
@@ -799,7 +885,7 @@ radius = int/float, radius of data query
 
 <br>
 
-### 6.2. plotspectrum
+### 6.2. plotspectrum<a id="62-plotspectrum"></a>
 
 Plots spectra in the format returned by [spectrumquery](#61-spectrumquery).
 
@@ -817,7 +903,18 @@ where:
 data = dict in format returned by spectrumquery
 ```
 
-**Returns:** bokeh figure object
+**Returns:** dict
+
+```
+{
+'type' : 'spectrum'
+'survey' : str, survey of spectrum
+'source' : int/str, source used to get data (None if a pos was used)
+'pos': [ra,dec], pos used to get data (None if a source was used)
+'plot' : bokeh figure object, the actual plot
+'ATKfilename' : the default filename given by ATK
+}
+```
 
 <br>
 
@@ -835,8 +932,8 @@ showplot(plot)
 
 <br><br>
 
-### 7. Timeseries Tools
-### 7.1 plotpowspec
+### 7. Timeseries Tools<a id="7-timeseries-tools"></a>
+### 7.1 plotpowspec<a id="71-plotpowspec"></a>
 
 Plots a power spectrum from lightcurve data in the format returned by [lightcurvequery](#41-lightcurvequery)
 
@@ -853,7 +950,18 @@ where:
 data = dict or list in format returned by lightcurvequery
 ```
 
-**Returns:** bokeh figure object
+**Returns:** dict
+
+```
+{
+'type' : 'powspec'
+'survey' : str, survey of lightcurve data given to the powspec tool
+'source' : int/str, source used to get data (None if a pos was used)
+'pos': [ra,dec], pos used to get data (None if a source was used)
+'plot' : bokeh figure object, the actual plot
+'ATKfilename' : the default filename given by ATK
+}
+```
 
 <br>
 
@@ -871,7 +979,7 @@ showplot(plot)
 
 <br><br>
 
-### 7.2 tsanalysis
+### 7.2 tsanalysis<a id="72-tsanalysis"></a>
 
 Runs period analysis on lightcurve data in format returned by [lightcurvequery](#lightcurvequery)
 
@@ -904,7 +1012,7 @@ plot=tsanalysis(data)
 
 <br><br>
 
-## 8. Datapage Tools
+## 8. Datapage Tools<a id="8-datapage-tools"></a>
 
 These functions are used to create custom datapages from any plots/data supported by AstroToolkit.
 
@@ -916,9 +1024,9 @@ Below is the datapage produced by this example. Once the script to create these
 
 <br>
 
-### 8.1. gridsetup
+### 8.1. gridsetup<a id="81-gridsetup"></a>
 
-Helps with datapage creation.
+Formats plots for datapage creation by sizing them to a grid of given dimensions.
 
 <br>
 
@@ -930,30 +1038,39 @@ getgrid(dimensions,plots,grid_size=CONFIG)
 
 where:
 ```
-dimensions = list, grid dimensions in format [width,height]. E.g. for a grid that is 6 units wide and 3 units tall, use dimensions = [6,3]
+dimensions = dict, dict with keys 'width' and 'height' that define the dimensions of the datapage in grid units (e.g. for a datapage that is 6 units wide and 3 units tall, dimensions={'width':6,'height':3})
 ```
 ```
-plots = list of lists, plots with their desired dimensions included. E.g. for a 2x2 plot and two 2x1 plots, use plots = [[plot1,2,2],[plot2,2,1],[plot3,2,1]].
+plots = list of plots, with each entry having the format:
+        {
+        'name' : the label to give to the plot
+        'figure' : the plot dictionary as returned by plotting tools
+        'width' : the width in grid units of this element
+        'height' : the height in grid units of this element
+        }
 ```
 ```
 grid_size  = int, size of each square of the grid to which all plots are scaled.
 ```
 
-**Returns:** list
-
-list of plots stripped of their dimensions. E.g. for the plots = ... input above, the following will be returned:
+**Returns:** dict
 
 ```
-[plot1,plot2,plot3]
+{
+'name 1' : plot 1
+'name 2' : plot 2
+
+etc. for each plot given to the tool
+}
 ```
 
-where all plots have been scaled to the desired grid size.
+where the keys "name ..." are the names given to the plots above, and the values 'plot ...' are the plots to which these names refer.
 
 **NOTE:** Again, see the datapage_creation example as noted [above](#8-datapage-tools) for an example.
 
 <br>
 
-### 8.2. getbuttons
+### 8.2. getbuttons<a id="82-getbuttons"></a>
 
 Returns a Bokeh figure containing SIMBAD and Vizier buttons for use in datapages.
 
@@ -973,7 +1090,7 @@ grid_size = int, size of the grid to which the buttons are scaled.
 pos = list, [ra,dec] in degrees
 ```
 ```
-source = int/float/str, Gaia source_id
+source = int/str, Gaia source_id
 ```
 ```
 simbad_radius = int, radius to use in SIMBAD queries
@@ -982,15 +1099,22 @@ simbad_radius = int, radius to use in SIMBAD queries
 vizier_radius = int, radius to use in Vizier queries
 ```
 
-**Returns:**
+**Returns:** dict
 
-bokeh figure object
+```
+{
+'type' : 'buttons'
+'source' : int/str, source used to get data (None if a pos was used)
+'pos': [ra,dec], pos used to get data (None if a source was used)
+'plot' : bokeh figure object, the actual plot element
+}
+```
 
 **NOTE:** Again, see the datapage_creation example as noted [above](#8-datapage-tools) for an example.
 
 <br>
 
-### 8.3. getmdtable
+### 8.3. getmdtable<a id="83-getmdtable"></a>
 
 Creates a table of metadata table using data from supported surveys and/or custom data.
 
@@ -1011,7 +1135,7 @@ metadata = dict, dictionary of metadata in accepted format (see below)
 pos = list, [ra,dec] in degrees
 ```
 ```
-source = int/float/str, Gaia source_id
+source = int/str, Gaia source_id
 ```
 
 <br>
@@ -1021,8 +1145,10 @@ The expected metadata format is:
 ```
 {
 'gaia' : {
-         'parameters' : names of parameters (i.e. column headers) that exist in that survey
-         'errors' : names of errors (i.e. column headers) for these parameters that exist in that survey
+         'parameters' : names of parameters (i.e. column headers) that exist in that
+          survey
+         'errors' : names of errors (i.e. column headers) for these parameters that
+          exist in that survey
          'notes' : str, any notes to include on this parameter/error/etc.
          }
 }
@@ -1047,19 +1173,27 @@ In this case, an additional 'values' key must be included, and the values/errors
 }
 ```
 
-**Returns**:
-bokeh figure object
+**Returns**: dict
+
+```
+{
+'type' : 'metadata'
+'source' : int/str, source used to get data (None if a pos was used)
+'pos': [ra,dec], pos used to get data (None if a source was used)
+'plot' : bokeh figure object, the actual plot element
+}
+```
 
 **NOTE:** Again, see the datapage_creation example as noted [above](#8-datapage-tools) for an example.
 
 <br><br>
 
-## 9. File Handling Tools
+## 9. File Handling Tools<a id="9-file-handling-tools"></a>
 These tools can be used to transform many returned ATK data structures into local files, and vice versa. This process is designed to be completely lossless, allowing for the exact data structure that was used to create a file to be recreated at a later date.
 
 <br>
 
-### 9.1. savedata
+### 9.1. savedata<a id="91-savedata"></a>
 
 This tool allows for the saving of many ATK data structures into local files.
 
@@ -1089,7 +1223,7 @@ Name of file that the data was saved to
 
 <br>
 
-### 9.2. readdata
+### 9.2. readdata<a id="92-readdata"></a>
 
 This tool allows for the lossless recreation of ATK data stuctures from files created using [savedata](#91-savedata).
 
@@ -1132,9 +1266,9 @@ showplot(plotlightcurve(recreated_lightcurve_data,colours=['red','orange','yello
 
 <br>
 
-### 9.3. export
+### 9.3. export<a id="93-export"></a>
 
-This allows for bokeh figures to be saved as a .png file.
+This allows for ATK figures to be saved as a .png file.
 
 <br>
 
@@ -1154,15 +1288,15 @@ keephtml = bool. To get the filename for the png, the plot must first be saved a
 
 <br><br>
 
-### 10. Miscellaneous Tools
+### 10. Miscellaneous Tools<a id="10-miscellaneous-tools"></a>
 
 These are tools that do not fit into the above categories, but can still be useful for quickly performing some basic functions.
 
 <br>
 
-### 10.1. showplot
+### 10.1. showplot<a id="101-showplot"></a>
 
-This is just bokeh's show() functionality, but allows for it to be imported from ATK for ease of use since this is the backbone of the package.
+This allows for the plot dictionaries returned by ATK to be opened in the browser. Doing so will also save the plot locally as a .html file. Can also be used with the same functionality as show() from bokeh for non-ATK bokeh figures.
 
 <br>
 
@@ -1173,14 +1307,14 @@ showplot(plot)
 
 where:
 ```
-plot = bokeh figure object
+plot = ATK plot dictionary
 ```
 
 <br>
 
-### 10.2. saveplot
+### 10.2. saveplot<a id="102-saveplot"></a>
 
-This is just bokeh's save() functionality, but allows for it to be imported from ATK for ease of use since this is the backbone of the package.
+This allows for the plot dictionaries returned by ATK to be saved to local .html files without opening them in the browser. Can also be used with the same functionality as save() from bokeh for non-ATK bokeh figures.
 
 <br>
 
@@ -1191,12 +1325,12 @@ saveplot(plot)
 
 where:
 ```
-plot = bokeh figure object
+plot = ATK plot dictionary
 ```
 
 <br>
 
-### 10.3. correctpm
+### 10.3. correctpm<a id="103-correctpm"></a>
 
 Corrects for proper motion of an object between an input time and a target time.
 
@@ -1250,7 +1384,7 @@ ra_corrected,dec_corrected=correctpm([2016,0],[2000,0],ra,dec,pmra,pmdec)
 
 <br>
 
-### 10.4. getdistance
+### 10.4. getdistance<a id="104-getdistance"></a>
 
 Simply calculates the distance (1/parallax) of an object given its parallax in mas (the unit of parallax in Gaia).
 
@@ -1275,7 +1409,7 @@ distance of object in pc
 
 <br>
 
-### 10.5. convfromdeg
+### 10.5. convfromdeg<a id="105-convfromdeg"></a>
 
 Converts deg coordinates to HMS/DMS format
 
@@ -1300,7 +1434,7 @@ pos = list, [ra,dec] of object in degrees
 
 <br>
 
-### 10.6. convtodeg
+### 10.6. convtodeg<a id="106-convtodeg"></a>
 
 Converts HMS/DMS coordinates to deg.
 
@@ -1314,7 +1448,7 @@ convfromdeg(pos)
 
 where:
 ```
-pos = list, [ra,dec] of object in [HMS/DMS] format
+pos = list, [ra,dec] of object in [HMS/DMS] format, i.e. [[H,M,S],[D,M,S]]
 ```
 
 <br>
@@ -1322,3 +1456,75 @@ pos = list, [ra,dec] of object in [HMS/DMS] format
 **Returns:** list
 
 [ra,dec] of object in deg
+
+<br>
+
+### 10.7. getcolumn<a id="107-getcolumn"></a>
+
+Returns a list of values from a .fits file given a column name.
+
+**Usage:**
+
+```
+getcolumn(file_name,col_name)
+```
+
+where:
+```
+file_name = str, name of file with or without the .fits extension.
+```
+```
+col_name = str, name of column in file
+```
+
+**Returns:** list
+
+list of values for that column
+
+<br>
+
+### 10.8. getsources<a id="108-getsources"></a>
+
+Returns a list of source values from a .fits file given a column name, which can either be set in the tool or in the config.
+
+**Usage:**
+
+```
+getsources(file_name,col_name=CONFIG)
+```
+
+where:
+```
+file_name = str, name of file with or without the .fits extension.
+```
+```
+col_name = str, name of column containing Gaia sources
+```
+
+**Returns:** list
+
+list of Gaia sources
+
+<br>
+
+### 10.9. getpositions<a id="109-getpositions"></a>
+
+Returns a list of ra,dec values from a .fits file given ra and dec column names, which can either be set in the tool or in the config.
+
+**Usage:**
+
+```
+getsources(file_name,col_name=CONFIG)
+```
+
+where:
+```
+file_name = str, name of file with or without the .fits extension.
+```
+```
+col_name = str, comma separated string containing names of ra and dec columns. e.g. col_name = 'RA_ICRS,'DE_ICRS'. Must be in this order.
+```
+
+**Returns:** list
+
+list of positions [[ra1,dec1],[ra2,dec2]], etc.