Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Updating docs for iterative cubing #36

Merged
merged 1 commit into from
Aug 18, 2020
Merged

Updating docs for iterative cubing #36

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions astrocut/make_cube.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -269,9 +269,10 @@ def make_cube(self, file_list, cube_file="img-cube.fits", sector=None, max_memor
Turns a list of fits image files into one large data-cube.
Input images must all have the same footprint and resolution.
The resulting datacube is transposed for quicker cutouts.
This function can take some time to run and requires enough
memory to hold the entire cube in memory.
(For full TESS sectors this is about 40 GB)
This function can take some time to run, exactly how much time will depend on the number
of input files and the maximum allowed memory. The runtime will be fastest if the
entire data cube can be held in memory, however that can be quite large (~40GB for a full
TESS main mission sector, 3 times that for a TESS extended mission sector).

Parameters
----------
Expand All @@ -285,6 +286,10 @@ def make_cube(self, file_list, cube_file="img-cube.fits", sector=None, max_memor
Optional. The filename/path to save the output cube in.
sector : int
Optional. TESS sector to add as header keyword (not present in FFI files).
max_memory : float
Optional, default is 50. The maximum amount of memory to make available for building
the data cube in GB. Note, this is the maximum amount of space to be used for the cube
array only, so should not be set to the full amount of memory on the system.
verbose : bool
Optional. If true intermediate information is printed.

Expand Down
29 changes: 18 additions & 11 deletions docs/astrocut/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ This is what allows the cutout operation to be performed efficiently.
The `~astrocut.CutoutFactory` class performs the actual cutout and builds
a target pixel file (TPF) that is compatible with TESS pipeline TPFs.

The basic workflow is to first create an image cube from individual FFI files
The basic work-flow is to first create an image cube from individual FFI files
(this is one-time work), and then make individual cutout TPFs from this
large cube file. If you are doing a small number of cutouts, it may make
sense for you to use our tesscut web service:
Expand All @@ -34,18 +34,25 @@ sense for you to use our tesscut web service:
Making image cubes
^^^^^^^^^^^^^^^^^^

Making an image cube is a simple operation, but comes with a vert important
limitation:
Making an image cube is a simple operation, but comes with an important
time/memory trade-off.

.. warning::
**Memory Requirements**
.. important::
**Time/Memory Trade-off**

The entire cube file must be able to fit in your computer's memory!
The "max_memory" argument determines the maximum memory in GB that will be used
for the image data cube while it is being built. This is *only* for the data cube,
and so is somewhat smaller than the amount of memory needed for the program to run.
Never set it to your systems total memory.

For a sector of TESS FFI images from a single camera/chip combination this is ~50 GB.

This operation can also take some time to run. For the 1348 FFI images of the TESS ete-6
simulated sector, it takes about 12 minutes to run on a computer with 65 GB of memory.
Because of this, it is possible to build cube files with much less memory than will
hold the final product. However there is a large time trade-off, as the software must
run through the list of files multiple times instead of just once. The default value
of 50 GB was chosen because it comfortably fits a main mission sector of TESS FFIs,
with the default setting on a system with 65 GB of memory it takes about 15 min to
build a cube file. On a system with less memory that requires 3 passes through the
list of files this time rises to ~45 min.


By default ``make_cube`` runs in verbose mode and prints out its progress, however setting
verbose to false will silence all output.
Expand Down Expand Up @@ -88,7 +95,7 @@ Making cutout target pixel files

To make a cutout, you must already have an image cube to cut out from.
Assuming that that step has been completed, you simply give the central
coordinate and cutout size (in either pixels or angular `~astropy.Quanitity`)
coordinate and cutout size (in either pixels or angular `~astropy.Quantity`)
to the *cube_cut* function.

You can either specify a target pixel file name, or it will be built as:
Expand Down
4 changes: 2 additions & 2 deletions docs/astrocut/install.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ The easiest way to install Astrocut is using pip::
From source
-----------

To install the bleading edge version from github without donloading,
To install the bleeding edge version from github without downloading,
run the following command::

pip git+https://github.com/spacetelescope/astrocut.git
Expand All @@ -38,6 +38,6 @@ using this command::

To install astrocut (from the root of the source tree)::

python setup.py install
pip install .