funenv(7)

🌸 NAME 🌸

FunEnv — the Funtools Environment Variables, bestie. Yes this is funenv(7) from the SAORD Documentation crew, and we're gonna go through every single one, no skips. 💖

---

✨ SYNOPSIS ✨

Okay so basically: this page describes the environment variables that tailor the overall Funtools environment. That's it, that's the vibe. 🎀

---

🦋 DESCRIPTION 🦋

The following environment variables are supported by Funtools, and we're listing every one of them because we are thorough: 🫶

💅 FITS_EXTNAME

This one specifies the default FITS extension name when FunOpen() is called on a file that's lacking a primary image. So like,

setenv FITS_EXTNAME "NEWEV"

lets you call FunOpen() on files without having to specify NEWEV in the Funtools bracket specification. ✨

And if there's no FITS_EXTNAME variable defined and the extension name isn't passed in the bracket specification either? Then the default is to look for the standard X-ray event table extension names "EVENTS" or "STDEVT" — because we are, after all, an X-ray astronomy group at heart! 🥺🌌

🌟 FITS_EXTNUM

Specifies the default FITS extension number when FunOpen() is called on a file lacking a primary image. So,

setenv FITS_EXTNUM 7

lets you call FunOpen() on files and open the seventh extension without specifying the number in the Funtools bracket specification. Iconic, honestly. 👑

🎀 FITS_BINCOLS and EVENTS_BINCOLS

These specify the default binning key for FITS binary tables and raw event files, respectively. They can be over-ridden using the bincols=[naxis1,naxis2] keyword in a Funtools bracket specification. The value of each environment variable is a pair of comma-delimited columns, wrapped in parentheses, used for binning.

So if you wanna bin on detx and dety by default, you do:

setenv FITS_BINCOLS "(detx,dety)"

instead of adding a bincols specification to every single filename like some kind of chaos gremlin:

foo.fits[bincols=(detx,dety)]

💜 FITS_BITPIX and EVENTS_BITPIX

These set the default bitpix value for binning FITS binary tables and raw event files, respectively. They can be over-ridden using the bitpix=[value] keyword in a Funtools bracket specification. The value of each environment variable is one of the standard FITS bitpix values: 8, 16, 32, -32, -64.

So if you want the binning routines to create a floating array, use:

setenv FITS_BITPIX -32

in preference to adding a bitpix specification to every filename:

foo.fits[bitpix=-32]

🌈 ARRAY

The ARRAY environment variable specifies the default definition of an array file for Funtools. It's used when there's no array specification passed in the ARRAY() directive in a Non-FITS Array specification. The value is a valid array specification, like:

setenv ARRAY "s100.150"
foo.arr[ARRAY()]

And this can be defined in preference to adding the specification to every filename:

foo.arr[ARRAY(s100.150)]

🦋 EVENTS

The EVENTS environment variable specifies the default definition of a raw event file for Funtools. It's used when there's no EVENTS specification passed in the EVENTS() directive in a Non-FITS EVENTS specification. The value is a valid EVENTS specification, such as:

setenv EVENTS "x:J:1024,y:J:1024,pi:I,pha:I,time:D,dx:E:1024,dx:E:1024"
foo.ev[EVENTS()]

And again, this can be defined in preference to adding the specification to every filename:

foo.ev[EVENTS(x:J:1024,y:J:1024,pi:I,pha:I,time:D,dx:E:1024,dx:E:1024)]

---

The following filter-related environment variables are supported by Funtools: 🔥

⭐ FILTER_PTYPE

The FILTER_PTYPE environment variable specifies how to build a filter. There are three possible methods:

• process or p — the filter is compiled and linked against the funtools library (which must therefore be accessible in the original install directory) to produce a slave program. This program is fed events or image data and returns filter results.
• dynamic or d (gcc only) — the filter is compiled and linked against the funtools library (which must therefore be accessible in the original install directory) to produce a dynamic shared object, which is loaded into the funtools program and executed as a subroutine. (Extensive testing has shown that, contrary to expectations, this method is no faster than using a slave process.)
• contained or c — the filter and all supporting region code is compiled and linked without reference to the funtools library to produce a slave program (which is fed events or image data and returns filter results). This method is slower than the other two, because of the time it takes to compile the region filtering code. It's used by stand-alone programs such as ds9, which don't have access to the funtools library.

By default, dynamic is generally used for gcc compilers and process for other compilers. However, the filter building algorithm will check for required external files and will use contained if these are missing. 👀

🍓 FUN_MAXROW

The FUN_MAXROW environment variable is used by the core row-processing Funtools programs (funtable, fundisp, funcnts, funhist, funmerge, and funcalc) to set the maximum number of rows read at once — i.e. it sets the third argument to the FunTableRowGet() call. The default is 8192.

Heads up bestie: this variable is a convention only. It will not be a part of a non-core Funtools program unless code is explicitly added, since each call to FunTableRowGet() specifies its own maximum number of rows to read. NB: if you make this value very large, you probably will need to increase FUN_MAXBUFSIZE (see below) as well. 😭

🧚 FUN_MAXBUFSIZE

The FUN_MAXBUFSIZE environment variable is used to limit the max buffer size that will be allocated to hold table row data. This buffer size is calculated to be the row size of the table multiplied by the maximum number of rows read at once (see above).

Since the row size is unlimited (and we have examples of it being larger than 5 Mb), it's possible that the total buffer size will exceed the machine capabilities. We therefore set a default value of 5Mb for the max buffer size, and adjust maxrow so that the total size calculated is less than this max buffer size. (If the row size is greater than this max buffer size, then maxrow is set to 1.) This environment variable will change the max buffer size allowed. 💀

💖 FILTER_CC

The FILTER_CC environment variable specifies the compiler to use for compiling a filter specification. You also can use the CC environment variable. If neither has been set, then gcc will be used if available. Otherwise cc is used if available. 🛠️

🎀 FILTER_EXTRA

The FILTER_EXTRA environment variable specifies extra options to add to a filter compile command line. In principle, you can add libraries, include files, and compiler switches.

Use this variable with care, okay? 🙈

🌸 FILTER_TMPDIR

The FILTER_TMPDIR environment variable specifies the temporary directory for filter compilation intermediate files. You also can use the TMPDIR and TMP variables. By default, /tmp is used as the temporary directory. 🗂️

✨ FILTER_KEEP

The FILTER_KEEP environment variable specifies whether the intermediate filter files (i.e. the C source file and compile log file) should be saved after a filter is built. The default is "false", so those intermediate files get deleted.

This variable is useful for debugging, but care should be taken to reset its value to false when debugging is complete. 🚨

---

🔥 SEE ALSO 🔥

See funtools(7) for a list of Funtools help pages. Go read it, bestie, it's giving ✨completionist✨. 📚

---

Okay that's the whole page, we ate and left no crumbs 🫶 — this was version 1.4.5, dated April 14, 2011, and it's funenv(7) signing off. Byeee 💅🎀