--- title: "MidDate" language: "en" type: "Symbol" summary: "MidDate[datespec] gives the midpoint instant of a date or list of dates datespec. MidDate[datespec, gran] gives the midpoint date object with granularity gran. MidDate[datespec, gran, x] gives the date that is the fraction x between the beginning and end of datespec." keywords: - intermediate date - middle date - central date canonical_url: "https://reference.wolfram.com/language/ref/MidDate.html" source: "Wolfram Language Documentation" related_guides: - title: "Date & Time" link: "https://reference.wolfram.com/language/guide/DateAndTime.en.md" related_functions: - title: "MinDate" link: "https://reference.wolfram.com/language/ref/MinDate.en.md" - title: "MaxDate" link: "https://reference.wolfram.com/language/ref/MaxDate.en.md" - title: "DateBounds" link: "https://reference.wolfram.com/language/ref/DateBounds.en.md" - title: "Mean" link: "https://reference.wolfram.com/language/ref/Mean.en.md" - title: "Median" link: "https://reference.wolfram.com/language/ref/Median.en.md" - title: "CentralFeature" link: "https://reference.wolfram.com/language/ref/CentralFeature.en.md" --- # MidDate MidDate[datespec] gives the midpoint instant of a date or list of dates datespec. MidDate[datespec, gran] gives the midpoint date object with granularity gran. MidDate[datespec, gran, x] gives the date that is the fraction x between the beginning and end of datespec. ## Details and Options * ``MidDate`` gives the date that is midway through a given date or list of dates. * Possible forms of ``datespec`` in ``MidDate[datespec, …]`` include: | | | | --------------- | ------------------------------------------------ | | DateObject[…] | mid date of a date object of any granularity | | TimeObject[…] | mid time of a time object of any granularity | | DateInterval[…] | mid date of a date interval | | {d1, d2, …} | mid date of a list of dates, times and intervals | | TimeSeries[…] | mid date of the times of a time series | | EventSeries[…] | mid date of the times of an event series | | TemporalData[…] | mid date of the times of temporal data | * ``MidDate[{d1, d2, …}]`` gives the midpoint instant based on the sum of probability density functions for a uniform distribution of the ``di`` dates. * ``MidDate`` takes the following options: | | | | | --------------- | --------- | --------------------------------------- | | CalendarType | Automatic | calendar for generated date | | DateFormat | Automatic | format used to display date | | DateGranularity | Automatic | calendar granularity for generated date | | Method | Automatic | midpoint detection method | | TimeSystem | Automatic | time system being used | | TimeZone | Automatic | time zone being used | * With ``MidDate[{d1, d2, …}, Method -> method]``, the ``Method`` option value ``method`` determines how midpoint dates are calculated for the ``di`` dates. Possible ``Method`` values include: | | | | ---------------- | --------------------------------------------- | | "GranularMean" | mean weighted by granularity length (default) | | "GranularMedian" | median weighted by granularity length | | "WeightedMean" | mean weighted by full duration of each date | | "UnionedMean" | mean of the unioned region of all dates | | "MidpointMean" | mean of midpoints | | "MidpointMedian" | median of midpoints | | "BoundsMean" | mean of the date bounds | --- ## Examples (23) ### Basic Examples (4) Get the midpoint instant for a month-granular date: ```wl In[1]:= MidDate[DateObject[{2024, 9}, "Month", "Gregorian", -5.]] Out[1]= DateObject[{2024, 9, 16, 0, 0, 0.}, "Instant", "Gregorian", -5.] ``` --- Find the day that falls in the middle of a year: ```wl In[1]:= MidDate[DateObject[{2024}, "Year", "Gregorian", -5.], "Day"] Out[1]= DateObject[{2024, 7, 2}, "Day"] ``` --- Find the hour that is 2/3 of the way through a given week: ```wl In[1]:= MidDate[DateObject[{2024, 9, 30}, "Week", "Gregorian", -5.], "Hour", 2 / 3] Out[1]= DateObject[{2024, 10, 4, 16}, "Hour", "Gregorian", -5.] ``` --- Find the mid date of three instants in the year 2024: ```wl In[1]:= MidDate[{DateObject[{2024, 12, 30, 18, 1, 56.774}, "Instant", "Gregorian", -5.], DateObject[{2024, 4, 8, 12, 54, 47.1752}, "Instant", "Gregorian", -5.], DateObject[{2024, 8, 13, 22, 45, 35.5214}, "Instant", "Gregorian", -5.]}] Out[1]= DateObject[{2024, 8, 17, 17, 54, 6.49018}, "Instant", "Gregorian", -5.] ``` ### Scope (7) For list inputs, the midpoint is taken based on the implicit interval for each date in the list: ```wl In[1]:= dates = {DateObject[{2024, 10, 1}, "Day"], DateObject[{2024, 10, 3}, "Day"]}; In[2]:= mid = MidDate[dates, "Day"] Out[2]= DateObject[{2024, 10, 2}, "Day"] ``` The full time interval for each date is taken into account: ```wl In[3]:= TimelinePlot[{DateInterval /@ dates, {DateInterval@mid}}] Out[3]= [image] ``` --- For mid dates with coarse granularity, the date given corresponds to the instance that encompasses the midpoint, even if it begins before the first date: ```wl In[1]:= MidDate[{DateObject[{2024, 10, 3}, "Day"], DateObject[{2024, 10, 5}, "Day", "Gregorian", -5.], DateObject[{2024, 10, 5}, "Day"]}, "Month"] Out[1]= DateObject[{2024, 10}, "Month"] ``` --- Get the mid date for an ``EventSeries`` : ```wl In[1]:= ts = EarthquakeData[All, 8, {{2020, 1, 1}, {2022, 5, 16}}, "Magnitude"] Out[1]= TemporalData[EventSeries, {{{8.100000381469727, 8.100000381469727, 8., 8.199999809265137, 8.100000381469727}}, {{{3.823856912*^9, 3.823856913*^9, 3.823856915*^9, 3.836510148*^9, 3.83776412*^9}}}, 1, {"Discrete", 1}, {"Discrete", 1}, 1, {ResamplingMethod -> None, ValueDimensions -> 1}}, True, 314.1] In[2]:= MidDate[ts] Out[2]= DateObject[{2021, 5, 24, 2, 1, 56.}, "Instant", "Gregorian", -5.] ``` --- Get the mid date from a ``Databin`` : ```wl In[1]:= MidDate[Databin["1qGFQ8v"]] Out[1]= DateObject[{2014, 2, 21, 11, 16, 2.}, "Instant", "Gregorian", -5.] ``` --- Find the mid date for an ``Association`` : ```wl In[1]:= MidDate[<|"date1" -> DateObject[{2024, 9, 22}, "Day"], "date2" -> DateObject[{2024, 4, 24}, "Day"], "date3" -> DateObject[{2024, 10, 28}, "Day"]|>] Out[1]= DateObject[{2024, 8, 15, 4, 0, 0}, "Instant", "Gregorian", -5.] ``` --- Find the mid time of five times today: ```wl In[1]:= RandomTime[5, DateGranularity -> "Minute"]//MidDate Out[1]= DateObject[{2024, 10, 9, 9, 41, 54}, "Instant", "Gregorian", -5.] ``` --- Find the midpoint instant of three date intervals: ```wl In[1]:= DateInterval /@ RandomDate[{3, 2}] Out[1]= {DateInterval[{{{2024, 3, 22, 8, 9, 23.266915321350098}, {2024, 7, 3, 2, 8, 9.82506799697876}}}, "Instant", "Gregorian", -5.], DateInterval[{{{2024, 11, 17, 7, 24, 11.214188575744629}, {2024, 11, 25, 22, 56, 49.68836069107056}}}, "Instant", "Gregorian", -5.], DateInterval[{{{2024, 5, 11, 8, 10, 49.19735908508301}, {2024, 10, 21, 22, 9, 44.79204082489014}}}, "Instant", "Gregorian", -5.]} In[2]:= MidDate[%] Out[2]= DateObject[{2024, 8, 11, 19, 49, 51.3307}, "Instant", "Gregorian", -5.] ``` ### Options (9) #### CalendarType (1) Return the midpoint date in the Japanese calendar: ```wl In[1]:= MidDate[DateObject[{2024}, "Year", "Gregorian", -5.], CalendarType -> "Japanese"] Out[1]= DateObject[{"Reiwa", 6, 7, 2, 0, 0, 0.}, "Instant", "Japanese", -5.] ``` #### DateFormat (1) Return the midpoint date in an ``"ISODateTime"`` format: ```wl In[1]:= MidDate[DateObject[{2024, 10}, "Month", "Gregorian", -5.], DateFormat -> "ISODateTime"] Out[1]= DateObject[{2024, 10, 16, 12, 0, 0.}, "Instant", "Gregorian", -5., "UT", "ISODateTime"] ``` #### Method (5) The default midpoint detection method (``"GranularMean"``) takes into account granularity length when selecting a midpoint: ```wl In[1]:= MidDate[{DateObject[{2024, 10, 1}, "Day"], DateObject[{2024, 10, 7}, "Week"]}] Out[1]= DateObject[{2024, 10, 9, 9, 0, 0}, "Instant", "Gregorian", -5.] ``` This means a one-week period is weighted equally whether it appears as a single ``"Week"`` date or as a sequence of seven ``"Day"`` dates: ```wl In[2]:= MidDate[{DateObject[{2024, 10, 1}, "Day"], DateObject[{2024, 10, 7}, "Day"], DateObject[{2024, 10, 8}, "Day"], DateObject[{2024, 10, 9}, "Day"], DateObject[{2024, 10, 10}, "Day"], DateObject[{2024, 10, 11}, "Day"], DateObject[{2024, 10, 12}, "Day"], DateObject[{2024, 10, 13}, "Day"]}] Out[2]= DateObject[{2024, 10, 9, 9, 0, 0}, "Instant", "Gregorian", -5.] ``` --- The method ``"WeightedMean"`` takes into account the full length of each date, not just its granularity: ```wl In[1]:= MidDate[{DateObject[{2024, 2}, "Month"], DateObject[{2024, 4}, "Month"]}, "Day"] Out[1]= DateObject[{2024, 3, 16}, "Day"] In[2]:= MidDate[{DateObject[{2024, 2}, "Month"], DateObject[{2024, 4}, "Month"]}, "Day", Method -> "WeightedMean"] Out[2]= DateObject[{2024, 3, 17}, "Day"] ``` --- The method ``"MidpointMedian"`` gives equal weight to all dates, regardless of granularity: ```wl In[1]:= MidDate[{DateObject[{2024, 2}, "Month"], DateObject[{2024, 10, 4}, "Day"]}, "Day"] Out[1]= DateObject[{2024, 2, 22}, "Day"] In[2]:= MidDate[{DateObject[{2024, 2}, "Month"], DateObject[{2024, 10, 4}, "Day"]}, "Day", Method -> "MidpointMedian"] Out[2]= DateObject[{2024, 6, 10}, "Day"] ``` --- The method ``"BoundsMean"`` considers only the outer date bounds of the dates: ```wl In[1]:= MidDate[{DateObject[{2024, 2}, "Month"], DateObject[{2024, 11}, "Month", "Gregorian", -5.]}, "Day", Method -> "BoundsMean"] Out[1]= DateObject[{2024, 7, 1}, "Day"] In[2]:= MidDate[{DateObject[{2024, 2}, "Month"], DateObject[{2024, 3}, "Month"], DateObject[{2024, 4}, "Month"], DateObject[{2024, 11}, "Month", "Gregorian", -5.]}, "Day", Method -> "BoundsMean"] Out[2]= DateObject[{2024, 7, 1}, "Day"] ``` --- Some midpoint detection methods weight for granularity, while others treat all dates as equally weighted: ```wl In[1]:= dates = {DateObject[{2024, 10, 1}, "Day"], DateObject[{2024, 10, 7}, "Week"]}; In[2]:= dates8 = {DateObject[{2024, 10, 1}, "Day"], DateObject[{2024, 10, 7}, "Day"], DateObject[{2024, 10, 8}, "Day"], DateObject[{2024, 10, 9}, "Day"], DateObject[{2024, 10, 10}, "Day"], DateObject[{2024, 10, 11}, "Day"], DateObject[{2024, 10, 12}, "Day"], DateObject[{2024, 10, 13}, "Day"]}; In[3]:= weighted = {"GranularMean", "GranularMedian", "WeightedMean"}; In[4]:= midpoint = {"MidpointMean", "MidpointMedian"}; ``` With only two dates given, ``"Weighted"`` methods will account for granularity and be pulled toward coarser granularity dates: ```wl In[5]:= TimelinePlot[{DateInterval /@ dates, Splice[{MidDate[dates, Method -> #]}& /@ weighted]}, PlotLegends -> Prepend[weighted, "intervals"], ImageSize -> 300] Out[5]= [image] ``` With the coarser granularity broken up into individual dates, the ``"Weighted"`` methods remain consistent: ```wl In[6]:= TimelinePlot[{DateInterval /@ dates8, Splice[{MidDate[dates8, Method -> #]}& /@ weighted]}, PlotLegends -> Prepend[weighted, "intervals"], ImageSize -> 300] Out[6]= [image] ``` Midpoint methods weight all dates equally and thus do not account for difference in granularity: ```wl In[7]:= TimelinePlot[{DateInterval /@ dates, Splice[{MidDate[dates, Method -> #]}& /@ midpoint]}, PlotLegends -> Prepend[midpoint, "intervals"], ImageSize -> 300] Out[7]= [image] ``` If broken into individual days, these midpoint methods will be pulled to the right: ```wl In[8]:= TimelinePlot[{DateInterval /@ dates8, Splice[{MidDate[dates8, Method -> #]}& /@ midpoint]}, PlotLegends -> Prepend[midpoint, "intervals"], ImageSize -> 300] Out[8]= [image] ``` ``"WeightedMean"`` and ``"UnionedMean"`` both account for the full duration of dates, but ``"WeightedMean"`` will account for overlapping intervals, while ``"UnionedMean"`` will flatten all intervals: ```wl In[9]:= oct = {DateObject[{2024, 10}, "Month"], DateObject[{2024, 10, 7}, "Week"]}; In[10]:= mean = {"WeightedMean", "UnionedMean"}; In[11]:= TimelinePlot[{DateInterval /@ oct, Splice[{MidDate[oct, Method -> #]}& /@ mean]}, PlotLegends -> Prepend[mean, "intervals"], ImageSize -> 300] Out[11]= [image] ``` #### TimeSystem (1) Return the midpoint date in the ``"TAI"`` time system: ```wl In[1]:= MidDate[DateObject[{2024, 9, 30}, "Week", "Gregorian", -5.], TimeSystem -> "TAI"] Out[1]= DateObject[{2024, 10, 3, 17, 0, 37.}, "Instant", "Gregorian", -5., "TAI"] ``` #### TimeZone (1) Return the midpoint date in GMT: ```wl In[1]:= MidDate[DateObject[{2024, 10}, "Quarter", "Gregorian", -5.], TimeZone -> "GMT"] Out[1]= DateObject[{2024, 11, 16, 5, 0, 0.}, "Instant", "Gregorian", "GMT"] ``` ### Applications (1) Find the release dates of all James Bond movies: ```wl In[1]:= releases = NumericalSort@EntityValue[EntityClass["Movie", "JamesBondFranchise"], "ReleaseDate", "Association"] Out[1]= <|Entity["Movie", "DrNo::34pn3"] -> DateObject[{1963, 5, 8}, "Day"], Entity["Movie", "FromRussiaWithLove::787df"] -> DateObject[{1964, 5, 27}, "Day"], Entity["Movie", "Goldfinger::nyzw4"] -> DateObject[{1965, 1, 9}, "Day"], Entity["Movie", "Thunder ... bject[{2008, 11, 14}, "Day"], Entity["Movie", "Skyfall::q5wfv"] -> DateObject[{2012, 11, 9}, "Day"], Entity["Movie", "Spectre::wxc7f"] -> DateObject[{2015, 11, 6}, "Day"], Entity["Movie", "NoTimeToDie::5648j"] -> DateObject[{2021, 10, 8}, "Day"]|> ``` Find the mid date of those release dates: ```wl In[2]:= MidDate[releases, "Day"] Out[2]= DateObject[{1986, 6, 13}, "Day"] ``` The midpoint of the bounds was six years later, reflecting an accumulation of releases in the early years: ```wl In[3]:= MidDate[releases, "Day", Method -> "BoundsMean"] Out[3]= DateObject[{1992, 7, 23}, "Day"] ``` ### Properties & Relations (1) ``Mean``, ``Median``, ``Quantile`` and ``CentralFeature`` all use different methods to find central dates: ```wl In[1]:= dates = {DateObject[{2024, 10, 20}, "Day"], DateObject[{2024, 10, 4, 15, 39, 20.336531}, "Instant", "Gregorian", -5.], DateObject[{2024, 10, 5}, "Day"], DateObject[{2024, 10, 1}, "Day"]}; In[2]:= MidDate[dates] Out[2]= DateObject[{2024, 10, 9, 4, 0, 0}, "Instant", "Gregorian", -5.] In[3]:= Mean[dates] Out[3]= DateObject[{2024, 10, 7}, "Day"] In[4]:= Median[dates] Out[4]= DateObject[{2024, 10, 5}, "Day"] In[5]:= Quantile[dates, .5] Out[5]= DateObject[{2024, 10, 4}, "Day"] ``` ### Possible Issues (1) A list of numbers is interpreted by ``MidDate`` as a list of absolute times, not as a single date list: ```wl In[1]:= list = DateList[] Out[1]= {2024, 10, 9, 21, 40, 19.664795} In[2]:= MidDate[list] Out[2]= DateObject[{1900, 1, 1, 0, 5, 53.9441}, "Instant", "Gregorian", -5.] In[3]:= MidDate[DateObject[list]] Out[3]= DateObject[{2024, 10, 9, 21, 40, 19.6648}, "Instant", "Gregorian", -5.] ``` ## See Also * [`MinDate`](https://reference.wolfram.com/language/ref/MinDate.en.md) * [`MaxDate`](https://reference.wolfram.com/language/ref/MaxDate.en.md) * [`DateBounds`](https://reference.wolfram.com/language/ref/DateBounds.en.md) * [`Mean`](https://reference.wolfram.com/language/ref/Mean.en.md) * [`Median`](https://reference.wolfram.com/language/ref/Median.en.md) * [`CentralFeature`](https://reference.wolfram.com/language/ref/CentralFeature.en.md) ## Related Guides * [Date & Time](https://reference.wolfram.com/language/guide/DateAndTime.en.md) ## History * [Introduced in 2025 (14.2)](https://reference.wolfram.com/language/guide/SummaryOfNewFeaturesIn142.en.md)