-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add basic documentation and examples
- Loading branch information
1 parent
609e95b
commit db7c085
Showing
8 changed files
with
120 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
*.csv filter=lfs diff=lfs merge=lfs -text |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,58 @@ | ||
# `tz-canary` - Time Zone Canary | ||
|
||
In a perfect world, all time series data is time-zone-aware and stored in UTC. | ||
Sadly, we do not live in a perfect world. | ||
Time series data often lacks a time zone identifier, or worse, does not actually adhere to the time zone it claims to be in. | ||
|
||
`tz-canary` inspects the Daylight Savings Time (DST) switches in a time series to infer a set of plausible time zones the data could be in. | ||
It allows you to **infer** the full set of plausible time zones for the data, or to **validate** whether a given time zone is plausible for the data. | ||
|
||
## Installation | ||
|
||
TODO - after pushing v0.1.0 to PyPI | ||
|
||
## Usage | ||
|
||
The simplest way to use `tz-canary` is to validate a given time zone for a time series: | ||
|
||
```python | ||
import pandas as pd | ||
from tz_canary import validate_time_zone | ||
|
||
df = pd.read_csv("docs/data/example_data.csv", index_col="datetime", parse_dates=True) | ||
|
||
validate_time_zone(df.index, "Europe/Amsterdam") # will pass | ||
validate_time_zone(df.index, "America/New_York") # will raise ImplausibleTimeZoneError | ||
validate_time_zone(df.index, "UTC") # will raise ImplausibleTimeZoneError | ||
``` | ||
|
||
You can also get a list of all plausible time zones for a time series: | ||
|
||
```python | ||
from pprint import pprint | ||
|
||
import pandas as pd | ||
from tz_canary import infer_time_zone | ||
|
||
df = pd.read_csv("docs/data/example_data.csv", index_col="datetime", parse_dates=True) | ||
|
||
plausible_time_zones = infer_time_zone(df.index) | ||
pprint(plausible_time_zones) | ||
|
||
# Output: | ||
# {zoneinfo.ZoneInfo(key='Africa/Ceuta'), | ||
# zoneinfo.ZoneInfo(key='Arctic/Longyearbyen'), | ||
# zoneinfo.ZoneInfo(key='Europe/Amsterdam'), | ||
# ... | ||
# zoneinfo.ZoneInfo(key='Europe/Zurich')} | ||
``` | ||
|
||
TODO - add example for building a `TransitionsData` object and using that to validate/infer many time series. | ||
|
||
## Development | ||
|
||
TODO - add overview of setup (git LFS, poetry, pre-commit, pytest, etc.) | ||
|
||
## Contributing | ||
|
||
TODO - add contributing guidelines |
Git LFS file not shown
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,24 @@ | ||
import pandas as pd | ||
|
||
|
||
def generate_example_data(): | ||
df_example = pd.DataFrame( | ||
index=pd.date_range( | ||
start="2023-01-01", | ||
end="2023-12-31", | ||
freq="15T", | ||
tz="Europe/Amsterdam", | ||
name="datetime", | ||
), | ||
data={"best_color": "orange"}, | ||
) | ||
|
||
# We strip the time zone information from the index to simulate a file that does not | ||
# specify time zone information. | ||
df_example.index = df_example.index.tz_localize(None) | ||
|
||
df_example.to_csv("example_data.csv") | ||
|
||
|
||
if __name__ == "__main__": | ||
generate_example_data() |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,17 @@ | ||
from pprint import pprint | ||
|
||
import pandas as pd | ||
|
||
from tz_canary import infer_time_zone | ||
|
||
df = pd.read_csv("docs/data/example_data.csv", index_col="datetime", parse_dates=True) | ||
|
||
plausible_time_zones = infer_time_zone(df.index) | ||
pprint(plausible_time_zones) | ||
|
||
# Output: | ||
# {zoneinfo.ZoneInfo(key='Africa/Ceuta'), | ||
# zoneinfo.ZoneInfo(key='Arctic/Longyearbyen'), | ||
# zoneinfo.ZoneInfo(key='Europe/Amsterdam'), | ||
# ... | ||
# zoneinfo.ZoneInfo(key='Europe/Zurich')} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
import pandas as pd | ||
|
||
from tz_canary import validate_time_zone | ||
|
||
df = pd.read_csv("docs/data/example_data.csv", index_col="datetime", parse_dates=True) | ||
|
||
validate_time_zone(df.index, "Europe/Amsterdam") # will pass | ||
validate_time_zone(df.index, "America/New_York") # will raise ImplausibleTimeZoneError | ||
validate_time_zone(df.index, "UTC") # will raise ImplausibleTimeZoneError |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
from tz_canary.exceptions import ImplausibleTimeZoneError # noqa: F401 | ||
from tz_canary.infer import infer_time_zone # noqa: F401 | ||
from tz_canary.transitions_data import TransitionsData # noqa: F401 | ||
from tz_canary.validate import validate_time_zone # noqa: F401 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters