org.das2.datum

Class DatumUtil

java.lang.Object

org.das2.datum.DatumUtil

public final class DatumUtil
extends java.lang.Object

Method Summary

Modifier and Type	Method and Description
static Datum	asOrderOneUnits(Datum d) This method takes the input datum and gets it as close to order one as possible by trying all possible conversions.
static DatumFormatter	bestFormatter(Datum minimum, Datum maximum, int nsteps) return a DatumFormatter that efficiently formats evenly-spaced datums from minimum to maximum with nstep intervals.
static DatumFormatter	bestFormatter(DatumVector datums) return the most efficient formatter for the datums, supporting nominal data, TimeLocationUnits, and LocationUnits, and other data.
static DatumFormatter	bestFormatter(DatumVector datums, DatumRange context) return the most efficient formatter for the datums, supporting nominal data, TimeLocationUnits, and LocationUnits, and other data.
static DatumFormatter	bestTimeFormatter(Datum minimum, Datum maximum, int nsteps)
static Datum	createValid(java.lang.String s) create a dimensionless datum by parsing the string.
static java.lang.String[]	datumStringSplit(java.lang.String s) splits the datum into a magnitude part and a unit part.
static Datum	divp(Datum amount, Datum delta) this is the divide that rounds down to the next integer, so divp("-25hr","24hr") is -2.
static double[]	doubleValues(Datum[] datums, Units units)
static double[]	doubleValues(Datum[] datums, Units[] unitsArray)
static int	fractionalDigits(Datum resolution)
static DatumFormatter	limitLogResolutionFormatter(Datum minimum, Datum maximum, int nsteps)
static DatumFormatter	limitResolutionFormatter(Datum minimum, Datum maximum, int nsteps)
static Datum	lookupDatum(java.lang.String s) Attempts to resolve strings commonly encountered.
static Datum	modp(Datum amount, Datum delta) return the modulo within the delta.
static Datum	numericalResolutionLimit(Datum datum) return the numeric resolution of the Datum.
static Datum	parse(java.lang.String s) attempt to parse the string as a datum.
static Datum	parseValid(java.lang.String s) parse the string which contains a valid representation of a a Datum.
static java.lang.String[]	splitDatumString(java.lang.String s) Split the string to separate magnitude component from units component.
static java.lang.String	zeros(int count) return "0" for 0, "0.0" for 1, "0.00" for 2, and so on.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

bestFormatter

public static DatumFormatter bestFormatter(DatumVector datums)

return the most efficient formatter for the datums, supporting nominal data, TimeLocationUnits, and LocationUnits, and other data.

Parameters:

datums -

Returns:

a formatter for the set.

See Also:

https://github.com/autoplot/dev/blob/master/demos/2021/20211203/testBestFormatter.jy

bestFormatter

public static DatumFormatter bestFormatter(DatumVector datums,
                                           DatumRange context)

return the most efficient formatter for the datums, supporting nominal data, TimeLocationUnits, and LocationUnits, and other data. A context can be provided, for example when the title contains the date of the data and only $H:$M should be shown.

Parameters:

datums -

context - externally-represented context, or null if none is used.

Returns:

a formatter for the set.

See Also:

https://github.com/autoplot/dev/blob/master/demos/2021/20211203/testBestFormatter.jy

fractionalDigits

public static int fractionalDigits(Datum resolution)

limitLogResolutionFormatter

public static DatumFormatter limitLogResolutionFormatter(Datum minimum,
                                                         Datum maximum,
                                                         int nsteps)

limitResolutionFormatter

public static DatumFormatter limitResolutionFormatter(Datum minimum,
                                                      Datum maximum,
                                                      int nsteps)

bestFormatter

public static DatumFormatter bestFormatter(Datum minimum,
                                           Datum maximum,
                                           int nsteps)

return a DatumFormatter that efficiently formats evenly-spaced datums from minimum to maximum with nstep intervals. (Interval size is maximum.subtract(minimum).divide(nsteps))

Parameters:

minimum -

maximum -

nsteps - the number of sub intervals

Returns:

zeros

public static java.lang.String zeros(int count)

return "0" for 0, "0.0" for 1, "0.00" for 2, and so on. This can be used in factory.newFormatter(formatString).

Parameters:

count - number of decimal places following the decimal.

Returns:

string for newFormatter.

See Also:

DatumFormatterFactory.newFormatter(java.lang.String)

bestTimeFormatter

public static DatumFormatter bestTimeFormatter(Datum minimum,
                                               Datum maximum,
                                               int nsteps)

splitDatumString

public static java.lang.String[] splitDatumString(java.lang.String s)

Split the string to separate magnitude component from units component. "5" → [ "5", "" ] "5 m" → [ "5", "m" ] "5m" → [ "5", "m" ] "4.5m^2" → [ "4.5", "m^2" ] "4.5e6m^2" → [ "4.5e6", "m^2" ] "-1" → [ "-1", "" ] "-1s" → [ "-1", "s" ] "-1.0e-6s" → [ "-1e-6", "s" ] "5 Deg N" → [ "5", "Deg N" ] " 10 days" → [ "10", "days" ] See http://jfaden.net:8080/hudson/job/autoplot-test037/ws/splitDatumString.jy

Parameters:

s - the string to break up

Returns:

two element array

parse

public static Datum parse(java.lang.String s)
                   throws java.text.ParseException

attempt to parse the string as a datum. Note that if the units aren't specified, then of course the Datum will be assumed to be dimensionless. This also requires the the unit be registered already, and lookup should be used if the unit should be registered automatically. Strings containing the unit UTC are parsed as times. Strings containing an ISO8601 string like $Y-$m-$dT$H:$M are parsed as strings.

Parameters:

s - the string representing the Datum, e.g. "5 Hz" (but not 5Hz).

Returns:

the Datum

Throws:

java.text.ParseException - when the double can't be parsed or the units aren't recognized.

parseValid

public static Datum parseValid(java.lang.String s)

parse the string which contains a valid representation of a a Datum. A runtime exception is thrown when the string cannot be parsed.

Parameters:

s - the string representing the Datum, e.g. "5 Hz"

Returns:

the Datum

Throws:

java.lang.RuntimeException - when the value wasn't parseable.

datumStringSplit

public static java.lang.String[] datumStringSplit(java.lang.String s)

splits the datum into a magnitude part and a unit part. When times are detected, "UTC" will be the units part. Here is a list to test against, and the motivation:

• 2014-05-29T00:00 ISO8601 times, cannot contain spaces.
• 5.e4 Hz registered known units
• 5.6 foos units from the wild
• 5.7 bytes/sec mix of MKS and units from the wild.
• 5.7Hz no space
• 5.7T no space, contains T.
• +5.7E+2Hz more challenging double.
• $57 unit before number

Note: units cannot start with E or e then a number or plus or minus. Datums cannot contain commas, semicolons, or quotes. NaN is Double.NaN. TODO: only $ is supported as a prefix. Others should be considered for completeness.

Parameters:

s - the string-formatted datum

Returns:

the magnitude and the units, or [null,s] when it is not parseable.

lookupDatum

public static Datum lookupDatum(java.lang.String s)
                         throws java.text.ParseException

Attempts to resolve strings commonly encountered. This was introduced to create a standard method for resolving Strings in ASCII files to a Datum. This follows the rules that:

• Things that appear to be times are parsed to a TimeLocationUnit.
• a double followed by whitespace then a unit is parsed as lookupUnit then parse(double)

Here is a list to test against, and the motivation:

• 2014-05-29T00:00 ISO8601 times, cannot contain spaces.
• 5.e4 Hz registered known units
• 5.6 foos units from the wild
• 5.7 bytes/sec mix of MKS and units from the wild.
• 5.7Hz no space
• 5.7T no space, (contains T which is also in ISO8601 times)
• 5.7eggs e could be mistaken for exponent.
• +5.7E+2Hz more challenging double.
• $57 unit before number

Parameters:

s -

Returns:

a Datum containing the value.

Throws:

java.text.ParseException

See Also:

Units.parse(java.lang.String)

createValid

public static Datum createValid(java.lang.String s)

create a dimensionless datum by parsing the string. See TimeUtil.createValid( String stime ).

Parameters:

s -

Returns:

doubleValues

public static double[] doubleValues(Datum[] datums,
                                    Units units)

doubleValues

public static double[] doubleValues(Datum[] datums,
                                    Units[] unitsArray)

asOrderOneUnits

public static Datum asOrderOneUnits(Datum d)

This method takes the input datum and gets it as close to order one as possible by trying all possible conversions.

Parameters:

d - A datum that needs to have its units changed to order one units.

Returns:

The order-one-ified Datum.

numericalResolutionLimit

public static Datum numericalResolutionLimit(Datum datum)

return the numeric resolution of the Datum. Note some Datum implementations have additional information which allows the measurement resolution to be reflected as well, and this should be much smaller.

Parameters:

datum - a datum

Returns:

a datum in the offset units.

modp

public static Datum modp(Datum amount,
                         Datum delta)

return the modulo within the delta. The result will always be a positive number. For example:

modp('-3days','7days')	4days
modp('10days','7days')	3days

A typical use might be:

%{code
 t= t + modp(t-phaseStart,span)
 }

TODO: study inconsistencies with QDataset Ops modp.

Parameters:

amount -

delta -

Returns:

the amount.

divp

public static Datum divp(Datum amount,
                         Datum delta)

this is the divide that rounds down to the next integer, so divp("-25hr","24hr") is -2. Note that the result must be dimensionless, other forms are not supported. TODO: study inconsistencies with QDataset Ops divp

Parameters:

amount -

delta -

Returns:

the dimensionless amount.