dimension.h

/* Copyright (C) 2018 Chris Piker <chris-piker@uiowa.edu>
 *
 * This file is part of libdas2, the Core Das2 C Library.
 *
 * Libdas2 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.
 *
 * Libdas2 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 libdas2; if not, see <http://www.gnu.org/licenses/>.
 */

#ifndef _das_dimension_h_
#define _das_dimension_h_

#include <das2/descriptor.h>
#include <das2/variable.h>

#ifdef __cplusplus
extern "C" {
#endif

#define DASDIM_MAXDEP 16  // Arbitrary decision, can be changed
#define DASDIM_MAXVAR 16  // Another arbitrary changable descision

   
/* 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 
 * call to new_DasVarBinary() 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
 */
   
#ifndef _das_dimension_c_  
extern const char* DASVAR_CENTER;
extern const char* DASVAR_MIN;
extern const char* DASVAR_MAX;
extern const char* DASVAR_WIDTH;
extern const char* DASVAR_MEAN;   /* all these can substitute for the center    */
extern const char* DASVAR_MEDIAN; /* if the center is missing but they are      */
extern const char* DASVAR_MODE;   /* distinct so it's good to include them here */
extern const char* DASVAR_REF; 
extern const char* DASVAR_OFFSET; 
extern const char* DASVAR_MAXERR; 
extern const char* DASVAR_MINERR;
extern const char* DASVAR_UNCERT;
extern const char* DASVAR_STD_DEV;
extern const char* DASVAR_SPREAD;
extern const char* DASVAR_WEIGHT;
#endif

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 */
   char sId[64];           /* A name for this dimension */
   
   /* 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 
    * indicies */
   int iFirstInternal;
   
   /* The variables which supply data for this dimension */
   DasVar* aVars[DASDIM_MAXVAR];
   char aRoles[DASDIM_MAXVAR][32];
   size_t uVars;
   
   /* For dependent variables (i.e. data) pointers to relavent 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
    * DasVar_orthoginalTo() when printing coordinate information */
   /* struct das_dim* aCoords[DASDIM_MAXDEP];
   size_t uCoords;*/
} DasDim;


DasDim* new_DasDim(const char* sId, enum dim_type dtype, int nRank);

const char* DasDim_id(const DasDim* pThis);


char* DasDim_toStr(const DasDim* pThis, char* sBuf, int nLen);

int DasDim_copyInProps(DasDim* pThis, char cAxis, const DasDesc* pOther);


bool DasDim_addVar(DasDim* pThis, const char* sRole, DasVar* pVar);


const DasVar* DasDim_getVar(const DasDim* pThis, const char* sRole);

const DasVar* DasDim_getPointVar(const DasDim* pThis);


DasVar* DasDim_popVar(DasDim* pThis, const char* role);

void del_DasDim(DasDim* pThis);


int DasDim_shape(const DasDim* pThis, ptrdiff_t* pShape);


ptrdiff_t DasDim_lengthIn(const DasDim* pThis, int nIdx, ptrdiff_t* pLoc);


#ifdef __cplusplus
}
#endif

#endif /* _das_dimension_h_ */