TimeSeries Class

1. Description

2. Module Interface

3. Subroutines and Functions

4. Examples

Description

The TimeSeries class represents an time-independent series of values.

(See also the Compression, FillValue and TimeCoordinate classes.)

Module Interface

MODULE TimeSeries_Class

TYPE TimeSeries

INTERFACE isValid
INTERFACE initialize
INTERFACE finalize
INTERFACE equal
INTERFACE unequal
INTERFACE get
INTERFACE set
INTERFACE read
INTERFACE write
INTERFACE print
INTERFACE addNewTime
INTERFACE getCompression
INTERFACE getDescription
INTERFACE getFill
INTERFACE getFillValue
INTERFACE getLastTimeIndex
INTERFACE getName
INTERFACE getOffset
INTERFACE getScale
INTERFACE getTime
INTERFACE getTimeIndex
INTERFACE getUnit
INTERFACE getValue
INTERFACE getValues
INTERFACE hasFillValue
INTERFACE setTimeAt
INTERFACE setTimeIndex
INTERFACE setValue
INTERFACE ASSIGNMENT (=)
INTERFACE OPERATOR (==)
INTERFACE OPERATOR (/=)

INTEGER, PARAMETER :: TimeSeries_InvalidDimensions
INTEGER, PARAMEGER :: TimeSeries_InvalidAttributeType
INTEGER, PARAMETER :: TimeSeries_InvalidAttributeSize
INTEGER, PARAMETER :: TimeSeries_DefinitionFailed
INTEGER, PARAMETER :: TimeSeries_NoTimeDimensionFound
INTEGER, PARAMETER :: TimeSeries_NoIndxDimensionFound

END MODULE TimeSeries_Class

Functions and Subroutines

FUNCTION isValid(this) RESULT(result)
    LOGICAL :: result
    TYPE(TimeSeries), INTENT(in) :: this

This function checks whether the parameter this contains a valid TimeSeries object. It may be applied to any TimeSeries object at any time. A valid TimeSeries object has a name, unit, and TimeCoordinate subobject.

SUBROUTINE initialize(this,compress,description,fill_value,name,
                         offset,scale,time,unit,values)
    TYPE(TimeSeries),     INTENT(out)          :: this
    TYPE(Compression),    INTENT(in), OPTIONAL :: compress
    CHARACTER(len=*),     INTENT(in), OPTIONAL :: description
    TYPE(FillValue),      INTENT(in), OPTIONAL :: fill
    REAL,                 INTENT(in), OPTIONAL :: fill_value
    CHARACTER(len=*),     INTENT(in)           :: name
    REAL,                 INTENT(in), OPTIONAL :: offset
    REAL,                 INTENT(in), OPTIONAL :: scale
    TYPE(TimeCoordinate), INTENT(in), OPTIONAL :: time
    CHARACTER(len=*),     INTENT(in), OPTIONAL :: unit
    REAL, DIMENSION(:),   INTENT(in), OPTIONAL :: values

This subroutine initializes an (invalid) TimeSeries object. This subroutine should be invoked on an object before any other function or subroutine except isValid. After initialization, the parameter this contains a valid TimeSeries object. The parameter name should contain the name of the object. This name is used to identify this TimeSeries object when it is read from or written to a file.
The following parameters can optionally be specified:

compress

The Compression object associated with this time series. Either this parameter should be provided or the offset and/or scale parameters.

description

A text that gives a more detailed description of this time series than its name.

fill

A FillValue object that is used to identify missing values. This parameter can only be specified when initializing a TimeSeries object. It cannot be changed later on. When you provide this parameter, you should not provide the fill_value parameter.

fill_value

The value that indicates that a value at a given time is undefined. It cannot be changed later on. You should provide either this parameter or the fill parameter.

name

The name of this time series. This name should not be the empty string.

offset

An offset that should be added to the values of this TimeSeries in order to obtain the actual values. This offset is added after the values have been scaled. This parameter should not be provided when the compress parameter is.

scale

A scaling factor that should be applied to the values. This parameter should not be provided when the compress parameter is.

time

The TimeCoordinate object that defines the valid range of the time of this TimeSeries object.

unit

The unit in which the values of this TimeSeries object are expressed.

values

The values of this TimeSeries object.

An TimeSeries object can also be initialized from another TimeSeries object using the assignment operator.

(See also the Compression and TimeCoordinate classes.)

SUBROUTINE initialize(this,info)
    TYPE(TimeSeries), INTENT(out) :: this
    TYPE(FieldInfo),  INTENT(in)  :: info

This subroutine initializes an (invalid) TimeSeries object using the information provided by the parameter info.
For a description of the FieldInfo type, see the DataFile class.

SUBROUTINE finalize(this)
    TYPE(TimeSeries), INTENT(inout) :: this

This subroutine finalizes the (valid) TimeSeries object, this. This object should have been initialized earlier in the program. After finalization, the object is invalid and should not be used anymore.

FUNCTION equal(left,right) RESULT(result)
    LOGICAL :: result
    TYPE(TimeSeries), INTENT(in) :: left
    TYPE(TimeSeries), INTENT(in) :: right

This function compares two TimeSeries objects. When the two objects are equal, the value .TRUE. is returned. Otherwise, the return value is .FALSE.. Two TimeSeries object are equal when their names, descriptions, etc. are equal.
This function can also be invoked via the binary operator ==.

FUNCTION unequal(left,right) RESULT(result)
    LOGICAL :: result
    TYPE(TimeSeries), INTENT(in) :: left
    TYPE(TimeSeries), INTENT(in) :: right

This function checks whether two TimeSeries objects are different.
This function can also be invoked via the binary operator /=.

SUBROUTINE get(this,compress,description,name,offset,scale,time,unit,values)
    TYPE(TimeSeries),     INTENT(in)            :: this
    TYPE(Compression),    INTENT(out), OPTIONAL :: compress
    CHARACTER(len=*),     INTENT(out), OPTIONAL :: description
    CHARACTER(len=*),     INTENT(out), OPTIONAL :: name
    REAL,                 INTENT(out), OPTIONAL :: offset
    REAL,                 INTENT(out), OPTIONAL :: scale
    TYPE(TimeCoordinate), INTENT(out), OPTIONAL :: time
    CHARACTER(len=*),     INTENT(out), OPTIONAL :: unit
    REAL, DIMENSION(:),   INTENT(out), OPTIONAL :: values

This subroutine retrieves information from the TimeSeries object, this. The object itself is not modified. The optional parameters determine which information will be retrieved. Note that the size of array passed as the parameter value should be large enough to contain all the values of this TimeSeries object. This subroutine can be invoked without any parameters. In this case, the subroutine is as a no-op.

(See also the Compression and TimeCoordinate classes.)

SUBROUTINE set(this,description,name,time,unit,values)
    TYPE(TimeSeries),     INTENT(inout)        :: this
    CHARACTER(len=*),     INTENT(in), OPTIONAL :: description
    CHARACTER(len=*),     INTENT(in), OPTIONAL :: name
    TYPE(TimeCoordinate), INTENT(in), OPTIONAL :: time
    CHARACTER(len=*),     INTENT(in), OPTIONAL :: unit
    REAL, DIMENSION(:),   INTENT(in), OPTIONAL :: values

This subroutine modifies the TimeSeries object, this. The optional parameters determine which information is modified. When both the parameter time and value are provided, value should be in the range from 1 to getLength(time). This subroutine can be invoked without any parameters. In this case, the subroutine is as a no-op. Note that the name and unit parameters may not be set to the empty string.

(See also the Compression and TimeCoordinate classes.)

SUBROUTINE read(this,file,err)
    TYPE(TimeSeries), INTENT(inout)           :: this
    TYPE(DataFile),   INTENT(in)              :: file
    TYPE(Error),      INTENT(inout), OPTIONAL :: err

This subroutine reads this TimeSeries object from a file. The object can be read successfully when a one- or two-dimensional variable with the name of the TimeSeries object is present in the data file. The old contents of the object is destroyed. An Error object can be passed to this subroutine to catch run-time errors that would otherwise cause the execution of the program to be aborted.
The following error codes can be set:

TimeSeries_InvalidDimensions
The file contains a variable with the given name but this variable does not have one dimension.
TimeSeries_InvalidAttributeType
An attribute required by the COARDS conventions  for NetCDF file was found but this attribute was of the wrong type.
TimeSeries_InvalidAttributeSize
An attribute required by the COARDS conventions  for NetCDF file was found but this attribute had the wrong size.
TimeSeries_NoTimeDimensionFound
The variable in the data file has no time dimension.

(See also the DataFile and Error classes.)

SUBROUTINE write(this,file,err)
    TYPE(TimeSeries), INTENT(in)              :: this
    TYPE(DataFile),   INTENT(in)              :: file
    TYPE(Error),      INTENT(inout), OPTIONAL :: err

This subroutine writes the contents of this TimeSeries object to a file. When the object was written to the same file before, the new contents replaces the old. An Error object can be passed to this subroutine to catch run-time errors that would otherwise cause the execution of the program to be aborted.
The following error codes can be set:

TimeSeries_DefinitionFailed
The object was not written to the file before. Therefore, it must be defined first. However, when attempting to do this, an error occured.
TimeSeries_InvalidDimensions
A similar object with a different number of dimensions was written to the file before. This information cannot be replaced.

(See also the DataFile and Error classes.)

SUBROUTINE print(this)
    TYPE(TimeSeries), INTENT(in) :: this

This subroutine is the equivalent of the Fortran PRINT statement. It prints the TimeSeries object, this, to the standard output unit in standardized format. The object is not modified.

SUBROUTINE addNewTime(this,time)
    TYPE(TimeSeries), INTENT(inout) :: this
    REAL,             INTENT(in)    :: time

This subroutine adds a new time coordinate value to this time series. The length of this TimeSeries object is increased by one.

FUNCTION getCompression(this) RESULT(result)
    TYPE(Compression) :: result
    TYPE(TimeSeries), INTENT(in) :: this

This function returns the Compression object associated with this TimeSeries object.

(See also the Compression class.)

FUNCTION getDescription(this) RESULT(result)
    CHARACTER(len=*) :: result
    TYPE(TimeSeries), INTENT(in) :: this

This function retrieves the description of this TimeSeries object.

FUNCTION getFill(this) RESULT(result)
    TYPE(FillValue) :: result
    TYPE(TimeSeries), INTENT(in) :: this

This function returns the FillValue object of this TimeSeries object.

(See also the FillValue class.)

FUNCTION getFillValue(this) RESULT(result)
    REAL :: result
    TYPE(TimeSeries), INTENT(in) :: this

This function returns the fill value of this TimeSeries object. Note that the return value of this function is only meaningful when the function hasFillValue returns the value .TRUE. for this object.

FUNCTION getLastTimeIndex(this) RESULT(result)
    INTEGER :: result
    TYPE(TimeSeries), INTENT(in) :: this

This function returns the last valid time index value of this TimeSeries object. The index argument to the setTimeIndex subroutine should not exceed this value.

FUNCTION getName(this) RESULT(result)
    CHARACTER(len=*) :: result
    TYPE(TimeSeries), INTENT(in) :: this

This function retrieves the name of this TimeSeries object. This is the name that is used to identify the object in a data file.

FUNCTION getOffset(this) RESULT(result)
    REAL :: result
    TYPE(TimeSeries), INTENT(in) :: this

This function retrieves the offset value of the data contained in this TimeSeries object. This offset should be added to the values after the scaling factor has been applied.

FUNCTION getScale(this) RESULT(result)
    REAL :: result
    TYPE(TimeSeries), INTENT(in) :: this

This function retrieves the scaling factor of the data contained in this TimeSeries object. This scaling factor should be applied before the offset is added to the values.

FUNCTION getTime(this) RESULT(result)
    TYPE(TimeCoordinate) :: result
    TYPE(TimeSeries), INTENT(in) :: this

This function retrieves a copy of the TimeCoordinate subobject of this TimeSeries object.

FUNCTION getTimeIndex(this) RESULT(result)
 INTEGER :: result
 TYPE(TimeSeries), INTENT(in) :: this

This function retrieves time index of this TimeSeries object.

FUNCTION getUnit(this) RESULT(result)
    CHARACTER(len=*) :: result
    TYPE(TimeSeries), INTENT(in) :: this

This function retrieves the unit of this TimeSeries object.

FUNCTION getValue(this) RESULT(result)
    REAL :: result
    TYPE(TimeSeries), INTENT(in) :: this

This function retrieves the value of this TimeSeries object at its current time index.

FUNCTION getValues(this) RESULT(result)
    REAL, DIMENSION(:), POINTER :: result
    TYPE(TimeSeries), INTENT(in) :: this

This function retrieves the values of this TimeSeries object.

FUNCTION hasFillValue(this) RESULT(result)
    LOGICAL :: result
    TYPE(TimeSeries), INTENT(in) :: this

The return value of this function indicates whether this TimeSeries object has a fill value.

SUBROUTINE setTimeAt(this,index,time)
 TYPE(Field), INTENT(inout) :: this
 INTEGER, INTENT(in) :: index
 REAL, INTENT(in) :: time

This subroutine sets the time value at a given time index. The parameter index must have a value in the range from one to getLastTimeIndex(this).

SUBROUTINE setTimeIndex(this,index)
    TYPE(TimeSeries), INTENT(inout) :: this
    INTEGER,          INTENT(in)    :: index

This subroutine sets the current time index value of the TimeSeries object, this.

SUBROUTINE setValue(this,value)
    TYPE(TimeSeries), INTENT(inout) :: this
    REAL,             INTENT(in)    :: value

This subroutine sets the value at the current time index of the TimeSeries object, this.

ASSIGNMENT (=)    <left> = <right>

This operator copies the content of the TimeSeries object at the right of the assignment operator to the one at the left. The latter object can invalid before the assignment. After the assignment it is valid and equal to the object at the right.

OPERATOR (==)    <left> == <right>

This operator compares two TimeSeries objects for equality. It is an alternative for using the equal function.

OPERATOR (/=)    <left> /= <right>

This operator compares two TimeSeries objects for inequality. It is an alternative for using the unequal function.

Examples

The following example program shows how a TimeSeries object can be used to store a number of eigen values.

PROGRAM TimeSeries_Class_Example
  USE TimeCoordinate_Class
  USE TimeSeries_Class
  IMPLICIT NONE

  REAL, DIMENSION(10), PARAMETER :: values = &
     & (/ 10.0, 9.0, 7.0, 5.6, 4.3, 1.0, 0.34, 0.01, 0.009, 0.001 /)

  TYPE(TimeCoordinate):: time
  TYPE(TimeSeries)    :: series
  INTEGER             :: i

  CALL initialize(time,name="time",unit="days since 000-01-01")
  CALL initialize(series,name="temperature",time=time, &
     & description="Time Series of Temperature")

  DO i=LBound(values,1),UBound(values,1)
    CALL addNewTime(series,Real(i))
    CALL setValue(series,values(i))
  END DO

  CALL print(series)

  CALL finalize(series)
  CALL finalize(time)
END PROGRAM TimeSeries_Class_Example