DependentVariable

group DependentVariable

Object model and operations for a dataset’s dependent variable.

Type & Copying

OCTypeID DependentVariableGetTypeID(void)

Retrieve the unique OCTypeID for DependentVariable.

Returns:: Type identifier.

DependentVariableRef DependentVariableCopy(DependentVariableRef orig)

Create a deep (immutable) copy of an existing DependentVariable.

Parameters:

orig – Source object.

Returns:

New DependentVariableRef, or NULL on failure.

DependentVariableRef DependentVariableCreateComplexCopy(DependentVariableRef src, OCTypeRef owner)

Like CreateCopy, but ensures the result is complex-typed.

Parameters:

src – Source object.
owner – Optional back-pointer owner.

Returns:

New complex-typed DependentVariableRef.

Creation

DependentVariableRef DependentVariableCreate(OCStringRef name, OCStringRef description, SIUnitRef unit, OCStringRef quantityName, OCStringRef quantityType, OCNumberType elementType, OCArrayRef componentLabels, OCArrayRef components, OCStringRef *outError)

Construct an “internal” DependentVariable (data copied).

Parameters:

name – Optional human-readable name.
description – Optional longer description.
unit – SI unit (NULL→dimensionless).
quantityName – Logical quantity name (e.g. “temperature”).
quantityType – Semantic type (“scalar”, “vector_N”, etc.).
elementType – Numeric storage type (kOCNumberFloat64Type, etc.).
componentLabels – Optional array of OCStringRef labels.
components – Array of OCDataRef buffers.
outError – Optional pointer for error message.

Returns:

New DependentVariableRef or NULL on validation/alloc error.

DependentVariableRef DependentVariableCreateWithComponentsNoCopy(OCStringRef name, OCStringRef description, SIUnitRef unit, OCStringRef quantityName, OCStringRef quantityType, OCNumberType elementType, OCArrayRef componentLabels, OCArrayRef components, OCStringRef *outError): Same as Create, but does not copy the provided data buffers.

DependentVariableRef DependentVariableCreateWithSize(OCStringRef name, OCStringRef description, SIUnitRef unit, OCStringRef quantityName, OCStringRef quantityType, OCNumberType elementType, OCArrayRef componentLabels, OCIndex size, OCStringRef *outError)

Pre-allocate a new “internal” DependentVariable of given size (zero-filled).

Parameters:

name – Optional human-readable name.
description – Optional longer description.
unit – SI unit (NULL→dimensionless).
quantityName – Logical quantity name.
quantityType – Semantic type.
elementType – Numeric storage type.
componentLabels – Optional labels.
size – Number of elements per component.
outError – Optional pointer for error message.

DependentVariableRef DependentVariableCreateDefault(OCStringRef quantityType, OCNumberType elementType, OCIndex size, OCStringRef *outError): Minimal defaults constructor: scalar/pixel/vector by quantityType + size.

DependentVariableRef DependentVariableCreateWithComponent(OCStringRef name, OCStringRef description, SIUnitRef unit, OCStringRef quantityName, OCNumberType elementType, OCArrayRef componentLabels, OCDataRef component, OCStringRef *outError): Single-component convenience constructor.

DependentVariableRef DependentVariableCreateExternal(OCStringRef name, OCStringRef description, SIUnitRef unit, OCStringRef quantityName, OCStringRef quantityType, OCNumberType elementType, OCStringRef componentsURL, OCStringRef *outError): Construct an “external” DependentVariable (blobs fetched from URL).

DependentVariableRef DependentVariableCreateMinimal(SIUnitRef unit, OCStringRef quantityName, OCStringRef quantityType, OCNumberType numericType, OCArrayRef components, OCStringRef *outError)

Minimal convenience constructor with only essential parameters.

Creates a DependentVariable with the minimal required parameters. Uses default values for name, description, componentLabels, sparseSampling, and metaData.

Parameters:

unit – Physical unit (required).
quantityName – Logical quantity name (e.g. “temperature”).
quantityType – Semantic type (“scalar”, “vector_N”, etc.).
numericType – Numeric storage type (kOCNumberFloat64Type, etc.).
components – Array of OCDataRef buffers (required).
outError – Optional pointer for error message.

Returns:

New DependentVariableRef or NULL on validation/alloc error.

DependentVariableRef DependentVariableCreateFromJSON(cJSON *json, OCStringRef *outError): Deserialize from cJSON using internal dictionary logic.

In-place Mutation

bool DependentVariableAppend(DependentVariableRef dv, DependentVariableRef appendedDV, OCStringRef *outError): Append another DependentVariable’s data onto the end of this one.

Serialization

cJSON *DependentVariableCopyAsJSON(DependentVariableRef dv, bool typed, OCStringRef *outError): Create cJSON object from DependentVariable.

OCDictionaryRef DependentVariableCopyAsDictionary(DependentVariableRef dv): Serialize into a deep-copyable OCDictionary (for JSON, tests).

DependentVariableRef DependentVariableCreateFromDictionary(OCDictionaryRef dict, OCStringRef *outError): Reconstruct from a dictionary produced by CopyAsDictionary().

OCDataRef DependentVariableCreateCSDMComponentsData(DependentVariableRef dv, OCArrayRef dimensions): Create a packed binary data blob for CSDM serialization.

Basic Accessors

bool DependentVariableIsScalarType(DependentVariableRef dv)

bool DependentVariableIsVectorType(DependentVariableRef dv, OCIndex *outCount)

bool DependentVariableIsPixelType(DependentVariableRef dv, OCIndex *outCount)

bool DependentVariableIsMatrixType(DependentVariableRef dv, OCIndex *outRows, OCIndex *outCols)

bool DependentVariableIsSymmetricMatrixType(DependentVariableRef dv, OCIndex *outN)

OCIndex DependentVariableComponentsCountFromQuantityType(OCStringRef quantityType)

OCStringRef DependentVariableCopyType(DependentVariableRef dv)

bool DependentVariableSetType(DependentVariableRef dv, OCStringRef newType)

bool DependentVariableShouldSerializeExternally(DependentVariableRef dv)

OCStringRef DependentVariableCopyEncoding(DependentVariableRef dv)

bool DependentVariableSetEncoding(DependentVariableRef dv, OCStringRef newEnc)

OCStringRef DependentVariableCopyComponentsURL(DependentVariableRef dv)

bool DependentVariableSetComponentsURL(DependentVariableRef dv, OCStringRef url)

OCStringRef DependentVariableCopyName(DependentVariableRef dv)

bool DependentVariableSetName(DependentVariableRef dv, OCStringRef newName)

OCStringRef DependentVariableCopyDescription(DependentVariableRef dv)

bool DependentVariableSetDescription(DependentVariableRef dv, OCStringRef newDesc)

OCStringRef DependentVariableCopyQuantityName(DependentVariableRef dv)

bool DependentVariableSetQuantityName(DependentVariableRef dv, OCStringRef quantityName)

OCStringRef DependentVariableCopyQuantityType(DependentVariableRef dv)

bool DependentVariableSetQuantityType(DependentVariableRef dv, OCStringRef quantityType)

OCNumberType DependentVariableGetNumericType(DependentVariableRef dv)

bool DependentVariableSetNumericType(DependentVariableRef dv, OCNumberType newType)

Sparse-sampling Accessors

SparseSamplingRef DependentVariableCopySparseSampling(DependentVariableRef dv)

bool DependentVariableSetSparseSampling(DependentVariableRef dv, SparseSamplingRef ss)

Component-array Accessors

OCIndex DependentVariableGetComponentCount(DependentVariableRef dv)

bool DependentVariableSetComponents(DependentVariableRef dv, OCArrayRef newComponents)

OCMutableArrayRef DependentVariableCopyComponents(DependentVariableRef dv)

OCDataRef DependentVariableCopyComponentAtIndex(DependentVariableRef dv, OCIndex idx)

bool DependentVariableSetComponentAtIndex(DependentVariableRef dv, OCDataRef newBuf, OCIndex idx)

bool DependentVariableInsertComponentAtIndex(DependentVariableRef dv, OCDataRef component, OCIndex idx)

bool DependentVariableRemoveComponentAtIndex(DependentVariableRef dv, OCIndex idx)

Size & Element Type

OCIndex DependentVariableGetSize(DependentVariableRef dv)

bool DependentVariableSetSize(DependentVariableRef dv, OCIndex newSize)

Per-component Labels

OCArrayRef DependentVariableCopyComponentLabels(DependentVariableRef dv)

bool DependentVariableSetComponentLabels(DependentVariableRef dv, OCArrayRef labels)

OCStringRef DependentVariableCreateComponentLabelForIndex(DependentVariableRef dv, OCIndex idx)

OCStringRef DependentVariableCopyComponentLabelAtIndex(DependentVariableRef dv, OCIndex idx)

bool DependentVariableSetComponentLabelAtIndex(DependentVariableRef dv, OCStringRef newLabel, OCIndex idx)

Low-level Value Accessors

float DependentVariableGetFloatValueAtMemOffset(DependentVariableRef dv, OCIndex compIdx, OCIndex memOffset)

double DependentVariableGetDoubleValueAtMemOffset(DependentVariableRef dv, OCIndex compIdx, OCIndex memOffset)

float _Complex DependentVariableGetFloatComplexValueAtMemOffset(DependentVariableRef dv, OCIndex compIdx, OCIndex memOffset)

double _Complex DependentVariableGetDoubleComplexValueAtMemOffset(DependentVariableRef dv, OCIndex compIdx, OCIndex memOffset)

double DependentVariableGetDoubleValueAtMemOffsetForPart(DependentVariableRef dv, OCIndex compIdx, OCIndex memOffset, complexPart part)

float DependentVariableGetFloatValueAtMemOffsetForPart(DependentVariableRef dv, OCIndex compIdx, OCIndex memOffset, complexPart part)

SIScalarRef DependentVariableCreateValueFromMemOffset(DependentVariableRef dv, OCIndex compIdx, OCIndex memOffset)

bool DependentVariableSetValueAtMemOffset(DependentVariableRef dv, OCIndex compIdx, OCIndex memOffset, SIScalarRef value, OCStringRef *error)

Typedefs

typedef struct impl_DependentVariable *DependentVariableRef: Opaque handle for a DependentVariable.

Functions

bool DependentVariableTakeComplexPart(DependentVariableRef dv, OCIndex componentIndex, complexPart part)

Extracts a specific complex component (real, imaginary, magnitude, or argument) from a DependentVariable’s data, replacing each value accordingly.

// Convert component 1 of myDV to its magnitude values:
bool ok = DependentVariableTakeComplexPart(myDV, 1, kSIMagnitudePart);

Parameters:

dv – The DependentVariable to modify.
componentIndex – Index of the component to operate on (0-based). If negative, the operation applies to all components in sequence.
part – Which part of each element to retain:
- kSIRealPart : keep real part, zero imaginary
- kSIImaginaryPart : keep imaginary part, zero real
- kSIMagnitudePart : replace with magnitude (abs)
- kSIArgumentPart : replace with argument (phase)

Returns:

true if the data was successfully transformed; false if inputs are invalid or the variable’s numeric type does not support the requested component.

OCDictionaryRef DependentVariableGetApplicationMetaData(DependentVariableRef dv)

bool DependentVariableSetApplicationMetaData(DependentVariableRef dv, OCDictionaryRef dict)

OCTypeRef DependentVariableGetOwner(DependentVariableRef dv)

bool DependentVariableSetOwner(DependentVariableRef dv, OCTypeRef owner)

bool DependentVariableConvertToUnit(DependentVariableRef dv, SIUnitRef unit, OCStringRef *error)

Convert all component data in a dependent variable to a new unit. Integer‐typed dependent variables cannot be converted and will error.

Parameters:

dv – The dependent variable to convert.
unit – The target unit (must have the same reduced dimensionality).
error – On failure, receives an OCStringRef describing the problem; may be NULL. Caller should release *error if non-NULL.

Returns:

true on success, false on error.

bool DependentVariableSetValuesToZero(DependentVariableRef dv, int64_t componentIndex)

Efficiently set all data values in a dependent variable (or a single component) to zero. Uses a single memset per component for maximum performance.

Parameters:

dv – The dependent variable whose data will be zeroed.
componentIndex – Index of the component to zero; use -1 to zero all components.

Returns:

true on success, false on error (e.g. no components or index out of range).

bool DependentVariableZeroPartInRange(DependentVariableRef dv, OCIndex componentIndex, OCRange range, complexPart part)

Replace each value in a dependent variable (or a single component) by its absolute value. Signed integers become their magnitude; floats use fabs/fabsf; complex values are replaced by their magnitude (imaginary part dropped) and the elementType is updated to the corresponding real type.

Zeroes out a specific component (real, imaginary, magnitude, or argument) of a DependentVariable’s data over a given index range.

// Zero the real portion of component 2 between indices 100 and 199:
OCRange r = { .location = 100, .length = 100 };
bool ok = DependentVariableZeroPartInRange(myDV, 2, r, kRealPart);

Parameters:

dv – The dependent variable to process.
componentIndex – Index of the component to process; use –1 to process all components.
dv – The DependentVariable to modify.
componentIndex – Index of the component to operate on (0-based). If negative, all components are processed.
range – The code-point range [location, location+length) within each component to zero.
part – Which part of the value to zero:
- kRealPart : zero the real part
- kImaginaryPart : zero the imaginary part
- kMagnitudePart : zero both parts
- kArgumentPart : replace with magnitude only

Returns:

true on success, false on error (e.g. no components or index out of range).

Returns:

true if the operation succeeded on the specified component(s) and range; false if the input is invalid or the element type is unsupported.

bool DependentVariableTakeAbsoluteValue(DependentVariableRef dv, int64_t componentIndex)

bool DependentVariableMultiplyValuesByDimensionlessComplexConstant(DependentVariableRef dv, int64_t componentIndex, double _Complex constant)

Multiply each value in a dependent variable (or a single component) by a dimensionless complex constant. Uses BLAS level-1 routines for optimized real and complex scaling; falls back to simple loops for integer types.

Parameters:

dv – The dependent variable whose data will be modified.
componentIndex – Index of the component to process; use -1 to process all components.
constant – The dimensionless complex constant to multiply each element by.

Returns:

true on success, false on error (e.g. no components or index out of range).

bool DependentVariableConjugate(DependentVariableRef dv, OCIndex componentIndex)

Conjugates the complex values of one or all components in a DependentVariable.

For each complex element in the specified component (or all components if componentIndex is negative), this function replaces z = x + i·y with its complex conjugate \(\bar{z} = x - i·y\) by negating the imaginary part in-place. Real-valued components are left unchanged.

Parameters:

dv – A valid DependentVariableRef whose data you wish to conjugate. Must not be NULL.
componentIndex – Index of the component to conjugate.
- If componentIndex is in \([0,\,n-1)\), only that component is processed.
- If componentIndex is negative, all components are processed.
- If componentIndex ≥ number of components, the function returns false.

Returns:

true on success (even if there was nothing to do for real-only data), false if dv is NULL, componentIndex is out of range, or the data type is not supported.

bool DependentVariableMultiplyValuesByDimensionlessRealConstant(DependentVariableRef dv, OCIndex componentIndex, double constant)

Multiply each element in one (or all) components of a DependentVariable by a dimensionless real constant.

This function supports signed and unsigned integer types (8/16/32/64-bit), single- and double-precision real types, and single- and double-precision complex types. For integer types, each element is cast to double, scaled, then cast back. Real and complex types are scaled via the corresponding CBLAS “scal” routines for maximum performance.

Parameters:

dv – The DependentVariable whose data will be modified in place. Must be non-NULL and have at least one component.
componentIndex – The index of the component to scale. If >= 0, only that component is affected. If negative, all components in dv are scaled.
constant – The real, dimensionless scalar by which to multiply each element.

Returns:

true if dv was valid, componentIndex in range, and scaling completed; false otherwise (e.g. dv == NULL, no components, or unsupported element type).

bool DependentVariableAdd(DependentVariableRef input1, DependentVariableRef input2, OCStringRef *error)

Add the values of two DependentVariables element-wise. The operation is performed in-place on the first variable.

Parameters:

input1 – The first DependentVariable (modified in-place).
input2 – The second DependentVariable to add.
error – On failure, receives an OCStringRef describing the problem; may be NULL. Caller should release *error if non-NULL.

Returns:

true on success, false on error.

bool DependentVariableSubtract(DependentVariableRef input1, DependentVariableRef input2, OCStringRef *error)

Subtract the values of the second DependentVariable from the first element-wise. The operation is performed in-place on the first variable.

Parameters:

input1 – The first DependentVariable (modified in-place).
input2 – The second DependentVariable to subtract.
error – On failure, receives an OCStringRef describing the problem; may be NULL. Caller should release *error if non-NULL.

Returns:

true on success, false on error.

bool DependentVariableMultiply(DependentVariableRef input1, DependentVariableRef input2, OCStringRef *error)

Multiply the values of two DependentVariables element-wise. The operation is performed in-place on the first variable. Units are multiplied according to dimensional analysis.

Parameters:

input1 – The first DependentVariable (modified in-place).
input2 – The second DependentVariable to multiply.
error – On failure, receives an OCStringRef describing the problem; may be NULL. Caller should release *error if non-NULL.

Returns:

true on success, false on error.

bool DependentVariableDivide(DependentVariableRef input1, DependentVariableRef input2, OCStringRef *error)

Divide the values of the first DependentVariable by the second element-wise. The operation is performed in-place on the first variable. Units are divided according to dimensional analysis. Division by zero produces IEEE infinity values.

Parameters:

input1 – The first DependentVariable (modified in-place).
input2 – The second DependentVariable to divide by.
error – On failure, receives an OCStringRef describing the problem; may be NULL. Caller should release *error if non-NULL.

Returns:

true on success, false on error.

bool DependentVariableCombineMagnitudeWithArgument(DependentVariableRef magnitude, DependentVariableRef argument)

Combine magnitude and argument arrays to create complex values. The magnitude variable is modified in-place to contain complex results.

Parameters:

magnitude – The magnitude DependentVariable (modified in-place to complex type).
argument – The argument (phase) DependentVariable.

Returns:

true on success, false on error.