[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gnuastro-commits] master 6cbcae9 2/2: Book: examples for many Arithmeti
From: |
Mohammad Akhlaghi |
Subject: |
[gnuastro-commits] master 6cbcae9 2/2: Book: examples for many Arithmetic's operators |
Date: |
Wed, 11 Nov 2020 18:55:07 -0500 (EST) |
branch: master
commit 6cbcae9e9e5c731fa68ec70057d7b52fd0e6bb6b
Author: Zahra Sharbaf <zahra.sharbaf2@gmail.com>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Book: examples for many Arithmetic's operators
Until now, some of the Arithmetic's operators had examples and most of the
more basic ones didn't. However, or a first-time user, those basic ones are
the most familiar and without examples, adapting Arithmetic can be hard.
With this commit, to making usage of the Arithmetic's operator easy for
someone unfamiliar, examples are given for many of Arithmetic's operators
which did not have an example (even the simpler ones).
---
doc/gnuastro.texi | 285 +++++++++++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 261 insertions(+), 24 deletions(-)
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index f7c674e..27ba32e 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -10949,63 +10949,172 @@ The conditional operators will return pixel, or
numerical values of 0 (false) or
@item +
Addition, so ``@command{4 5 +}'' is equivalent to @mymath{4+5}.
+For example in the command below, the value 20000 is added to each pixel's
value in @file{image.fits}:
+@example
+$ astarithmetic 20000 image.fits +
+@end example
+You can also use this operator is to sum the values of one pixel in two images
(which have to be the same size).
+For example in the commands below (which are identical, see paragraph after
the commands), each pixel of @file{sum.fits} is the sum of the same pixel's
values in @file{a.fits} and @file{b.fits}.
+@example
+$ astarithmetic a.fits b.fits + -h1 -h1 --output=sum.fits
+$ astarithmetic a.fits b.fits + -g1 --output=sum.fits
+@end example
+The HDU/extension has to be specified for each image with @option{-h}.
+However, if the HDUs are the same in all inputs, you can use @option{-g} to
only specify the HDU once
@item -
Subtraction, so ``@command{4 5 -}'' is equivalent to @mymath{4-5}.
+Usage of this operator is similar to @command{+} operator, for example:
+@example
+$ astarithmetic 20000 image.fits -
+$ astarithmetic a.fits b.fits - -g1 --output=sub.fits
+@end example
@item x
Multiplication, so ``@command{4 5 x}'' is equivalent to @mymath{4\times5}.
+For example in the command below, the value of each output pixel is 5 times
its value in @file{image.fits}:
+@example
+$ astarithmetic image.fits 5 x
+@end example
+And you can multiply the value of each pixel in two images, like this:
+@example
+$ astarithmetic a.fits a.fits x -g1 –output=multip.fits
+@end example
@item /
Division, so ``@command{4 5 /}'' is equivalent to @mymath{4/5}.
+Like the multiplication, for example
+@example
+$ astarithmetic image.fits 5 -h1 /
+$ astarithmetic a.fits b.fits / -g1 –output=div.fits
+@end example
@item %
Modulo (remainder), so ``@command{3 2 %}'' is equivalent to @mymath{1}.
-Note that the modulo operator only works on integer types.
+Note that the modulo operator only works on integer types (see @ref{Numeric
data types}).
+This operator is therefore not defined for most processed astronomical
astronomical images that have floating-point value.
+However it is useful in labeled images, for example @ref{Segment output}).
+In such cases, each pixel is the integer label of the object it is associated
with hence with the example command below, we can change the labels to only be
between 1 and 4 and decrease all objects on the image to 4/5th (all objects
with a label that is a multiple of 5 will be set to 0).
+@example
+$ astarithmetic label.fits 5 1 %
+@end example
@item abs
Absolute value of first operand, so ``@command{4 abs}'' is equivalent to
@mymath{|4|}.
+For example the output of the command bellow will not have any negative pixels
(all negative pixels will be multiplied by @mymath{-1} to become positive)
+@example
+$ astarithmetic image.fits abs
+@end example
+
@item pow
First operand to the power of the second, so ``@command{4.3 5 pow}'' is
equivalent to @mymath{4.3^{5}}.
+For example with the command below all pixels will be squared
+@example
+$ astarithmetic image.fits 2 pow
+@end example
@item sqrt
The square root of the first operand, so ``@command{5 sqrt}'' is equivalent to
@mymath{\sqrt{5}}.
+Since the square root is only defined for positive values, any negative-valued
pixel will become NaN (blank).
The output will have a floating point type, but its precision is determined
from the input: if the input is a 64-bit floating point, the output will also
be 64-bit.
Otherwise, the output will be 32-bit floating point (see @ref{Numeric data
types} for the respective precision).
Therefore if you require 64-bit precision in estimating the square root,
convert the input to 64-bit floating point first, for example with @code{5
float64 sqrt}.
+For example each pixel of the output of the command below will be the square
root of that pixel in the input.
+@example
+$ astarithmetic image.fits sqrt
+@end example
+
+If you just want to scale an image with negative values using this operator
(for better visual inspection, and the actual values don't matter for you), you
can subtract the image from its minimum value, then take its square root:
+
+@example
+$ astarithmetic image.fits image.fits minvalue - sqrt -g1
+@end example
+
+Alternatively, to avoid reading the image into memory two times, you can use
the @option{set-} operator to read it into the variable @option{i} and use
@option{i} two times to speed up the operation (described below):
+
+@example
+$ astarithmetic image.fits set-i i i minvalue - sqrt
+@end example
@item log
Natural logarithm of first operand, so ``@command{4 log}'' is equivalent to
@mymath{ln(4)}.
-The output type is determined from the input, see the explanation under
@command{sqrt} for more.
+Negative pixels will become NaN, and the output type is determined from the
input, see the explanation under @command{sqrt} for more on these features.
+For example the command below will take the natural logarithm of every pixel
in the input.
+@example
+$ astarithmetic image.fits log --output=log.fits
+@end example
@item log10
-Base-10 logarithm of first operand, so ``@command{4 log10}'' is equivalent to
@mymath{\log(4)}.
-The output type is determined from the input, see the explanation under
@command{sqrt} for more.
+Base-10 logarithm of first popped operand, so ``@command{4 log}'' is
equivalent to @mymath{log_{10}(4)}.
+Negative pixels will become NaN, and the output type is determined from the
input, see the explanation under @command{sqrt} for more on these features.
+For example the command below will take the base-10 logarithm of every pixel
in the input.
+@example
+$ astarithmetic image.fits log10
+@end example
@item minvalue
-Minimum (non-blank) value in the top operand on the stack, so
``@command{a.fits minvalue}'' will push the minimum pixel value in this image
onto the stack.
-Therefore this operator is mainly intended for data (for example images), if
the top operand is a number, this operator just returns it without any change.
-So note that when this operator acts on a single image, the output will no
longer be an image, but a number.
+Minimum value in the first popped operand, so ``@command{a.fits minvalue}''
will push the minimum pixel value in this image onto the stack.
+When this operator acts on a single image, the output (operand that is put
back on the stack) will no longer be an image, but a number.
The output of this operand is in the same type as the input.
+This operator is mainly intended for multi-element datasets (for example
images or data cubes), if the popped operand is a number, it will just return
it without any change.
+
+Note that when the final remaining/output operand is a single number, it is
printed onto the standard output.
+For example with the command below the minimum pixel value in
@file{image.fits} will be printed in the terminal:
+@example
+$ astarithmetic image.fits minvalue
+@end example
+
+However, the output above also includes a lot of extra information that are
not relevant in this context.
+If you just want the final number, run Arithmetic in quiet mode:
+@example
+$ astarithmetic image.fits minvalue -q
+@end example
+
+Also see the description of @option{sqrt} for other example usages of this
operator.
@item maxvalue
-Maximum (non-blank) value of first operand in the same type, similar to
@command{minvalue}.
+Maximum value of first operand in the same type, similar to
@command{minvalue}, see the description there for more.
+For example
+@example
+$ astarithmetic image.fits maxvalue -q
+@end example
@item numbervalue
-Number of non-blank elements in first operand in the @code{uint64} type,
similar to @command{minvalue}.
+Number of non-blank elements in first operand in the @code{uint64} type (since
it is always a positive integer, see @ref{Numeric data types}).
+Its usage is similar to @command{minvalue}, for example
+@example
+$ astarithmetic image.fits numbervalue -q
+@end example
@item sumvalue
-Sum of non-blank elements in first operand in the @code{float32} type, similar
to @command{minvalue}.
+Sum of non-blank elements in first operand in the @code{float32} type.
+Its usage is similar to @command{minvalue}, for example
+@example
+$ astarithmetic image.fits sumvalue -q
+@end example
@item meanvalue
-Mean value of non-blank elements in first operand in the @code{float32} type,
similar to @command{minvalue}.
+Mean value of non-blank elements in first operand in the @code{float32} type.
+Its usage is similar to @command{minvalue}, for example
+@example
+$ astarithmetic image.fits meanvalue -q
+@end example
@item stdvalue
-Standard deviation of non-blank elements in first operand in the
@code{float32} type, similar to @command{minvalue}.
+Standard deviation of non-blank elements in first operand in the
@code{float32} type.
+Its usage is similar to @command{minvalue}, for example
+@example
+$ astarithmetic image.fits stdvalue -q
+@end example
@item medianvalue
-Median of non-blank elements in first operand with the same type, similar to
@command{minvalue}.
+Median of non-blank elements in first operand with the same type.
+Its usage is similar to @command{minvalue}, for example
+@example
+$ astarithmetic image.fits medianvalue -q
+@end example
+
@cindex NaN
@item min
@@ -11040,31 +11149,59 @@ Therefore, if the input was an integer, C's internal
type conversion will be use
For each pixel, find the maximum value in all given datasets.
The output will have the same type as the input.
This operator is called similar to the @command{min} operator, please see
there for more.
+For example
+@example
+$ astarithmetic a.fits b.fits c.fits 3 min -omax.fits
+@end example
+
@item number
For each pixel count the number of non-blank pixels in all given datasets.
The output will be an unsigned 32-bit integer datatype (see @ref{Numeric data
types}).
This operator is called similar to the @command{min} operator, please see
there for more.
+Note that some datasets may have blank values (which are also ignored in all
similar operators like @command{min}, @command{sum}, @command{mean} or
@command{median}).
+Hence final pixel values of this operator will not, in general, be equal to
the number of inputs.
+For example
+@example
+$ astarithmetic a.fits b.fits c.fits 3 number -onum.fits
+@end example
@item sum
For each pixel, calculate the sum in all given datasets.
The output will have the a single-precision (32-bit) floating point type.
This operator is called similar to the @command{min} operator, please see
there for more.
+For example
+@example
+$ astarithmetic a.fits b.fits c.fits 3 sum -ostack-sum.fits
+@end example
@item mean
For each pixel, calculate the mean in all given datasets.
The output will have the a single-precision (32-bit) floating point type.
This operator is called similar to the @command{min} operator, please see
there for more.
+For example
+@example
+$ astarithmetic a.fits b.fits c.fits 3 mean -ocoadd-mean.fits
+@end example
@item std
For each pixel, find the standard deviation in all given datasets.
The output will have the a single-precision (32-bit) floating point type.
This operator is called similar to the @command{min} operator, please see
there for more.
+For example
+@example
+$ astarithmetic a.fits b.fits c.fits 3 std -ostd.fits
+@end example
@item median
For each pixel, find the median in all given datasets.
The output will have the a single-precision (32-bit) floating point type.
This operator is called similar to the @command{min} operator, please see
there for more.
+For example
+@example
+$ astarithmetic a.fits b.fits c.fits 3 mean \
+ --output=stack-median.fits
+@end example
@item quantile
For each pixel, find the quantile from all given datasets.
@@ -11101,16 +11238,28 @@ astarithmetic a.fits b.fits c.fits 3 5 0.2
sigclip-number
For each pixel, find the sigma-clipped median in all given datasets.
The output will have the a single-precision (32-bit) floating point type.
This operator is called similar to the @command{sigclip-number} operator,
please see there for more.
+For example
+@example
+astarithmetic a.fits b.fits c.fits 3 5 0.2 sigclip-median
+@end example
@item sigclip-mean
For each pixel, find the sigma-clipped mean in all given datasets.
The output will have the a single-precision (32-bit) floating point type.
This operator is called similar to the @command{sigclip-number} operator,
please see there for more.
+For example
+@example
+astarithmetic a.fits b.fits c.fits 3 5 0.2 sigclip-mean
+@end example
@item sigclip-std
For each pixel, find the sigma-clipped standard deviation in all given
datasets.
The output will have the a single-precision (32-bit) floating point type.
This operator is called similar to the @command{sigclip-number} operator,
please see there for more.
+For example
+@example
+astarithmetic a.fits b.fits c.fits 3 5 0.2 sigclip-std
+@end example
@item filter-mean
Apply mean filtering (or @url{https://en.wikipedia.org/wiki/Moving_average,
moving average}) on the input dataset.
@@ -11279,23 +11428,54 @@ The unique elements of the dataset will be stored in
a single-dimensional datase
Recall that by default, single-dimensional datasets are stored as a table
column in the output.
But you can use @option{--onedasimage} or @option{--onedonstdout} to
respectively store them as a single-dimensional FITS array/image, or to print
them on the standard output.
+Although you can use this operator on the floating point dataset, due to
floating-point errors it may give non-reasonable values: because the tenth
digit of the decimal point is also considered although it may be statistically
meaningless, see @ref{Numeric data types}.
+It is therefore better/recommended to use it on the integer dataset like the
labeled images of @ref{Segment output} where each pixel has the integer label
of the object/clump it is associated with.
+For example let's assume you have cropped a region of a larger labeled image
and want to find the labels/objects that are within the crop.
+With this operator, this job is trivial:
+@example
+$ astarithmetic seg-crop.fits unique
+@end example
+
@item erode
@cindex Erosion
Erode the foreground pixels (with value @code{1}) of the input dataset (second
popped operand).
The first popped operand is the connectivity (see description in
@command{connected-components}).
Erosion is simply a flipping of all foreground pixels (with value @code{1}) to
background (with value @code{0}) that are ``touching'' background pixels.
``Touching'' is defined by the connectivity.
-In effect, this carves off the outer borders of the foreground, making them
thinner.
-This operator assumes a binary dataset (all pixels are @code{0} and @code{1}).
+
+In effect, this operator ``carves off'' the outer borders of the foreground,
making them thinner.
+This operator assumes a binary dataset (all pixels are @code{0} or @code{1}).
+For example, imagine that you have an astronomical image with a mean/sky value
of 0 units and a standard deviation (@mymath{\sigma}) of 100 units and many
galaxies in it.
+With the first command below, you can apply a threshold of @mymath{2\sigma} on
the image (by only keeping pixels that are greater than 200 using the
@command{gt} operator).
+The output of thresholding the image is a binary image (each pixel is either
smaller or equal to the threshold or larger than it).
+You can then erode the binary image with the second command below to remove
very small false positives (one or two pixel peaks).
+@example
+$ astarithmetic image.fits 100 gt -obinary.fits
+$ astarithmetic binary.fits 2 erode -oout.fits
+@end example
+
+Infact, you can merge these operations into one command thanks to the reverse
polish notation (see @ref{Reverse polish notation}):
+@example
+$ astarithmetic image.fits 100 gt 2 erode -oout.fits
+@end example
+
+To see the effect of connectivity, try this:
+@example
+$ astarithmetic image.fits 100 gt 1 erode -oout-con-1.fits
+@end example
@item dilate
@cindex Dilation
-Dilate the foreground pixels (with value @code{1}) of the input dataset
(second popped operand).
+Dilate the foreground pixels (with value @code{1}) of the binary input dataset
(second popped operand).
The first popped operand is the connectivity (see description in
@command{connected-components}).
Dilation is simply a flipping of all background pixels (with value @code{0})
to foreground (with value @code{1}) that are ``touching'' foreground pixels.
``Touching'' is defined by the connectivity.
In effect, this expands the outer borders of the foreground.
This operator assumes a binary dataset (all pixels are @code{0} and @code{1}).
+The usage is similar to @code{erode}, for example:
+@example
+$ astarithmetic binary.fits 2 erode -oout.fits
+@end example
@item connected-components
@cindex Connected components
@@ -11322,56 +11502,113 @@ If your input dataset doesn't have a binary type,
but you know all its values ar
@item fill-holes
Flip background (0) pixels surrounded by foreground (1) in a binary dataset.
-This operator takes two operands (similar to @code{connected-components}): the
first popped operand is the connectivity (to define a hole) and the second is
the binary (0 or 1 valued) dataset to fill holes in.
+This operator takes two operands (similar to @code{connected-components}): the
second is the binary (0 or 1 valued) dataset to fill holes in and the first
popped operand is the connectivity (to define a hole).
+Imagine that in your dataset there are some holes with zero value inside the
objects with one value (for example the output of the thresholding example of
@command{erode}) and you want to fill the holes:
+@example
+$ astarithmetic binary.fits 2 fill-holes
+@end example
@item invert
-Invert an unsigned integer dataset.
+Invert an unsigned integer dataset (won't work on other data types, see
@ref{Numeric data types}).
This is the only operator that ignores blank values (which are set to be the
maximum values in the unsigned integer types).
This is useful in cases where the target(s) has(have) been imaged in
absorption as raw formats (which are unsigned integer types).
With this option, the maximum value for the given type will be subtracted from
each pixel value, thus ``inverting'' the image, so the target(s) can be treated
as emission.
This can be useful when the higher-level analysis methods/tools only work on
emission (positive skew in the noise, not negative).
+@example
+$ astarithmetic image.fits invert
+@end example
@item lt
-Less than: If the second popped (or left operand in infix notation, see
@ref{Reverse polish notation}) value is smaller than the first popped operand,
then this function will return a value of 1, otherwise it will return a value
of 0.
+Less than: creates a binary output (values either 0 or 1) where each pixel
will be 1 if the second popped operand is smaller than the first popped operand
and 0 otherwise.
If both operands are images, then all the pixels will be compared with their
counterparts in the other image.
+For example:
+@example
+$ astarithmetic image1.fits image2.fits -g1 lt
+@end example
If only one operand is an image, then all the pixels will be compared with the
single value (number) of the other operand.
+For example:
+@example
+$ astaithmetic image1.fits 1000 lt
+@end example
Finally if both are numbers, then the output is also just one number (0 or 1).
-When the output is not a single number, it will be stored as an @code{unsigned
char} type.
+@example
+$ astarithmetic 4 5 lt
+@end example
+
@item le
Less or equal: similar to @code{lt} (`less than' operator), but returning 1
when the second popped operand is smaller or equal to the first.
+For example
+@example
+$ astaithmetic image1.fits 1000 le
+@end example
@item gt
Greater than: similar to @code{lt} (`less than' operator), but returning 1
when the second popped operand is greater than the first.
+For example
+@example
+$ astaithmetic image1.fits 1000 gt
+@end example
@item ge
Greater or equal: similar to @code{lt} (`less than' operator), but returning 1
when the second popped operand is larger or equal to the first.
+For example
+@example
+$ astaithmetic image1.fits 1000 ge
+@end example
@item eq
-Equality: similar to @code{lt} (`less than' operator), but returning 1 when
the two popped operands are equal (to double precision floating point
-accuracy).
+Equality: similar to @code{lt} (`less than' operator), but returning 1 when
the two popped operands are equal (to double precision floating point accuracy).
+@example
+$ astaithmetic image1.fits 1000 eq
+@end example
@item ne
Non-Equality: similar to @code{lt} (`less than' operator), but returning 1
when the two popped operands are @emph{not} equal (to double precision floating
point accuracy).
+@example
+$ astaithmetic image1.fits 1000 ne
+@end example
@item and
Logical AND: returns 1 if both operands have a non-zero value and 0 if both
are zero.
-Both operands have to be the same kind: either both images or both numbers.
+Both operands have to be the same kind: either both images or both numbers and
it mostly makes meaningful values when the inputs are binary (with pixel values
of 0 or 1).
+@example
+$ astarithmetic image1.fits image2.fits -g1 and
+@end example
+
+For example if you only want to see which pixels in an image have a value
@emph{between} 50 (greater equal, or inclusive) and 200 (less than, or
exclusive), you can use this command:
+@example
+$ astarithmetic image.fits set-i i 50 ge i 200 lt and
+@end example
@item or
Logical OR: returns 1 if either one of the operands is non-zero and 0 only
when both operators are zero.
Both operands have to be the same kind: either both images or both numbers.
+The usage is similar to @code{and}.
+
+For example if you only want to see which pixels in an image have a value
@emph{outside of} -100 (greater equal, or inclusive) and 200 (less than, or
excuslive), you can use this command:
+@example
+$ astarithmetic image.fits set-i i -100 lt i 200 ge or
+@end example
@item not
-Logical NOT: returns 1 when the operand is zero and 0 when the operand is
non-zero.
+Logical NOT: returns 1 when the operand is 0 and 0 when the operand is
non-zero.
The operand can be an image or number, for an image, it is applied to each
pixel separately.
+For example if you want to know which pixels are not blank, you can use not on
the output of the @command{isblank} operator described below:
+@example
+$ astarithmetic image.fits isblank not
+@end example
@cindex Blank pixel
@item isblank
Test for a blank value (see @ref{Blank pixels}).
In essence, this is very similar to the conditional operators: the output is
either 1 or 0 (see the `less than' operator above).
The difference is that it only needs one operand.
+For example:
+@example
+$ astarithmetic image.fits isblank
+@end example
Because of the definition of a blank pixel, a blank value is not even equal to
itself, so you cannot use the equal operator above to select blank pixels.
See the ``Blank pixels'' box below for more on Blank pixels in Arithmetic.