dimension.h

/* Copyright (C) 2018 Chris Piker <chris-piker@uiowa.edu>
 *
 * This file is part of das2C, the Core Das2 C Library.
 *
 * Das2C is free software; you can redistribute it and/or modify it under
 * the terms of the GNU Lesser General Public License version 2.1 as published
 * by the Free Software Foundation.
 *
 * Das2C is distributed in the hope that it will be useful, but WITHOUT ANY
 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
 * more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * version 2.1 along with das2C; if not, see <http://www.gnu.org/licenses/>.
 */
 
#ifndef _das_dimension_h_
#define _das_dimension_h_
 
#include <das3/descriptor.h>
#include <das3/variable.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define DASDIM_MAXDEP 16   // Arbitrary decision, can be changed
#define DASDIM_MAXVAR 16   // Another arbitrary changeable decision
#define DASDIM_NAXES 4     // can change later
#define DASDIM_AXLEN 4     // Instead of single character so we can handle utf-8
 
   
/* OFFSET and REFERENCE variable roles were a tough call.  In the end you only
 * need center values to do DFT's.  The DFT code should look at the coordinate
 * series and see what if it has a constant change in index.  If so, you can do
 * a DFT, otherwise you can't.
 * 
 * Currently in das 2.2 land we know that one "package" of values is a
 * continuous waveform set.  We can look at the yTags, see if they are
 * consistent and the if they are then we can transform.  It's very clear when
 * we can do this, but it's also it requires a very specific data structure. 
 * So in a general data model, how do you get the yTags?  You *can* do it with a 
 * morphology check but those tend to be a rabbit hole of exploding if
 * statements.
 * 
 * The initial thought was to have offset dimensions, but that caused a massive
 * symmetry break in the data model.  Why have a rule that always combines two
 * dimensions with a + operator?  Why not other operators?  Also, if you set 
 * say the the "STD_DEV" variable in the reference dimension and also in the
 * offset dimension, how do you combine those?  It seems offset dimensions
 * trigger more problems then they solve.
 * 
 * The solution taken here is to introduce two variable roles, REFERENCE and
 * OFFSET.  Since this choice only requires adding two string constants it can
 * be ignored if turns out it's a bad choice.  Otherwise it simplifies the
 * concept of  breaking down values into a reference point that may change for
 * each packet and a set of fixed offsets.  These sorts of coordinates come up
 * a lot in our work, for example frequency values for down-mixed data, radar
 * return altitudes and waveform captures.
 * 
 * DASVAR_CENTER should still be provided for client codes that don't understand
 * the offset and reference semantic.  And since this can be done with one 
 * operation set without exploding the network data volume 
 * it doesn't seem like that much of a burden.
 * 
 * Another approach would have been to expand properties to include an 
 * index/value relationship section.  We could define things like constant 
 * change of value for a change in a certain index and then define if rolling
 * the next index up is the same change as the lower index roll.  This seemed
 * like a much more complicated idea and didn't work so well with offsets that
 * are constant by record (i.e. the i value) but not constant by value index
 * (j,k,l ...).
 * -cwp
 */
   
DAS_API extern const char* DASVAR_CENTER;
DAS_API extern const char* DASVAR_MIN;
DAS_API extern const char* DASVAR_MAX;
DAS_API extern const char* DASVAR_WIDTH;
DAS_API extern const char* DASVAR_MEAN;   /* all these can substitute for the center    */
DAS_API extern const char* DASVAR_MEDIAN; /* if the center is missing but they are      */
DAS_API extern const char* DASVAR_MODE;   /* distinct so it's good to include them here */
DAS_API extern const char* DASVAR_REF; 
DAS_API extern const char* DASVAR_OFFSET; 
DAS_API extern const char* DASVAR_MAX_ERR;
DAS_API extern const char* DASVAR_MIN_ERR;
DAS_API extern const char* DASVAR_STD_DEV;
/* A binner that averages already-averaged data has to know how many 
   measurements are in each bin or sparse bin weigh as much as full ones. */
DAS_API extern const char* DASVAR_COUNT;
DAS_API extern const char* DASVAR_WEIGHT;
 
DAS_API extern const char* DASVAR_NORM;
 
/* Withheld until the math exists.  point_spread has no formalism to
   interpret it, so naming it would promise handling das2C does not have:
   extern const char* DASVAR_SPREAD;
 */
 
 
#define DASDIM_ROLE_SZ 32
 
enum dim_type { DASDIM_UNK = 0, DASDIM_COORD, DASDIM_DATA };
 
typedef struct das_dim {
   DasDesc base;        /* Attributes or properties for this variable */
   enum dim_type dtype;    /* Coordinate or Data flag */
   
   /* A name for this particular variable group, cannot repeat in the dataset */
   char sId[DAS_MAX_ID_BUFSZ]; 
 
   /* A general dimension category such as 'B', 'E', etc */
   char sDim[DAS_MAX_ID_BUFSZ]; 
 
   /* Display Info: Plot axes affinity, if any. For variables that have no
    * internal indices, only the first axis make any sense.  Multiple axis 
    * entries are possible because this dimension may contain a vector.
    *
    * A common example of a vector is a "space" dimension defined by a 
    * 3-vector.
    */
   char axes[DASDIM_NAXES][DASDIM_AXLEN];
 
   /* Display info: Is this the primary coordinate for a given axes */
   bool primary;
 
   /* Holds the max index to report out of this dimension.
    * The dimension may have internal indices beyond these
    * but they are not correlated with the overall dataset 
    * indices */
   int iFirstInternal;
   
   /* The variables which supply data for this dimension */
   DasVar* aVars[DASDIM_MAXVAR];
   char aRoles[DASDIM_MAXVAR][DASDIM_ROLE_SZ];
   size_t uVars;
   
   /* For dependent variables (i.e. data) pointers to relevant independent
    * dimensions are here.  I don't think we need this here as the dataset
    * provides this information.  Going to punt it for now but will use
    * orthogonality checks when printing coordinate information */
   /* struct das_dim* aCoords[DASDIM_MAXDEP];
   size_t uCoords;*/
 
   void* pUser;
} DasDim;
 
DAS_API DasDim* new_DasDim(const char* sDim, const char* sName, enum dim_type dtype, int nRank);
 
 
#define DasDim_dim(P) ((const char*)((P)->sDim))
#define DasDim_id(P)  ((const char*)((P)->sId))
 
#define DasDim_type(P) ((P)->dtype)
 
#define DasDim_typeName(P) (((P)->dtype == DASDIM_COORD) ? "coord" : "data" )
 
DAS_API int DasDim_numAxes(const DasDim* pThis);
 
DAS_API DasErrCode DasDim_setAxis(DasDim* pThis, int iAxis, const char* sAxis);
 
#define DasDim_getAxis(P,I) ( (P)->axes[I][0] != '\0' ?  (const char*) ((P)->axes[I]) : NULL )
 
DAS_API void DasDim_setAxes(DasDim* pThis, const DasDim* pOther);
 
#define DasDim_hasAxes(P) ((P)->axes[0] != '\0')
 
#define DasDim_primeCoord(P, B) ((P)->primary = B)
 
#define DasDim_isPrimeCoord(P)  ((P)->primary)
 
DAS_API int DasDim_info(const DasDim* pThis, char* sBuf, size_t uLen);
 
DAS_API char* DasDim_toStr(const DasDim* pThis, char* sBuf, size_t uLen);
 
/* Write this dimension's das3 <coord>/<data> element.  Not DAS_API, the
   dataset header writer in dataset.c is the caller, user code writes whole
   datasets with DasIO_writeDesc(). */
DasErrCode DasDim_encode(DasDim* pThis, DasBuf* pBuf);
 
DAS_API bool DasDim_isKnownRole(const char* sPurpose);
 
DAS_API const char* das_role_fromStr(const char* sRole);
 
DAS_API bool DasDim_addVar(DasDim* pThis, const char* sRole, DasVar* pVar);
 
 
DAS_API DasVar* DasDim_getVar(DasDim* pThis, const char* sRole);
 
 
#define DasDim_numVars(P) ((P)->uVars)
 
#define DasDim_getVarByIdx(P, I) ( (I)<((P)->uVars) ? ((DasVar*)((P)->aVars[(I)])) : NULL )
 
#define DasDim_getRoleByIdx(P, I) ( (I)<((P)->uVars) ? ((const char*)((P)->aRoles[(I)])) : NULL )
 
 
 
DAS_API DasVar* DasDim_getPointVar(DasDim* pThis);
 
 
DAS_API DasVar* DasDim_popVar(DasDim* pThis, const char* role);
 
DAS_API void del_DasDim(DasDim* pThis);
 
 
DAS_API int DasDim_shape(const DasDim* pThis, ptrdiff_t* pShape);
 
 
DAS_API ptrdiff_t DasDim_lengthIn(const DasDim* pThis, int nIdx, ptrdiff_t* pLoc);
 
 
DAS_API bool DasDim_degenerate(const DasDim* pThis, int iIndex);
 
 
#ifdef __cplusplus
}
#endif
 
#endif /* _das_dimension_h_ */