DatetimeRuler - Control axis with datetime values - MATLAB (original) (raw)

DatetimeRuler Properties

Control axis with datetime values

DatetimeRuler properties control the appearance and behavior of an _x_-axis, _y_-axis, or _z_-axis that shows datetime values. Each individual axis has its own ruler object. By changing property values of the ruler, you can modify certain aspects of a specific axis.

Use dot notation to refer to a particular ruler and property. Access the ruler objects through the XAxis, YAxis, andZAxis properties of the Axes object.

ax = gca; co = ax.XAxis.Color; ax.XAxis.Color = 'blue';

Appearance

expand all

Axis label horizontal alignment, specified as one of the values from the table.

LabelHorizontalAlignment Value	Description	Appearance
'center'	For a horizontal axis, the label is centered between the left and right edges of the plot box.For a vertical axis, the label is centered between the top and bottom edges of the plot box.
'left'	For a horizontal axis, the label is aligned with the left edge of the plot box.For a vertical axis, the label is aligned with the bottom edge of the plot box.
'right'	For a horizontal axis, the label is aligned with the right edge of the plot box.For a vertical axis, the label is aligned with the top edge of the plot box.

Scale and Direction

expand all

Minimum and maximum axis limits, specified as a two-element vector of the form [min max], where min andmax are datetime values. For example:

t = datetime(2014,6,28) + caldays(1:10); y = rand(1,10); plot(t,y); ax = gca; ax.XAxis.Limits = [t(2) t(8)];

Alternatively, set the limits using the xlim, ylim, and zlim functions.

If you assign a value to this property, then MATLAB® sets the associated mode to'manual'.

Note

The Limits property for the ruler and the associated XLim, YLim, orZLim property for the parent axes always have the same value. Setting one also sets the other.

Scale of values along axis, returned as 'linear'.DatetimeRuler objects do not support log scales.

Since R2023a

Reference date, specified as a datetime value. This property is useful for synchronizing tick placement across different axes and for plotting data from different time zones together.

MATLAB displays plots in the time zone of the first data set you plot into the axes. To change the time zone of the plot, set theReferenceDate property to a datetime value that has the desired time zone.

Example

Plot the number of New Year's Day revelers in New York and London. The resulting plot is in the time zone of New York.

NY = datetime(2021,1,1,0:17,0,0,"TimeZone","America/New_York"); London = datetime(2021,1,1,0:17,0,0,"TimeZone","Europe/London"); ax = axes; y = (1./(1:18).^2) * 100000; semilogy(ax,NY,y,London,y) grid on

Change the plot to use the time zone of London by setting theReferenceDate property to a datetime value that has a time zone of "Europe/London". Then add a legend and a title.

ax.XAxis.ReferenceDate = datetime(2022,1,1,"TimeZone","Europe/London"); legend("New York","London") title("New Year's Day Revelers")

Tick Values and Labels

expand all

Tick mark locations along the axis, specified as a vector of datetime values. For example:

t = datetime(2014,6,28) + caldays(1:10); y = rand(1,10); plot(t,y); ax = gca; ax.XAxis.TickValues = [t(1) t(3) t(5) t(10)];

If you assign a value to this property, then MATLAB sets the TickValuesMode property to'manual'.

Alternatively, use the xticks, yticks, and zticks functions.

Note

The TickValues property for the ruler and the associated XTick, YTick, orZTick property for the parent axes always have the same value. Setting one also sets the other.

Data Types: char | string | categorical

Tick label color, specified as an RGB triplet, a hexadecimal color code, a color name, or a short name.

For a custom color, specify an RGB triplet or a hexadecimal color code.

• An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7].
• A hexadecimal color code is a string scalar or character vector that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Therefore, the color codes"#FF8800","#ff8800","#F80", and"#f80" are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and the hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"
"none"	Not applicable	Not applicable	Not applicable	No color

This table lists the default color palettes for plots in the light and dark themes.

Palette	Palette Colors
"gem" — Light theme default_Before R2025a: Most plots use these colors by default._
"glow" — Dark theme default

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

RGB = orderedcolors("gem"); H = rgb2hex(RGB);

Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

Note

Setting the ruler’s Color property also sets theTickLabelColor property to the same value. However, setting the TickLabelColor property does not change theColor property. To prevent the Color property value from overriding the TickLabelColor property value, set the Color property first, and then set theTickLabelColor property.

Tick label format, specified as a string or character vector. The default format is based on the data.

Example: ax.XAxis.TickLabelFormat = "yyyy-MM-dd"; displays a date and time such as2014-04-19.

Example: ax.XAxis.TickLabelFormat = "eeee, MMMM d, yyyy HH:mm:ss"; displays a date and time such as Saturday, April 19, 2014 21:41:06.

Example: ax.XAxis.TickLabelFormat = "MMMM d, yyyy HH:mm:ss Z"; displays a date and time such as April 19, 2014 21:41:06 -0400.

The following tables show the letter identifiers that you can use to construct the format. To separate the fields, use nonletter characters such as a hyphen, space, colon, or any non-ASCII character. The identifiers correspond to the Unicode® Locale Data Markup Language (LDML) standard for dates.

Date and Time Formats

Use these identifiers to specify the display formats of the date and time fields.

Some tips and considerations:

• If you read a two-digit year number and specify the format as y or yy, then the pivot year determines the century to which the year belongs.
• Use one or more u characters instead ofy characters to represent the year when working with year numbers near zero.
• Datetime values later than 144683 years CE or before 140743 BCE display only the year numbers, regardless of the specified format value.

Time Zone Offset Formats

Use these identifiers to specify the display format of the time zone offset. A time zone offset is the amount of time that a specific date and time is offset from UTC. This is different from a time zone, which comprises rules that determine the offsets for specific times of the year. Include a time zone offset identifier when you want to ensure that the time components are displayed unambiguously.

Selection mode for the TickLabelFormat property, specified as one of these values:

• "auto" — MATLAB automatically selects a format for the tick labels based on the plotted datetime values and theSecondaryLabelFormat property.
• "manual" — You specify the format by setting the TickLabelFormat property.

Since R2024a

Secondary label format, specified as a string scalar or character vector. The secondary label appears in the margin next to the tick labels. You can use this property to customize the format of the label. The default format is based on the data. To remove the secondary label, specify an empty string ("").

If you specify the secondary label format, the tick labels might update to avoid displaying redundant information. For example, if you plot several days and display the month in the secondary label, the tick labels update to show the day numbers without the month.

Example: ax.XAxis.SecondaryLabelFormat = "MMMM" displays the month name.

Example: ax.XAxis.SecondaryLabelFormat = "ZZZZ" displays a time zone offset.

The following tables show the letter identifiers that you can use to construct the format. To separate the fields, use nonletter characters such as a hyphen, space, colon, or any non-ASCII character. The identifiers correspond to the Unicode Locale Data Markup Language (LDML) standard for dates.

Date and Time Formats

Use these identifiers to specify the display formats of the date and time fields.

Some tips and considerations:

• If you read a two-digit year number and specify the format as y or yy, then the pivot year determines the century to which the year belongs.
• Use one or more u characters instead ofy characters to represent the year when working with year numbers near zero.
• Datetime values later than 144683 years CE or before 140743 BCE display only the year numbers, regardless of the specified format value.

Time Zone Offset Formats

Use these identifiers to specify the display format of the time zone offset. A time zone offset is the amount of time that a specific date and time is offset from UTC. This is different from a time zone, which comprises rules that determine the offsets for specific times of the year. Include a time zone offset identifier when you want to ensure that the time components are displayed unambiguously.

Since R2024a

Selection mode for the SecondaryLabelFormat property, specified as one of these values:

• "auto" — MATLAB automatically selects a format for the secondary label based on plotted datetime values and theTickLabelFormat property.
• "manual" — You specify the format by setting the SecondaryLabelFormat property.

Minor tick mark locations, specified as a vector of increasing datetime values.

If you assign values to this property, then MATLAB sets the MinorTickValuesMode property to'manual'.

Font

Callbacks

expand all

Axis limits changed callback, specified as one of these values:

• A function handle.
• A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.
• A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

This callback executes after the axis limits have changed, either programmatically or using an interaction such as panning within the axes. It can also execute if MATLAB changes the axis limits to encompass the range of your data when you call a plotting function.

This callback function can access specific information about the axis limits. MATLAB passes this information in a LimitsChanged object as the second argument to your callback function. If you are developing an app in App Designer, the argument is calledevent. You can query the object properties using dot notation. For example, event.NewLimits returns the new axis limits. TheLimitsChanged object is not available to callback functions specified as character vectors.

The following table lists the properties of the LimitsChanged object.

For more information about writing callbacks in apps, see Callbacks in App Designer.

Parent/Child

expand all

The ruler has no children. You cannot set this property.

Version History

Introduced in R2016b

expand all

The FontSmoothing property has no effect and will be removed in a future release. You can set or get the value of this property without warning, but all text is smooth regardless of the property value. This property removal was announced in R2022a.

Format the secondary label of a datetime ruler by setting the SecondaryLabelFormat property. For example, a value of"yyyy" displays a four-digit year.

Set the ReferenceDate property when you plot datetime values. This property is useful for synchronizing tick placement across different axes, and for plotting data from different time zones together.