vecChain.c
Interface between vectors and chains and regions, etc.
DESCRIPTION:
Create a vector based on the contents of the chain
RETURN VALUES:
Pointer to a VECTOR
SIGNATURE:
VECTOR *shVFromChain(
CHAIN *chain,
char *member
)
Create an array of vectors based on the contents of the chain
Three cases are handled:
1/ `member' is the name of a member of the struct in the chain,
or an element of such a member if its' an array
2/ `member' is the name a member of a member of the struct in the chain,
or an element of such a member if it's an array
3/ anything more complex
schematically,
For case 1, value = *(struct + offsetMember)
For case 2, value = *(*(struct + offsetStruct) + offsetMember)
For case 3, call shExprEval to find value
In all cases this is faster than shVFromChain as the chain is
only scanned once; in cases 1 and 2 it is _much_ faster as the
expression is only parsed once (factors of ~ 10 per element).
E.g., given
typedef struct {
int j<2>;
} FOO;
typedef struct {
int i;
int a<2>;
REGION *reg;
FOO *foo;
} TST;
then:
vectorsFromChain $tst_chain i case = 1
vectorsFromChain $tst_chain a<1> case = 1
vectorsFromChain $tst_chain foo case = 1
Error: shVectorsFromChain: TST.foo is not a primitive type
vectorsFromChain $tst_chain foo->j<0> case = 2
vectorsFromChain $tst_chain reg->nrow case = 2
vectorsFromChain $tst_chain reg->rows<1><1> case = 3
SIGNATURE:
VECTOR **
shVectorsFromChain(const CHAIN *chain, /* the CHAIN */
int nvec, /* number of desired members */
char **members) /* names of desired members */
extract some range of rows and columns of a REGION
into a VECTOR.
The rectangular region with corners (row0, col0) and (row1, col1)
is averaged over row (dirn == 0) or over column (dirn == 1). Note
that dirn == 1 gives a _vertical_ slice through the data (note that
a 1 looks a little like a column...)
As a special case, a negative value of row1 will be taken to be
nrow - |row1|
and similarily for columns
SIGNATURE:
VECTOR *
shVectorGetFromRegion(const REGION *reg, /* the region with the data */
int row0, int row1, /* row range, inclusive */
int col0, int col1, /* column range, inclusive */
int dirn, /* 0 for collapse onto a column,
1 for collapsing onto a row */
int use_median) /* use median rather than mean */
Set a regions with the contents of a vector
This replaces either a row or a col of a region with the vector
dirn = 1 is replace col, dirn = 0 replaces row
SIGNATURE:
RET_CODE
shVectorSetInRegion(const REGION *reg, /* the region with the data */
VECTOR *vec,
int row,
int col,
int dirn) /* 0 to insert row, 1 to insert col */
DESCRIPTION:
Plot one VECTOR vs. another VECTOR
RETURN VALUES:
SH_SUCCESS if successfull
SIGNATURE:
RET_CODE shVPlot(
PGSTATE *pgstate, /* where to plot it */
VECTOR *vectorX, /* vector to use for x */
VECTOR *vectorXErr, /* vector to use for x error */
VECTOR *vectorY, /* vector to use for y */
VECTOR *vectorYErr, /* vector to use for y error*/
VECTOR *vectorMask, /* mask to pick only part of data */
VECTOR *vectorSymbol, /* vector for symbol */
VECTOR *vectorColor, /* vector for color */
double xminIn, /* min value for x */
double xmaxIn, /* max value for x */
double yminIn, /* min value for y */
double ymaxIn, /* max value for y */
int xyOptMask /* XMINOPT | XMAXOPT, etc., to use above
values, not calculated ones */
)
DESCRIPTION:
Return the min or the max value in a vector, EXACT values.
Set char to "min" or "max". Use the returned values to define a HG.
RETURN VALUES:
Min or max as VECTOR_TYPE, or 0.0 if error or no min or max
SIGNATURE:
VECTOR_TYPE shVExtreme(
VECTOR *vector, /* the vector of which a limit is sought */
VECTOR *vMask, /* use only this part of vector */
char *minORmax /* set to min or max to get result */
)
DESCRIPTION:
Return the min or the max value in a vector WITH 10% buffer.
Set char to "min" or "max". Use the returned values to define a HG.
RETURN VALUES:
Min or max as VECTOR_TYPE, or 0.0 if error or no min or max
SIGNATURE:
VECTOR_TYPE shVLimit(
VECTOR *vector, /* the vector of which a limit is sought */
VECTOR *vMask, /* use only this part of vector */
char *minORmax /* set to min or max to get result */
)
DESCRIPTION:
Sets the name of the vector
RETURN VALUES:
SH_SUCCESS if successfull SH_GENERIC_ERROR if vector is null
SIGNATURE:
RET_CODE shVNameSet(
VECTOR *vector, /* the vector to set */
char* name /* what to name it */
)
DESCRIPTION:
Gets the name of the vector
RETURN VALUES:
the name of the vector, or NULL if null pointer
SIGNATURE:
char *shVNameGet(
VECTOR *vector /* the vector to get the name from */
)
DESCRIPTION:
Return either the mean or sigma of the values in a VECTOR
RETURN VALUES:
SH_SUCCESS if successfull, and the result in result
SIGNATURE:
RET_CODE shVStatistics(
VECTOR* vector, /* IN: the vector to evaluate */
VECTOR* vMask, /* IN: the vector to evaluate */
char* operation, /* IN: either "mean" or "sigma" */
VECTOR_TYPE* result /* OUT: the answer */
)
DESCRIPTION:
Find the median of the values in an vector
RETURN VALUES:
the median value
SIGNATURE:
VECTOR_TYPE shVMedian(
VECTOR *vector, /* the VECTOR to return the median of */
VECTOR *vMask /* use corresponding vector value if 1 */
)
DESCRIPTION:
Sigma clip average of an VECTOR
RETURN VALUES:
SH_SUCCESS if successful, results in mean and sqrtVar
SIGNATURE:
RET_CODE shVSigmaClip(
VECTOR *vector, /* vector to use */
VECTOR *vMask, /* mask to select part of vector */
VECTOR_TYPE sigmaClip, /* sigma clip value */
unsigned int nIter, /* number of iterations */
VECTOR_TYPE *mean, /* return: mean */
VECTOR_TYPE *sqrtVar) /* return: sqrt var */
DESCRIPTION:
Copy an vector to a chain
RETURN VALUES:
chain, or NULL if error
SIGNATURE:
/*int QbutR */ /* do a quick but risky insert */
CHAIN* shVToChain(
VECTOR *vector, /* vector to use */
CHAIN *chain, /* destination chain */
char* member /* member */
)
DESCRIPTION:
Put the values in an VECTOR in a HG
RETURN VALUES:
SH_SUCCESS; or SH_GENERIC_ERROR if there is a problem,
or vector has no data.
SIGNATURE:
RET_CODE shHgFillFromV(
HG *hg, /* the HG to accept the values */
VECTOR *vector, /* the VECTOR that is the source of values */
VECTOR *vMask /* determines what part of the vector will be used */
)
DESCRIPTION:
Create a new HG and put the values from a VECTOR into the HG.
RETURN VALUES:
Pointer to a hg if successful or NULL if Illegal VECTOR
SIGNATURE:
HG *shHgNewFromV(
VECTOR *vector, /* the VECTOR that will supply values */
VECTOR *vMask, /* what part of the vector to use */
VECTOR *vWeight, /* weight vector */
unsigned int nbin, /* the number of bins to create in HG */
VECTOR_TYPE min, /* min calculated if >= max */
VECTOR_TYPE max, /* max */
char *name /* name to give hg, vector name otherwise */
)