作成者Observable

外観

d3-time ​

時系列データの可視化、時間的パターンの分析、または一般的な時間に関する作業を行う場合、従来の時間単位の不規則性がすぐに明らかになります。グレゴリオ暦では、たとえば、ほとんどの月は31日ですが、28日、29日、または30日である月もあり、ほとんどの年は365日ですが、閏年は366日です。また、サマータイムにより、ほとんどの日は24時間ですが、23時間または25時間の日もあります。さらに複雑なことに、サマータイムの慣習は世界中で異なります。

これらの時間的な特殊性のため、一見些細なタスクの実行が困難になる可能性があります。たとえば、2つの日付の間経過した日数を計算する場合、単純に減算して24時間（86,400,000ミリ秒）で割ることはできません。

js
const start = new Date(2015, 02, 01); // 2015-03-01T00:00
const end = new Date(2015, 03, 01); // 2015-04-01T00:00
const days = (end - start) / 864e5; // 30.958333333333332, oops! 🤯

ただし、d3.timeDay.count を使用できます。

js
d3.timeDay.count(start, end) // 31 😌

day インターバルは、d3-timeによって提供されるいくつかのインターバルの1つです。各インターバルは従来の時間単位（時間、週、月など）を表し、境界日付を計算するメソッドがあります。たとえば、d3.timeDayは、対応する日の真夜中（通常は現地時間午前12時）を計算します。丸めとカウントに加えて、インターバルを使用して境界日付の配列を生成することもできます。たとえば、今月の各日曜日を計算するには

js
const start = d3.timeMonth.floor(new Date(2015, 0, 15)); // 2015-01-01T00:00
const stop = d3.timeMonth.ceil(new Date(2015, 0, 15)); // 2015-02-01T00:00
const weeks = d3.timeWeek.range(start, stop); // [2015-01-04T00:00, 2015-01-11T00:00, 2015-01-18T00:00, 2015-01-25T00:00]

d3-timeモジュールは独自の暦システムを実装していません。単にECMAScript Dateの上にカレンダー計算のための便利なAPIを実装しています。したがって、閏秒を無視し、現地時間と協定世界時（UTC）でのみ機能します。

このモジュールは、D3の時間スケールで適切なティックを生成するために使用され、D3の時間形式によっても使用され、カレンダーレイアウトなどを行うためにも直接使用できます。

interval(date) ​

js
d3.utcMonday() // the latest preceding Monday, UTC time

ソース · interval.floorと同等ですが、dateが指定されていない場合、現在の時間にデフォルト設定されます。たとえば、d3.timeYear(date)とd3.timeYear.floor(date)は同等です。

interval.floor(date) ​

js
d3.utcMonday.floor(new Date()) // the latest preceding Monday, UTC time

ソース · dateの前または等しい最新のインターバル境界日付を表す新しい日付を返します。たとえば、d3.timeDay.floor(date)は、通常、指定されたdateの現地時間午前12時を返します。

このメソッドはべき等です。指定されたdateが既に現在のインターバルにフロアされている場合、同一の時間を含む新しい日付が返されます。さらに、返された日付は関連するインターバルの表現可能な最小値であり、interval.floor(interval.floor(date) - 1)は、前のインターバル境界日付を返します。

Dateオブジェクトでは==演算子と===演算子は値で比較されないため、指定されたdateが既にフロアされているかどうかを判断するためにそれらを使用することはできません。代わりに、数値に変換してから比較してください。

js
// Returns true if the specified date is a day boundary.
function isDay(date) {
  return +d3.timeDay.floor(date) === +date;
}

これは、サマータイムのために一部のタイムゾーンでは真夜中が存在しない場合があるため、時間が午前12時かどうかをテストするよりも信頼性があります。

interval.round(date) ​

js
d3.utcMonday.round(new Date()) // the previous or following Monday, whichever is closer

ソース · dateに最も近いインターバル境界日付を表す新しい日付を返します。たとえば、d3.timeDay.round(date)は、正午前または正午の場合、指定されたdateの現地時間午前12時を返し、正午後の場合は翌日の午前12時を返します。

このメソッドはべき等です。指定されたdateが既に現在のインターバルに丸められている場合、同一の時間を含む新しい日付が返されます。

interval.ceil(date) ​

js
d3.utcMonday.ceil(new Date()) // the following Monday

ソース · dateの後または等しい最も早いインターバル境界日付を表す新しい日付を返します。たとえば、d3.timeDay.ceil(date)は、通常、指定されたdateの翌日の現地時間午前12時を返します。

このメソッドはべき等です。指定されたdateが既に現在のインターバルにシーリングされている場合、同一の時間を含む新しい日付が返されます。さらに、返された日付は関連するインターバルの表現可能な最大値であり、interval.ceil(interval.ceil(date) + 1)は、次のインターバル境界日付を返します。

interval.offset(date, step) ​

js
d3.utcDay.offset(new Date(), 1) // the same time tomorrow

ソース · dateにstepインターバルを加算した新しい日付を返します。stepが指定されていない場合、デフォルトは1になります。stepが負の場合、返された日付は指定されたdateの前になります。stepがゼロの場合、指定されたdateのコピーが返されます。stepが整数でない場合、フロアされます。このメソッドは、指定されたdateをインターバルに丸めません。たとえば、dateが今日の午後5時34分の場合は、d3.timeDay.offset(date, 1)は、明日の午後5時34分を返します（サマータイムが変わっても！）。

interval.range(start, stop, step) ​

js
d3.utcDay.range(new Date("2014-01-01"), new Date("2015-01-01")) // every day in 2014

ソース · start（を含む）以降でstop（を除く）より前のすべてのインターバル境界を表す日付の配列を返します。stepを指定した場合、step番目の境界ごとに返されます。たとえば、d3.timeDayインターバルでは、stepが2の場合、日を交互に返します。stepが整数でない場合、フロアされます。

返される配列の最初の日付は、start以降の最も早い境界です。後続の日付は、stepインターバルでオフセットされ、フロアされます。したがって、2つの重複する範囲は一貫している可能性があります。たとえば、この範囲には奇数日が含まれています。

js
d3.timeDay.range(new Date(2015, 0, 1), new Date(2015, 0, 7), 2) // [2015-01-01T00:00, 2015-01-03T00:00, 2015-01-05T00:00]

これには偶数日が含まれています。

js
d3.timeDay.range(new Date(2015, 0, 2), new Date(2015, 0, 8), 2) // [2015-01-02T00:00, 2015-01-04T00:00, 2015-01-06T00:00]

stepを指定した場合に範囲を一貫させるには、代わりにinterval.everyを使用してください。

便宜上、interval.rangeのエイリアスは、対応するインターバルの複数形として提供されます（utcMondaysなど）。

interval.filter(test) ​

ソース · 指定されたtest関数を使用して、このインターバルのフィルターされたサブセットである新しいインターバルを返します。test関数は日付を受け取り、指定された日付がインターバルの一部とみなされる場合にのみtrueを返す必要があります。たとえば、各月の1日、11日、21日、31日（存在する場合）を返すインターバルを作成するには

js
d3.timeDay.filter((d) => (d.getDate() - 1) % 10 === 0)

返されたフィルタリングされたインターバルは、interval.count をサポートしていません。interval.every も参照してください。

interval.every(step) ​

js
d3.unixDay.every(3)

ソースコード · このインターバルのフィルタリングされたビューを返し、step 番目の日付を表します。step の意味は、フィールド関数で定義されているこのインターバルの親インターバルによって異なります。たとえば、d3.timeMinute.every(15) は、時間単位で15分ごと（:00、:15、:30、:45など）を表すインターバルを返します。一部のインターバルでは、結果の日付が均一に間隔を空けていない場合があります。d3.timeDayの親インターバルはd3.timeMonthであるため、インターバル番号は各月の初めにリセットされます。step が無効な場合は、null を返します。step が1の場合は、このインターバルを返します。

このメソッドは、interval.range と組み合わせて使用して、2つの重複する範囲の一貫性を確保できます。たとえば、この範囲には奇数日が含まれています。

js
d3.timeDay.every(2).range(new Date(2015, 0, 1), new Date(2015, 0, 7)) // [2015-01-01T00:00, 2015-01-03T00:00, 2015-01-05T00:00]

これも同様です。

js
d3.timeDay.every(2).range(new Date(2015, 0, 2), new Date(2015, 0, 8)) // [2015-01-03T00:00, 2015-01-05T00:00, 2015-01-07T00:00]

返されたフィルタリングされたインターバルは、interval.count をサポートしていません。interval.filter も参照してください。

interval.count(start, end) ​

ソースコード · start（除く）の後、end（含む）以前またはend と等しいインターバル境界の数 を返します。この動作はinterval.rangeとはわずかに異なります。これは、指定されたend日付のゼロベースの番号を指定されたstart日付を基準に返すことを目的としているためです。たとえば、現在のゼロベースの年間日数を計算するには

js
d3.timeDay.count(d3.timeYear(now), now) // 177

同様に、日曜日から始まる週の現在のゼロベースの週数を計算するには

js
d3.timeSunday.count(d3.timeYear(now), now) // 25

timeInterval(floor, offset, count, field) ​

js
const utcDay = d3.timeInterval(
  (date) => date.setUTCHours(0, 0, 0, 0), // floor
  (date, step) => date.setUTCDate(date.getUTCDate() + step), // offset
  (start, end) => (end - start) / 864e5, // count
  (date) => date.getUTCDate() - 1 // field
);

ソースコード · 指定されたfloor関数とoffset関数、およびオプションのcount関数を指定して、新しいカスタムインターバルを構築します。

floor関数は、日付を1つ引数として受け取り、最も近いインターバル境界に切り下げます。

offset関数は、日付と整数のステップを引数として受け取り、指定された日付を指定された境界の数だけ進めます。ステップは正、負、またはゼロにすることができます。

オプションのcount関数は、既に現在のインターバルに切り下げられた開始日と終了日を受け取り、開始（除く）と終了（含む）の間の境界数を返します。count関数を指定しない場合、返されたインターバルはinterval.countまたはinterval.everyメソッドを公開しません。注：内部最適化のため、指定されたcount関数は他の時間インターバルでinterval.countを呼び出してはいけません。

オプションのfield関数は、既に現在のインターバルに切り下げられた日付を受け取り、指定された日付のフィールド値を返します。これは、この日付（除く）と直前の親境界の間の境界数に対応します。たとえば、d3.timeDayインターバルの場合、これは月の初めからの日数を返します。field関数を指定しない場合、1970年1月1日UTCのUNIXエポックからのインターバル境界数をカウントするデフォルトになります。field関数はinterval.everyの動作を定義します。

timeMillisecond ​

ソースコード · ローカル時刻のミリ秒。使用可能な最短の時間単位です。

timeSecond ​

ソースコード · ローカル時刻の秒（例：午前01:23:45.0000）。1,000ミリ秒。

timeMinute ​

ソースコード · ローカル時刻の分（例：午前01:02:00）。60秒。ECMAScriptは閏秒を無視することに注意してください。

timeHour ​

ソースコード · ローカル時刻の時間（例：午前01:00）。60分。ローカル時刻で1時間進めると、同じ時間になるか、夏時間のために時間がスキップされる場合があります。

timeDay ​

ソースコード · ローカル時刻の日付（例：2012年2月7日午前0時）。通常24時間。夏時間のため、ローカル時刻の日数は23～25時間になる場合があります。d3.unixDayはd3.utcDayに似ていますが、UNIXエポック（1970年1月1日）からの日数をカウントするため、interval.everyは月の日数に基づいて変化するのではなく、均一に間隔を空けた日付を返します。

timeWeek ​

ソースコード · d3.timeSundayのエイリアス。7日間、通常は168時間。夏時間のため、ローカル時刻の週数は167～169時間になる場合があります。

timeSunday ​

ソースコード · ローカル時刻の日曜日からの週（例：2012年2月5日午前0時）。

timeMonday ​

ソースコード · ローカル時刻の月曜日からの週（例：2012年2月6日午前0時）。

timeTuesday ​

ソースコード · ローカル時刻の火曜日からの週（例：2012年2月7日午前0時）。

timeWednesday ​

ソースコード · ローカル時刻の水曜日からの週（例：2012年2月8日午前0時）。

timeThursday ​

ソースコード · ローカル時刻の木曜日からの週（例：2012年2月9日午前0時）。

timeFriday ​

ソースコード · ローカル時刻の金曜日からの週（例：2012年2月10日午前0時）。

timeSaturday ​

ソースコード · ローカル時刻の土曜日からの週（例：2012年2月11日午前0時）。

timeMonth ​

ソースコード · ローカル時刻の月（例：2012年2月1日午前0時）。28～31日の範囲。

timeYear ​

ソースコード · ローカル時刻の年（例：2012年1月1日午前0時）。365～366日の範囲。

utcMillisecond ​

ソースコード · UTC時刻のミリ秒。使用可能な最短の時間単位です。

utcSecond ​

ソースコード · UTC時刻の秒（例：午前01:23:45.0000）。1,000ミリ秒。

utcMinute ​

ソースコード · UTC時刻の分（例：午前01:02:00）。60秒。ECMAScriptは閏秒を無視することに注意してください。

utcHour ​

ソースコード · UTC時刻の時間（例：午前01:00）。60分。

utcDay ​

ソースコード · UTC時刻の日付（例：2012年2月7日午前0時）。24時間。

utcWeek ​

ソースコード · d3.timeSundayのエイリアス。7日間、168時間。

utcSunday ​

ソースコード · UTC時刻の日曜日からの週（例：2012年2月5日午前0時）。

utcMonday ​

ソースコード · UTC時刻の月曜日からの週（例：2012年2月6日午前0時）。

utcTuesday ​

ソースコード · UTC時刻の火曜日からの週（例：2012年2月7日午前0時）。

utcWednesday ​

ソースコード · UTC時間における水曜日を基準とした週（例：2012年2月8日午前0時）。

utcThursday ​

ソースコード · UTC時間における木曜日を基準とした週（例：2012年2月9日午前0時）。

utcFriday ​

ソースコード · UTC時間における金曜日を基準とした週（例：2012年2月10日午前0時）。

utcSaturday ​

ソースコード · UTC時間における土曜日を基準とした週（例：2012年2月11日午前0時）。

utcMonth ​

ソースコード · UTC時間における月（例：2012年2月1日午前0時）。日数は28日から31日。

utcYear ​

ソースコード · UTC時間における年（例：2012年1月1日午前0時）。日数は365日から366日。

unixDay ​

d3.utcDayと同様ですが、UNIXエポック（1970年1月1日）からの日数をカウントします。そのため、interval.everyは、月の日数に基づいて変化するのではなく、均等に間隔を置いた日付を返します。

timeMilliseconds(start, stop, step) ​

d3.timeMillisecond.range のエイリアス。

timeSeconds(start, stop, step) ​

d3.timeSecond.range のエイリアス。

timeMinutes(start, stop, step) ​

d3.timeMinute.range のエイリアス。

timeHours(start, stop, step) ​

d3.timeHour.range のエイリアス。

timeDays(start, stop, step) ​

d3.timeDay.range のエイリアス。

timeWeeks(start, stop, step) ​

d3.timeWeek.range のエイリアス。

timeSundays(start, stop, step) ​

d3.timeSunday.range のエイリアス。

timeMondays(start, stop, step) ​

d3.timeMonday.range のエイリアス。

timeTuesdays(start, stop, step) ​

d3.timeTuesday.range のエイリアス。

timeWednesdays(start, stop, step) ​

d3.timeWednesday.range のエイリアス。

timeThursdays(start, stop, step) ​

d3.timeThursday.range のエイリアス。

timeFridays(start, stop, step) ​

d3.timeFriday.range のエイリアス。

timeSaturdays(start, stop, step) ​

d3.timeSaturday.range のエイリアス。

timeMonths(start, stop, step) ​

d3.timeMonth.range のエイリアス。

timeYears(start, stop, step) ​

d3.timeYear.range のエイリアス。

utcMilliseconds(start, stop, step) ​

d3.utcMillisecond.range のエイリアス。

utcSeconds(start, stop, step) ​

d3.utcSecond.range のエイリアス。

utcMinutes(start, stop, step) ​

d3.utcMinute.range のエイリアス。

utcHours(start, stop, step) ​

d3.utcHour.range のエイリアス。

utcDays(start, stop, step) ​

d3.utcDay.range のエイリアス。

utcWeeks(start, stop, step) ​

d3.utcWeek.range のエイリアス。

utcSundays(start, stop, step) ​

d3.utcSunday.range のエイリアス。

utcMondays(start, stop, step) ​

d3.utcMonday.range のエイリアス。

utcTuesdays(start, stop, step) ​

d3.utcTuesday.range のエイリアス。

utcWednesdays(start, stop, step) ​

d3.utcWednesday.range のエイリアス。

utcThursdays(start, stop, step) ​

d3.utcThursday.range のエイリアス。

utcFridays(start, stop, step) ​

d3.utcFriday.range のエイリアス。

utcSaturdays(start, stop, step) ​

d3.utcSaturday.range のエイリアス。

utcMonths(start, stop, step) ​

d3.utcMonth.range のエイリアス。

utcYears(start, stop, step) ​

d3.utcYear.range のエイリアス。

timeTicks(start, stop, count) ​

ソースコード · d3.utcTicks と同等ですが、ローカル時間で計算します。

timeTickInterval(start, stop, count) ​

ソースコード · 同じ引数を与えられた場合にd3.timeTicksで使用される時間間隔を返します。

utcTicks(start, stop, count) ​

ソースコード · startとstop（を含む）の間で、ほぼcount個の、規則正しい間隔で配置された日付の配列を返します。stopがstartより前の場合は、逆の年代順で日付が返されます。そうでない場合は、年代順で日付が返されます。以下のUTC時間間隔が考慮されます。

  • 1秒
  • 5秒
  • 15秒
  • 30秒
  • 1分
  • 5分
  • 15分
  • 30分
  • 1時間
  • 3時間
  • 6時間
  • 12時間
  • 1日
  • 2日
  • 1週間
  • 1ヶ月
  • 3ヶ月
  • 1年

d3.ticksのルールに従って、（短い範囲の場合は）ミリ秒の倍数、（長い範囲の場合は）年の倍数も考慮されます。 countに最も近い日付数を生成する間隔が使用されます。例えば

js
const start = new Date("1970-03-01");
const stop = new Date("1996-03-19");
const count = 4;
const ticks = d3.utcTicks(start, stop, count); // [1975-01-01, 1980-01-01, 1985-01-01, 1990-01-01, 1995-01-01]

countが時間間隔の場合、この関数はinterval.rangeと同様に動作しますが、startとstopの両方が包括的であり、stopがstartより前の場合は、日付を逆の年代順で返す場合があります。

utcTickInterval(start, stop, count) ​

ソースコード · 同じ引数を与えられた場合にd3.utcTicksで使用される時間間隔を返します。startまたはstopが無効な場合など、関連する間隔がない場合は、nullを返します。

js
const start = new Date("1970-03-01");
const stop = new Date("1996-03-19");
const count = 4;
const interval = d3.utcTickInterval(start, stop, count); // d3.utcYear.every(5)