Ambiguous filter_temporal process definition

[sinergise-anze]

While implementing filter_temporal process we have stumbled across some inconsistencies in the process definition. Note that none of it is a blocker for us, but it is probably best to document such issues when we encounter them. Let us know if you would prefer some other channel of communication for this.

Also, if you would prefer a PR (IIUC, it should be fixed here) I'd be happy to do it, but would appreciate a confirmation that these suggestions make sense.

---

The filter_temporal process documentation is not clear on whether the dimension parameter specifies a single or multiple dimensions:

If the dimension is set to null (it's the default value), the data cube is expected to only have one temporal dimension.

If the dimension is not set or is set to null, the filter applies to all temporal dimensions.

Return value: ... remain unchanged, except that the given temporal dimension(s) have less (or the same) dimension labels.

Since the data types do not suggest a way to provide multiple extents and/or dimensions, I am assuming that this process can only operate on a single temporal dimension. If this is so, I would suggest changing the texts to read:

If the dimension is set to null (it's the default value), the data cube is expected to have exactly one temporal dimension.

If the dimension is not set or is set to null, the filter applies to the only temporal dimension that exists (and must exist) in data cube.

Return value: ... remain unchanged, except that the given temporal dimension has less (or the same) dimension labels.

---

Additionally, this exception is not available in the list of errors:

Fails with a DimensionNotAvailable error if the specified dimension does not exist.

Errors/Exceptions
DimensionNotAvailable
Message: A dimension with the specified name does not exist.

I assume that ProcessParameterInvalid should be used instead and that other possible messages should also be included. One option would be:

Fails with a ProcessParameterInvalid error if the specified dimension does not exist.

Errors/Exceptions
ProcessParameterInvalid
Message: A dimension with the specified name does not exist.
Message: A dimension with the specified name is not temporal.
Message: More than one temporal dimension available, please specify dimension.
Message: No temporal dimension is available.

[m-mohr]

Thanks for the report.

The filter_temporal process documentation is not clear on whether the dimension parameter specifies a single or multiple dimensions:

If the dimension is set to null (it's the default value), the data cube is expected to only have one temporal dimension.

If the dimension is not set or is set to null, the filter applies to all temporal dimensions.

Return value: ... remain unchanged, except that the given temporal dimension(s) have less (or the same) dimension labels.

Since the data types do not suggest a way to provide multiple extents and/or dimensions, I am assuming that this process can only operate on a single temporal dimension. If this is so, I would suggest changing the texts to read:

If the dimension is set to null (it's the default value), the data cube is expected to have exactly one temporal dimension.

If the dimension is not set or is set to null, the filter applies to the only temporal dimension that exists (and must exist) in data cube.

Return value: ... remain unchanged, except that the given temporal dimension has less (or the same) dimension labels.

You are correct, there are contradicting statements in the process. It was meant to work this way:

• dimension not given: filters ALL temporal dimensions
• dimension given (you can only specify one): Filters only the specified temporal dimension

I'll issue a PR.

Additionally, this exception is not available in the list of errors:

Yes, it is correct that the error is missing there. The file you are referring to is just giving a recommendation on some general errors as they may be reported by the API. The processes define their own errors in addition.

I assume that ProcessParameterInvalid should be used instead and that other possible messages should also be included.

Indeed, sometime it could be useful to combine the error messages as they give additional context. Through the introduction of logging it got less relevant though as now the logs give more context, too (e.g. path). I agree that this is a bit confusing.

[sinergise-anze]

Thank you for the explanation and the fix, it makes much more sense now!