Skip to content

Commit

Permalink
rtd doxygen format and clean up
Browse files Browse the repository at this point in the history 
* doxygen format on TECA_ALGORITHM_PROPERTY and other similar macros
* remove X_fwd.h files
* remove @anchor and @ref on algorithm, properties because anchor names
  need to be unique project wide.
* more doxygen formatting of classes
  • Loading branch information
@burlen
burlen committed May 5, 2021
1 parent ecc9895 commit f589c19
Show file tree
Hide file tree
Showing 91 changed files with 1,857 additions and 1,583 deletions.
103 changes: 60 additions & 43 deletions alg/teca_2d_component_area.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,40 +10,40 @@

TECA_SHARED_OBJECT_FORWARD_DECL(teca_2d_component_area)

/// an algorithm that computes the area of labeled regions
/// An algorithm that computes the areas of labeled regions
/**
Given a set of labels on a Cartesian mesh, the algorithm computes the area of
each region. Regions are identified by assigning a unique integer value to each
mesh point that belongs in the region. The component_variable property names
the variable containing the region labels.
if the region labels start at 0 and are contiguous then an optimization can be
used. Set contiguous_component_ids property to enable the optimization. Note that
TECA's connected component labeler assigns the background (i.e. cells not inside
the segmentation) the label 0. One can identify the background region and area
via this label. When processing data generated outside of TECA it might be
necessary to supply the background label. Use -2 if there is no background.
the input dataset is passed through and the results of the calculations are
stored in the output dataset metadata in the following keys:
number_of_components - number of component ids for which area was
computed. Note that this can include a background
component i.e. for cells outside of the segmentation.
component_ids - a vector containing the label of each component. This is
always starts with 0, where the label 0 identifies cells
out side of the segmentation, and ranges up to
number_of_components - 1, where the labels from 1 up to
number_of_components - 1 identify connected regions of
cells inside the segmentation.
component_area - a vector containing the area for the corresponding entry
in the component_ids array.
background_id - the label used for cells outside of the segmentation,
i.e. the background. This can be used to skip processing
of the background when desirable.
* Given a set of labels on a Cartesian mesh, the algorithm computes the area
* of each region. Regions are identified by assigning a unique integer value
* to each mesh point that belongs in the region. The component_variable
* property names the variable containing the region labels.
*
* if the region labels start at 0 and are contiguous then an optimization can
* be used. Set contiguous_component_ids property to enable the optimization.
* Note that TECA's connected component labeler assigns the background (i.e.
* cells not inside the segmentation) the label 0. One can identify the
* background region and area via this label. When processing data generated
* outside of TECA it might be necessary to supply the background label. Use -2
* if there is no background.
*
* the input dataset is passed through and the results of the calculations are
* stored in the output dataset metadata in the following keys:
*
* | name | description |
* | ---- | ----------- |
* | number_of_components | number of component ids for which area was |
* | | computed. Note that this can include a background |
* | | component i.e. for cells outside of the segmentation. |
* | component_ids | a vector containing the label of each component. This is |
* | | always starts with 0, where the label 0 identifies |
* | | cells out side of the segmentation, and ranges up |
* | | to number_of_components - 1, where the labels from |
* | | 1 up to number_of_components - 1 identify |
* | | connected regions of cells inside the segmentation. |
* | component_area | a vector containing the area for the corresponding |
* | | entry in the component_ids array. |
* | background_id | the label used for cells outside of the segmentation, |
* | | i.e. the background. This can be used to skip processing |
* | | of the background when desirable. |
*/
class teca_2d_component_area : public teca_algorithm
{
Expand All @@ -53,23 +53,40 @@ class teca_2d_component_area : public teca_algorithm
TECA_ALGORITHM_CLASS_NAME(teca_2d_component_area)
~teca_2d_component_area();

// report/initialize to/from Boost program options objects.
/** @name program_options
* report/initialize to/from Boost program options objects.
*/
///@{
TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
TECA_SET_ALGORITHM_PROPERTIES()
///@}

// set the name of the input array
/** @name component_variable
* Sets the name of the array containing component labels to compute the
* area of.
*/
///@{
TECA_ALGORITHM_PROPERTY(std::string, component_variable)
///@}

// set this only if you know for certain that label ids are contiguous and
// start at 0. this enables use of a faster implementation.
/** @name contiguous_component_ids
* set this only if you know for certain that label ids are contiguous and
* start at 0. this enables use of a faster implementation.
*/
///@{
TECA_ALGORITHM_PROPERTY(int, contiguous_component_ids)

// set this to override the component label used for background. By default
// this is set to -1 to indicate that the value should be obtained from the
// metadata key `background_id`. Note that TECA's connected component
// labeler uses the id 0 for the background and passes this in a metadata
// key and as a result no action is required.
///@}

/** @name background_id
* set this to override the component label used for background. By default
* this is set to -1 to indicate that the value should be obtained from the
* metadata key `background_id`. Note that TECA's connected component
* labeler uses the id 0 for the background and passes this in a metadata
* key and as a result no action is required.
*/
///@{
TECA_ALGORITHM_PROPERTY(long, background_id)
///@}

protected:
teca_2d_component_area();
Expand Down
9 changes: 3 additions & 6 deletions alg/teca_apply_binary_mask.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,25 +43,22 @@ class teca_apply_binary_mask : public teca_algorithm
TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
TECA_SET_ALGORITHM_PROPERTIES()

/** @anchor mask_variable
* @name mask_variable
/** @name mask_variable
* set the name of the variable containing the mask values
*/
///@{
TECA_ALGORITHM_PROPERTY(std::string, mask_variable)
///@}

/** @anchor masked_variable
* @name masked_variable
/** @name masked_variable
* A list of of variables to apply the mask to. If empty no arrays will be
* requested, and no variables will be masked
*/
///@{
TECA_ALGORITHM_VECTOR_PROPERTY(std::string, masked_variable)
///@}

/** @anchor output_variable_prefix
* @name output_variable_prefix
/** @name output_variable_prefix
* A prefix for the names of the variables that have been masked. If this
* is empty masked data replaces its input, otherwise input data is
* preserved and masked data is added.
Expand Down
101 changes: 61 additions & 40 deletions alg/teca_bayesian_ar_detect.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,36 +10,35 @@

TECA_SHARED_OBJECT_FORWARD_DECL(teca_bayesian_ar_detect)

/// TECA BARD atmospheric river detector
/// The TECA BARD atmospheric river detector.
/**
Given a point wise IVT (integrated vapor transport) field and a training
parameter table computes the point wise probability of an atmospheric river
using the TECA BARD algorithm.
Required inputs:
1. IVT (integrated vapor transport) array on a Cartesian nesh.
2. a compatible parameter table. columns of which are : min IVT,
component area, HWHM lattitude
The names of the input varibale and columns can be specified at run time
through algorithm properties.
Produces:
A Cartesian mesh with probability of an AR stored in the point centered
array named "ar_probability". The diagnostic quantites "ar_count" amd
"parameter_table_row" are stored in information arrays.
For more information see:
O’Brien, T. A., Risser, M. D., Loring, B., Elbashandy, A. A., Krishnan, H.,
Johnson, J., Patricola, C. M., O’Brien, J. P., Mahesh, A., Arriaga Ramirez,
S., Rhoades, A. M., Charn, A., Inda Díaz, H., & Collins, W. D. (2020).
Detection of atmospheric rivers with inline uncertainty quantification:
TECA-BARD v1.0.1. Geoscientific Model Development, 13(12), 6131–6148.
https://doi.org/10.5194/gmd-13-6131-2020
* Given a point wise IVT (integrated vapor transport) field and a training
* parameter table computes the point wise probability of an atmospheric river
* using the TECA BARD algorithm.
*
* Required inputs:
*
* 1. IVT (integrated vapor transport) array on a Cartesian nesh.
* 2. a compatible parameter table. columns of which are : min IVT,
* component area, HWHM lattitude
*
* The names of the input varibale and columns can be specified at run time
* through algorithm properties.
*
* Produces:
*
* A Cartesian mesh with probability of an AR stored in the point centered
* array named "ar_probability". The diagnostic quantites "ar_count" amd
* "parameter_table_row" are stored in information arrays.
*
* For more information see:
*
* O’Brien, T. A., Risser, M. D., Loring, B., Elbashandy, A. A., Krishnan, H.,
* Johnson, J., Patricola, C. M., O’Brien, J. P., Mahesh, A., Arriaga Ramirez,
* S., Rhoades, A. M., Charn, A., Inda Díaz, H., & Collins, W. D. (2020).
* Detection of atmospheric rivers with inline uncertainty quantification:
* TECA-BARD v1.0.1. Geoscientific Model Development, 13(12), 6131–6148.
* https://doi.org/10.5194/gmd-13-6131-2020
*/
class teca_bayesian_ar_detect : public teca_algorithm
{
Expand All @@ -54,32 +53,54 @@ class teca_bayesian_ar_detect : public teca_algorithm
TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
TECA_SET_ALGORITHM_PROPERTIES()

// set the name of the input array
/** @name ivt_variable
* Sets the name of the array containing the IVT field to detect ARs in.
*/
///@{
TECA_ALGORITHM_PROPERTY(std::string, ivt_variable)
///@}

// set the names of columns in the parameter table.
/** @name min_ivt_variable
* Set the names of the minimum IVT column in the parameter table.
*/
///@{
TECA_ALGORITHM_PROPERTY(std::string, min_ivt_variable)
///@}

/** @name min_component_area_variable
* Set the names of the minimum area column in the parameter table.
*/
///@{
TECA_ALGORITHM_PROPERTY(std::string, min_component_area_variable)
///@}

/** @name hwhm_latitude_variable
* Set the names of the HWHM column in the parameter table.
*/
///@{
TECA_ALGORITHM_PROPERTY(std::string, hwhm_latitude_variable)
///@}

/** @anchor probability variable
* @name probability variable
/** @name probability variable
* Set the name of the variable to store output probability as.
*/
///@{
TECA_ALGORITHM_PROPERTY(std::string, ar_probability_variable)
///@}

// set/get the number of threads in the pool. setting
// to -1 results in a thread per core factoring in all MPI
// ranks running on the node. the default is -1.
/** Set the number of threads in the pool. Setting to -1 results in a
* thread per core factoring in all MPI ranks running on the node. the
* default is -1.
*/
void set_thread_pool_size(int n_threads);

/// Get the number of threads in the pool.
unsigned int get_thread_pool_size() const noexcept;

// override the input connections because we are going to
// take the first input and use it to generate metadata.
// the second input then becomes the only one the pipeline
// knows about.
/** override the input connections because we are going to take the first
* input and use it to generate metadata. the second input then becomes
* the only one the pipeline knows about.
*/
void set_input_connection(unsigned int id,
const teca_algorithm_output_port &port) override;

Expand Down
12 changes: 8 additions & 4 deletions alg/teca_bayesian_ar_detect_parameters.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,16 @@ class teca_bayesian_ar_detect_parameters : public teca_algorithm
TECA_GET_ALGORITHM_PROPERTIES_DESCRIPTION()
TECA_SET_ALGORITHM_PROPERTIES()

// control the number of rows copied into the table. The rows are
// copied in sequential order starting from row zero. The default value
// of -1 is used to serve all rows. See also get_parameter_table_size.
/** @name number_of_rows
* control the number of rows copied into the table. The rows are copied
* in sequential order starting from row zero. The default value of -1 is
* used to serve all rows. See also get_parameter_table_size.
*/
///@{
TECA_ALGORITHM_PROPERTY(long, number_of_rows)
///@}

// return the number of rows in the internal parameter table.
/// return the number of rows in the internal parameter table.
unsigned long get_parameter_table_size();

protected:
Expand Down
Loading

0 comments on commit f589c19

Please sign in to comment.