Overview
NumPy's datetime64 and timedelta64 types for time-series data.
NEP 7: Date/Time Types in NumPy
Status: Final | Full Text
Type Definitions
datetime64 (Absolute Time)
- 64-bit signed integer
- Units from POSIX epoch (January 1, 1970)
- NaT (Not a Time) = -2^63
timedelta64 (Relative Time)
- 64-bit signed integer
- Represents duration/interval
- NaT = -2^63
Time Units
| Code |
Meaning |
datetime64 Range |
| Y |
year |
± 9.2e18 years |
| M |
month |
± 7.6e17 years |
| W |
week |
± 1.7e17 years |
| D |
day |
± 2.5e16 years |
| h |
hour |
± 1.0e15 years |
| m |
minute |
± 1.7e13 years |
| s |
second |
± 2.9e12 years |
| ms |
millisecond |
± 2.9e9 years |
| us |
microsecond (default) |
± 2.9e6 years |
| ns |
nanosecond |
± 292 years |
| ps |
picosecond |
± 106 days |
| fs |
femtosecond |
± 2.6 hours |
| as |
attosecond |
± 9.2 seconds |
Operations
datetime64 vs datetime64
- Subtraction: → timedelta64
- Comparisons: ==, !=, <, >, <=, >=
- NOT allowed: addition, multiplication, division
datetime64 vs timedelta64
- Add/Subtract: → datetime64
timedelta64 vs timedelta64
- All arithmetic: +, -, *, /
- Result unit: More precise of the two
String Notation
dtype('datetime64[us]') # Long form
dtype('M8[us]') # Short form
dtype('timedelta64[ms]') # Long form
dtype('m8[ms]') # Short form
# With multiples
dtype('M8[100ns]') # 100 nanoseconds
dtype('M8[3M]') # 3 months
String Parsing
# ISO 8601 format
t[0] = '2008-07-30T17:31:02'
# Integer (seconds since epoch)
t[1] = 1199164176
# Python datetime
t[2] = datetime.datetime(2008, 7, 30, 17, 31, 1)
Suggested Implementation for NumSharp
New Type Codes
enum NPTypeCode {
// ... existing ...
DateTime64, // M8
TimeDelta64, // m8
}
Unit Metadata
enum DateTimeUnit {
Year, Month, Week, Day,
Hour, Minute, Second,
Millisecond, Microsecond, Nanosecond,
Picosecond, Femtosecond, Attosecond
}
class DateTimeDescriptor {
public DateTimeUnit Unit { get; }
public int Multiple { get; } // e.g., 100 for M8[100ns]
}
Storage
// Internal storage: Int64
// With unit metadata attached to dtype
public struct DateTime64 {
public long Value;
public DateTimeUnit Unit;
public bool IsNaT => Value == long.MinValue;
}
C# Type Mapping
// Conversion helpers
public static DateTime64 FromDateTime(DateTime dt, DateTimeUnit unit);
public static DateTime ToDateTime(DateTime64 dt64);
public static TimeDelta64 FromTimeSpan(TimeSpan ts, DateTimeUnit unit);
public static TimeSpan ToTimeSpan(TimeDelta64 td64);
Operation Rules
// datetime64 - datetime64 = timedelta64
public static NDArray Subtract(NDArray a, NDArray b) {
if (a.TypeCode == NPTypeCode.DateTime64 &&
b.TypeCode == NPTypeCode.DateTime64) {
return SubtractDateTimes(a, b); // Returns timedelta64
}
// ...
}
String Parsing
// ISO 8601 parsing
public static DateTime64 Parse(string iso8601, DateTimeUnit unit) {
var dt = DateTime.Parse(iso8601);
return FromDateTime(dt, unit);
}
Documentation
See docs/neps/NEP07.md
Overview
NumPy's datetime64 and timedelta64 types for time-series data.
NEP 7: Date/Time Types in NumPy
Status: Final | Full Text
Type Definitions
datetime64 (Absolute Time)
timedelta64 (Relative Time)
Time Units
Operations
datetime64 vs datetime64
datetime64 vs timedelta64
timedelta64 vs timedelta64
String Notation
String Parsing
Suggested Implementation for NumSharp
New Type Codes
Unit Metadata
Storage
C# Type Mapping
Operation Rules
String Parsing
Documentation
See
docs/neps/NEP07.md