├── .gitignore ├── .github ├── dependabot.yml ├── notebook_lists │ └── vanilla_notebooks.txt └── workflows │ └── notebooks.yaml ├── .pre-commit-config.yaml ├── ruff.toml ├── LICENSE-data ├── README.md ├── recipes ├── Retail_Forecasting │ ├── M5_retail_data_prep.py │ └── M5_retail_sales_forecasting.ipynb ├── Time_Series │ └── Getting_Started_with_WatsonX_AI_SDK.ipynb └── Classification │ └── Getting_Started_with_TSPulse_Classification.ipynb ├── LICENSE-code └── LICENSE /.gitignore: -------------------------------------------------------------------------------- 1 | venv 2 | .venv 3 | .venv* 4 | .env 5 | .ipynb_checkpoints 6 | .vscode 7 | .idea 8 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | # SPDX-License-Identifier: Apache-2.0 2 | 3 | # GitHub Dependabot configuration file 4 | version: 2 5 | updates: 6 | # Maintain dependencies for GitHub Actions 7 | - package-ecosystem: "github-actions" 8 | directories: 9 | - "/" 10 | schedule: 11 | interval: "daily" 12 | -------------------------------------------------------------------------------- /.pre-commit-config.yaml: -------------------------------------------------------------------------------- 1 | # See https://pre-commit.com for more information 2 | # See https://pre-commit.com/hooks.html for more hooks 3 | # Run `pre-commit install` to activate pre-commit hooks 4 | repos: 5 | - repo: https://github.com/kynan/nbstripout 6 | rev: 0.8.1 7 | hooks: 8 | - id: nbstripout 9 | args: [ 10 | "--extra-keys", "metadata.language_info.version metadata.kernelspec", 11 | "--keep-metadata-keys", "cell.metadata.collapsed cell.metadata.scrolled", 12 | ] -------------------------------------------------------------------------------- /ruff.toml: -------------------------------------------------------------------------------- 1 | line-length = 119 2 | lint.ignore = ["C901", "E501", "E741", "F402", "F823"] 3 | lint.select = ["C", "E", "F", "I", "W"] 4 | extend-include = ["*.ipynb"] 5 | 6 | [lint.isort] 7 | lines-after-imports = 2 8 | known-first-party = ["tsfm_public"] 9 | 10 | [format] 11 | # Like Black, use double quotes for strings. 12 | quote-style = "double" 13 | 14 | # Like Black, indent with spaces, rather than tabs. 15 | indent-style = "space" 16 | 17 | # Like Black, respect magic trailing commas. 18 | skip-magic-trailing-comma = false 19 | 20 | # Like Black, automatically detect the appropriate line ending. 21 | line-ending = "auto" 22 | -------------------------------------------------------------------------------- /.github/notebook_lists/vanilla_notebooks.txt: -------------------------------------------------------------------------------- 1 | recipes/Time_Series/Time_Series_Getting_Started.ipynb 2 | recipes/Time_Series/Bike_Sharing_Finetuning_with_Exogenous.ipynb 3 | recipes/Time_Series/Few-shot_Finetuning_and_Evaluation.ipynb 4 | recipes/Time_Series/Preprocessor_Use_and_Performance_Evaluation.ipynb 5 | recipes/Time_Series/Getting_Started_with_WatsonX_AI_SDK.ipynb 6 | recipes/Retail_Forecasting/M5_retail_sales_forecasting.ipynb 7 | recipes/Classification/Getting_Started_with_TSPulse_Classification.ipynb 8 | recipes/Imputation/Getting_Started_with_TSPulse_Imputation.ipynb 9 | recipes/Search/Getting_Started_with_TSPulse_Search.ipynb 10 | -------------------------------------------------------------------------------- /LICENSE-data: -------------------------------------------------------------------------------- 1 | Community Data License Agreement - Permissive - Version 2.0 2 | 3 | This is the Community Data License Agreement - Permissive, Version 2.0 (the "agreement"). Data Provider(s) and Data Recipient(s) agree as follows: 4 | 5 | 1. Provision of the Data 6 | 7 | 1.1. A Data Recipient may use, modify, and share the Data made available by Data Provider(s) under this agreement if that Data Recipient follows the terms of this agreement. 8 | 9 | 1.2. This agreement does not impose any restriction on a Data Recipient's use, modification, or sharing of any portions of the Data that are in the public domain or that may be used, modified, or shared under any other legal exception or limitation. 10 | 11 | 2. Conditions for Sharing Data 12 | 13 | 2.1. A Data Recipient may share Data, with or without modifications, so long as the Data Recipient makes available the text of this agreement with the shared Data. 14 | 15 | 3. No Restrictions on Results 16 | 17 | 3.1. This agreement does not impose any restriction or obligations with respect to the use, modification, or sharing of Results. 18 | 19 | 4. No Warranty; Limitation of Liability 20 | 21 | 4.1. All Data Recipients receive the Data subject to the following terms: 22 | 23 | THE DATA IS PROVIDED ON AN "AS IS" BASIS, WITHOUT REPRESENTATIONS, WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 24 | 25 | NO DATA PROVIDER SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE DATA OR RESULTS, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 26 | 27 | 5. Definitions 28 | 29 | 5.1. "Data" means the material received by a Data Recipient under this agreement. 30 | 31 | 5.2. "Data Provider" means any person who is the source of Data provided under this agreement and in reliance on a Data Recipient's agreement to its terms. 32 | 33 | 5.3. "Data Recipient" means any person who receives Data directly or indirectly from a Data Provider and agrees to the terms of this agreement. 34 | 35 | 5.4. "Results" means any outcome obtained by computational analysis of Data, including for example machine learning models and models' insights. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # IBM Granite Time Series Cookbook 2 | 3 | The "Recipes" in the Granite Time Series Cookbook showcase the capabilities of 4 | the IBM Granite Time Series models. 5 | 6 | ## Recipes 7 | 8 | 1. [Energy Demand Forecasting - Basic Inference](recipes/Time_Series/Time_Series_Getting_Started.ipynb) 9 | 2. [Energy Demand Forecasting - Preprocessing and Performance Evaluation](recipes/Time_Series/Preprocessor_Use_and_Performance_Evaluation.ipynb) 10 | 3. [Energy Demand Forecasting - Few-shot Fine-tuning](recipes/Time_Series/Few-shot_Finetuning_and_Evaluation.ipynb) 11 | 4. [Bike Sharing Forecasting - Zero-shot, Fine-tuning, and Performance Evaluation](recipes/Time_Series/Bike_Sharing_Finetuning_with_Exogenous.ipynb) 12 | 5. [Getting Started with Watson X AI SDK](recipes/Time_Series/Getting_Started_with_WatsonX_AI_SDK.ipynb) 13 | 6. [Retail Forecasting using M5 Sales Data - Few-shot, Fine-tuning, Evaluation, and Visualization](recipes/Retail_Forecasting/M5_retail_sales_forecasting.ipynb) 14 | 7. [BasicMotions Classification - Fine-tuning and Performance Evaluation](recipes/Classification/Getting_Started_with_TSPulse_Classification.ipynb) 15 | 8. [Bike Sharing missing data Imputation - Zero-Shot](recipes/Imputation/Getting_Started_with_TSPulse_Imputation.ipynb) 16 | 9. [Getting Started with Time-Series Search - Zero-Shot](recipes/Search/Getting_Started_with_TSPulse_Search.ipynb) 17 | 18 | ## Build Status 19 | 20 | 21 | Testing Notebooks 22 | 23 | 24 | ## Contributing 25 | 26 | For information about contributing to this repo, code of conduct guidelines, etc., see the community [CONTRIBUTING][CG] and [Code of Conduct][CoC] guides. All commits require DCO-signoff (discussed [here][CG-legal]) _and_ GPG or SSH signing (discussed [here][CG-signing]). The GitHub recommended code security settings are enforced on this public repository (which include the signing requirement). 27 | 28 | For more background and a FAQ, please see the [community wiki](https://github.com/ibm-granite-community/community/wiki) 29 | 30 | ## Licenses 31 | 32 | The Granite Time Series Cookbook's base license is CC BY 4.0. 33 | 34 | Code in this repository, including in notebook cells, is licensed under Apache 2.0. 35 | 36 | Any example datasets committed to this repository are licensed under CDLA Permissive 2.0. 37 | 38 | ## IBM Public Repository Disclosure 39 | 40 | All content in these repositories including code has been provided by IBM under the associated open source software license and IBM is under no obligation to provide enhancements, updates, or support. IBM developers produced this code as an open source project (not as an IBM product), and IBM makes no assertions as to the level of quality nor security, and will not be maintaining this code going forward. 41 | 42 | [CoC]: https://github.com/ibm-granite-community/community/blob/main/CODE_OF_CONDUCT.md 43 | [CG]: https://github.com/ibm-granite-community/community/blob/main/CONTRIBUTING.md 44 | [CG-legal]: https://github.com/ibm-granite-community/community/blob/main/CONTRIBUTING.md#legal 45 | [CG-signing]: https://github.com/ibm-granite-community/community/blob/main/CONTRIBUTING.md#signing-commits 46 | -------------------------------------------------------------------------------- /.github/workflows/notebooks.yaml: -------------------------------------------------------------------------------- 1 | # SPDX-License-Identifier: Apache-2.0 2 | 3 | name: Testing Notebooks 4 | 5 | on: 6 | schedule: # Test all notebooks daily 7 | - cron: '0 11 * * *' 8 | workflow_dispatch: # Test notebooks on demand 9 | inputs: 10 | pr: 11 | description: 'Pull Request number or leave empty for all notebooks' 12 | required: false 13 | type: string 14 | default: '' 15 | push: 16 | branches: 17 | - main 18 | paths: 19 | - '.github/workflows/notebooks.yaml' # This workflow 20 | - '.github/notebook_lists/*' # Notebook lists 21 | - 'recipes/**/*.ipynb' 22 | pull_request: 23 | branches: 24 | - main 25 | paths: 26 | - '.github/workflows/notebooks.yaml' # This workflow 27 | - '.github/notebook_lists/*' # Notebook lists 28 | - 'recipes/**/*.ipynb' 29 | 30 | env: 31 | LC_ALL: en_US.UTF-8 32 | 33 | defaults: 34 | run: 35 | shell: bash 36 | 37 | permissions: 38 | contents: read 39 | 40 | jobs: 41 | test_workflow_ready: 42 | # Don't run schedule target in forks 43 | if: ${{ (github.event_name != 'schedule') || (github.repository_owner == 'ibm-granite-community') }} 44 | permissions: 45 | pull-requests: write 46 | statuses: write 47 | runs-on: ubuntu-latest 48 | outputs: 49 | ref: ${{ inputs.pr && format('refs/pull/{0}/merge',inputs.pr) || '' }} 50 | all: ${{ contains(fromJSON('["schedule","workflow_dispatch"]'), github.event_name) && !inputs.pr }} 51 | status_url: ${{ steps.pr.outputs.status_url }} 52 | run_url: ${{ steps.pr.outputs.run_url }} 53 | steps: 54 | - name: "Harden Runner" 55 | uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0 56 | with: 57 | disable-sudo-and-containers: true 58 | egress-policy: block 59 | allowed-endpoints: > 60 | api.github.com:443 61 | github.com:443 62 | 63 | - name: Checkout 64 | if: ${{ inputs.pr }} 65 | id: checkout 66 | uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 67 | with: 68 | ref: ${{ inputs.pr && format('refs/pull/{0}/head',inputs.pr) || '' }} 69 | 70 | - name: Pull Request dispatch 71 | if: ${{ inputs.pr }} 72 | id: pr 73 | run: | 74 | echo "status_url=$STATUS_URL" >> "$GITHUB_OUTPUT" 75 | echo "run_url=$RUN_URL" >> "$GITHUB_OUTPUT" 76 | gh api -X POST "$STATUS_URL" -f "context=PR Test" -f "state=$STATUS_STATE" -f "description=$STATUS_DESCRIPTION" -f "target_url=$RUN_URL&pr=$PR" 77 | gh pr comment "$PR" -b "$GITHUB_WORKFLOW workflow launched on this PR: [View run]($RUN_URL)" 78 | env: 79 | PR: ${{ inputs.pr }} 80 | STATUS_URL: ${{ github.api_url }}/repos/${{ github.repository }}/statuses/${{ steps.checkout.outputs.commit }} 81 | RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} 82 | STATUS_STATE: pending 83 | STATUS_DESCRIPTION: This check has started... 84 | GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} 85 | 86 | 87 | vanilla: 88 | needs: 89 | - test_workflow_ready 90 | permissions: 91 | contents: read 92 | uses: ibm-granite-community/utils/.github/workflows/test_notebook.yaml@main 93 | secrets: 94 | WATSONX_APIKEY: ${{ secrets.WATSONX_APIKEY }} 95 | WATSONX_PROJECT_ID: ${{ secrets.WATSONX_PROJECT_ID }} 96 | WATSONX_URL: ${{ secrets.WATSONX_URL }} 97 | with: 98 | notebook-lists: | 99 | .github/notebook_lists/vanilla_notebooks.txt 100 | python-versions: >- 101 | 3.11 102 | 3.12 103 | ref: ${{ needs.test_workflow_ready.outputs.ref }} 104 | all: ${{ fromJSON(needs.test_workflow_ready.outputs.all) }} 105 | 106 | test_workflow_complete: 107 | needs: 108 | - test_workflow_ready 109 | - vanilla 110 | permissions: 111 | pull-requests: write 112 | statuses: write 113 | runs-on: ubuntu-latest 114 | if: ${{ !cancelled() && (needs.test_workflow_ready.result == 'success') }} 115 | steps: 116 | - name: "Harden Runner" 117 | uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0 118 | with: 119 | disable-sudo-and-containers: true 120 | egress-policy: block 121 | allowed-endpoints: > 122 | api.github.com:443 123 | github.com:443 124 | 125 | - name: Pull Request dispatch 126 | if: ${{ inputs.pr }} 127 | run: | 128 | gh api -X POST "$STATUS_URL" -f "context=PR Test" -f "state=$STATUS_STATE" -f "description=$STATUS_DESCRIPTION" -f "target_url=$RUN_URL&pr=$PR" 129 | env: 130 | PR: ${{ inputs.pr }} 131 | STATUS_URL: ${{ needs.test_workflow_ready.outputs.status_url }} 132 | RUN_URL: ${{ needs.test_workflow_ready.outputs.run_url }} 133 | STATUS_STATE: ${{ (contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')) && 'failure' || 'success' }} 134 | STATUS_DESCRIPTION: ${{ (contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')) && 'Failure' || 'Success' }} 135 | GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} 136 | -------------------------------------------------------------------------------- /recipes/Retail_Forecasting/M5_retail_data_prep.py: -------------------------------------------------------------------------------- 1 | # Data Preparation for Granite-TSFM Retail Example 2 | 3 | # 4 | 5 | 6 | import logging 7 | import os 8 | from itertools import chain 9 | 10 | import numpy as np 11 | import pandas as pd 12 | 13 | 14 | logger = logging.getLogger(__file__) 15 | 16 | try: 17 | import gdown 18 | except ImportError: 19 | logger.error("Please install the `gdown` utility to enable downloading the data (`pip install gdown`).") 20 | 21 | 22 | def prepare_data(temp_dir: str = "temp/", force_download: bool = False): 23 | """Utility to prepare the state-level aggregated M5 dataset for use with granite-timeseries-ttm retail example 24 | 25 | Args: 26 | temp_dir (str): A folder for the temporary downloaded files, defaults to "temp/". 27 | force_download (bool): If True data will be downloaded again. Default False. 28 | 29 | Download the M5 datasets from the google drive mentioned on the official M-Competitions 30 | [repository](https://github.com/Mcompetitions/M5-methods). The google drive containing all datasets and 31 | additional competition information is 32 | [here](https://drive.google.com/drive/folders/1D6EWdVSaOtrP1LEFh1REjI3vej6iUS_4?usp=sharing). The required files 33 | are downloaded to a folder named temp, once the data is prepared, it is safe to delete this folder. 34 | """ 35 | 36 | if os.path.exists(temp_dir) and not force_download: 37 | logger.info("Temporary folder already exists, assuming data already downloaded.") 38 | else: 39 | gdown.download(id="1Bj7Xj15yn4j6-BM_mpSmOVTV0c2ihEdo", output=temp_dir) 40 | gdown.download(id="1-khP8tp1gRTfaQQV_PlKd6R_3Mw5KiBw", output=temp_dir) 41 | gdown.download(id="1eeU8Me44yzgWsDD0dYrX4xVOixil_H4u", output=temp_dir) 42 | 43 | df_calendar = pd.read_csv(os.path.join(temp_dir, "calendar.csv")) 44 | df_sales_train = pd.read_csv(os.path.join(temp_dir, "sales_train_evaluation.csv")) 45 | df_sales_test = pd.read_csv(os.path.join(temp_dir, "sales_test_evaluation.csv")) 46 | 47 | # add missing "d" column for later merging 48 | df_calendar["d"] = ( 49 | (pd.to_datetime(df_calendar["date"]) - pd.to_datetime(df_calendar["date"]).min()).dt.days + 1 50 | ).transform(lambda x: f"d_{x}") 51 | 52 | # Prepare Data 53 | """ 54 | The data is contained in two core files `sales_train_evaluation.csv` and `sales_test_evaluation.csv`. In each of 55 | these files, the rows represent complete time series for individual store-item combinations. For use with 56 | granite-timeseries-ttm, we need a single dataset where each row represents a single timestamp for a store-item 57 | combination. In addition, since we will be looking at the sales only at the combined state level sales, we need to 58 | aggregate by the state id. The overall data preparation strategy is as follows: 59 | 1. Aggregate the individual data frames by `state_id`. 60 | 2. Melt the data frames to transform the data to "long format", where each row has a timestamp 61 | 3. Concatenate the train and test into one dataset 62 | 4. Merge the calendar features from `calendar.csv` 63 | 5. Encode date features into numerical quantities 64 | 6. Add group statistics to the data 65 | 7. Format categorical columns 66 | 67 | After the data processing, we end up with a single dataframe containg three state-level time series. 68 | """ 69 | 70 | # Aggregate 71 | ID_VARS = ["state_id"] 72 | DATE_FEATURES = [ 73 | "date", 74 | "wm_yr_wk", 75 | "weekday", 76 | "wday", 77 | "month", 78 | "year", 79 | "snap_CA", 80 | "snap_TX", 81 | "snap_WI", 82 | "event_name_1", 83 | "event_type_1", 84 | "event_name_2", 85 | "event_type_2", 86 | ] 87 | 88 | df_sales_train = ( 89 | df_sales_train.groupby("state_id") 90 | .sum() 91 | .drop(columns=["item_id", "dept_id", "cat_id", "store_id"]) 92 | .reset_index() 93 | ) 94 | df_sales_train = df_sales_train.melt(id_vars=ID_VARS, var_name="d", value_name="sales") 95 | 96 | df_sales_test = ( 97 | df_sales_test.groupby("state_id") 98 | .sum() 99 | .drop(columns=["item_id", "dept_id", "cat_id", "store_id"]) 100 | .reset_index() 101 | ) 102 | df_sales_test = df_sales_test.melt(id_vars=ID_VARS, var_name="d", value_name="sales") 103 | df_all = pd.concat([df_sales_train, df_sales_test]).reset_index(drop=True) 104 | df_all = pd.merge(df_all, df_calendar[["d"] + DATE_FEATURES], on="d", how="left") 105 | 106 | # Encode date features using sin-cos embedding 107 | date_cols = [ 108 | "wm_yr_wk", 109 | "wday", 110 | "month", 111 | ] 112 | for k in date_cols: 113 | unq_nums = df_all[k].unique() 114 | period = len(unq_nums) 115 | # normalize 116 | df_all[k] = df_all[k] - df_all[k].min() 117 | # get encodings 118 | df_all[k + "_sin"] = np.sin(2 * np.pi * df_all[k] / period) 119 | 120 | # Add grouped statistics as used in lightGBM by winners 121 | df_tmp = df_all[["date", "d", "state_id", "sales"]].copy() 122 | df_tmp["idx"] = pd.to_datetime(df_tmp["date"]) 123 | df_tmp["idx"] = (df_tmp["idx"] - df_tmp["idx"].min()).dt.days + 1 124 | # mask out the sales during the test period 125 | df_tmp.loc[df_tmp["idx"] > (1941 - 28), "sales"] = np.nan 126 | 127 | icols = [ 128 | ["state_id"], 129 | ] 130 | 131 | for col in icols: 132 | col_name = "_" + "_".join(col) + "_" 133 | df_tmp["enc" + col_name + "mean"] = df_tmp.groupby(col)["sales"].transform("mean") 134 | df_tmp["enc" + col_name + "std"] = df_tmp.groupby(col)["sales"].transform("std") 135 | 136 | encoding_cols = [col for col in df_tmp.columns if col not in ["d", "date", "idx", "sales"]] 137 | df_all = pd.merge(df_all, df_tmp[["d"] + encoding_cols], on=["d"] + list(chain(*icols)), how="left") 138 | 139 | # Format Categorical Columns 140 | categoricals = [ 141 | "event_name_1", 142 | "event_type_1", 143 | "event_name_2", 144 | "event_type_2", 145 | ] 146 | 147 | df_all[categoricals] = df_all[categoricals].fillna("noevent") 148 | 149 | # create a copy of state_id for use as a categorical 150 | df_all["state_id_cat"] = df_all["state_id"] 151 | 152 | outfile = "m5_for_state_level_forecasting.csv.gz" 153 | df_all.to_csv(outfile, index=False) 154 | print(f"Successfully saved the prepared M5 data to {outfile}.") 155 | -------------------------------------------------------------------------------- /LICENSE-code: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /recipes/Time_Series/Getting_Started_with_WatsonX_AI_SDK.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": {}, 6 | "source": [ 7 | "# Getting Started with Time Series Models on IBM WatsonX" 8 | ] 9 | }, 10 | { 11 | "cell_type": "markdown", 12 | "metadata": {}, 13 | "source": [ 14 | "This notebook demonstrates using the WatsonX SDK to perform inference calls against a model hosted remotely on [WatsonX](https://www.ibm.com/products/watsonx-ai)." 15 | ] 16 | }, 17 | { 18 | "cell_type": "markdown", 19 | "metadata": {}, 20 | "source": [ 21 | "### Install dependencies\n", 22 | "\n", 23 | "> **NOTE**: When running this recipe in [Colab](https://colab.research.google.com/), you may see an error about dependency conflicts with `google-colab 1.0.0`. You can safely ignore this error." 24 | ] 25 | }, 26 | { 27 | "cell_type": "code", 28 | "execution_count": null, 29 | "metadata": {}, 30 | "outputs": [], 31 | "source": [ 32 | "!pip install git+https://github.com/ibm-granite-community/utils\n", 33 | "!pip install ibm-watsonx-ai\n", 34 | "!pip install matplotlib" 35 | ] 36 | }, 37 | { 38 | "cell_type": "code", 39 | "execution_count": null, 40 | "metadata": {}, 41 | "outputs": [], 42 | "source": [ 43 | "import pprint\n", 44 | "\n", 45 | "import matplotlib.pyplot as plt\n", 46 | "import pandas as pd\n", 47 | "from ibm_granite_community.notebook_utils import get_env_var\n", 48 | "from ibm_watsonx_ai import APIClient, Credentials\n", 49 | "from ibm_watsonx_ai.foundation_models import TSModelInference\n", 50 | "from ibm_watsonx_ai.foundation_models.schema import TSForecastParameters" 51 | ] 52 | }, 53 | { 54 | "cell_type": "markdown", 55 | "metadata": {}, 56 | "source": [ 57 | "### Provide the environment variables\n", 58 | "\n", 59 | "There are three ways to provide the environment variables required. In order of precedence:\n", 60 | "\n", 61 | "1. Directly as an environment variable in the python environment where the jupyter notebook is running.\n", 62 | "2. As a Google Colab secret, if you are running the notebook in Colab.\n", 63 | "3. Supplied by the user in a prompt during execution of the notebook.\n", 64 | "\n", 65 | "#### Provide your API Key\n", 66 | "\n", 67 | "Obtain your `WATSONX_APIKEY` by generating a [Platform API Key](https://www.ibm.com/docs/en/watsonx/watsonxdata/1.0.x?topic=started-generating-api-keys) on the watsonx.data web client.\n", 68 | "\n", 69 | "#### Provide your Project Id\n", 70 | "\n", 71 | "Get your `WATSONX_PROJECT_ID` from the [WatsonX](https://www.ibm.com/watsonx) web client by following [these instructions](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-project-id.html?context=wx).\n", 72 | "\n", 73 | "#### Provide your base WatsonX URL\n", 74 | "\n", 75 | "Get your `WATSONX_URL` by viewing the details for the service instance from the Cloud Pak for Data web client, as described in [these watsonx.ai setup instructions](https://ibm.github.io/watsonx-ai-python-sdk/setup_cpd.html).\n", 76 | "\n", 77 | "As an example, your `WATSONX_URL` may be `https://us-south.ml.cloud.ibm.com` for the Dallas zone." 78 | ] 79 | }, 80 | { 81 | "cell_type": "code", 82 | "execution_count": null, 83 | "metadata": {}, 84 | "outputs": [], 85 | "source": [ 86 | "credentials = Credentials(\n", 87 | " api_key=get_env_var(\"WATSONX_APIKEY\"),\n", 88 | " url=get_env_var(\"WATSONX_URL\"),\n", 89 | ")\n", 90 | "client = APIClient(credentials)\n", 91 | "client.set.default_project(get_env_var(\"WATSONX_PROJECT_ID\"))" 92 | ] 93 | }, 94 | { 95 | "cell_type": "code", 96 | "execution_count": null, 97 | "metadata": {}, 98 | "outputs": [], 99 | "source": [ 100 | "for model in client.foundation_models.get_time_series_model_specs()[\"resources\"]:\n", 101 | " pprint.pp(\"--------------------------------------------------\")\n", 102 | " pprint.pp(f'model_id: {model[\"model_id\"]}')\n", 103 | " pprint.pp(f'functions: {model[\"functions\"]}')\n", 104 | " pprint.pp(f'long_description: {model[\"long_description\"]}')\n", 105 | " pprint.pp(f'label: {model[\"label\"]}')" 106 | ] 107 | }, 108 | { 109 | "cell_type": "code", 110 | "execution_count": null, 111 | "metadata": {}, 112 | "outputs": [], 113 | "source": [ 114 | "ts_model_id = client.foundation_models.TimeSeriesModels.GRANITE_TTM_512_96_R2\n", 115 | "\n", 116 | "ts_model = TSModelInference(model_id=ts_model_id, api_client=client)\n", 117 | "context_length = 512\n", 118 | "prediction_length = 20" 119 | ] 120 | }, 121 | { 122 | "cell_type": "markdown", 123 | "metadata": {}, 124 | "source": [ 125 | "### Download the data\n", 126 | "\n", 127 | "We'll work with a [bike sharing dataset](https://archive.ics.uci.edu/dataset/275/bike+sharing+dataset) available from the UCI Machine learning repository. This dataset includes the count of rental bikes between the years 2011 and 2012 in the Capital bike share system with the corresponding weather and seasonal information.\n", 128 | "\n", 129 | "You can download the source code to a temporary directory by running the following commands. Later you can clean up any downloaded files by removing the `temp` folder." 130 | ] 131 | }, 132 | { 133 | "cell_type": "code", 134 | "execution_count": null, 135 | "metadata": {}, 136 | "outputs": [], 137 | "source": [ 138 | "%%bash\n", 139 | "# curl https://archive.ics.uci.edu/static/public/275/$BIKE_SHARING -o $BIKE_SHARING && \\\n", 140 | "BIKE_SHARING=bike+sharing+dataset.zip\n", 141 | "test -d temp || ( \\\n", 142 | " mkdir -p temp && \\\n", 143 | " cd temp && \\\n", 144 | " wget https://archive.ics.uci.edu/static/public/275/$BIKE_SHARING -O $BIKE_SHARING && \\\n", 145 | " unzip -o $BIKE_SHARING && \\\n", 146 | " rm -f $BIKE_SHARING && \\\n", 147 | " cd - \\\n", 148 | ") && ls -l temp/" 149 | ] 150 | }, 151 | { 152 | "cell_type": "code", 153 | "execution_count": null, 154 | "metadata": {}, 155 | "outputs": [], 156 | "source": [ 157 | "DATA_FILE_PATH = \"temp/hour.csv\"" 158 | ] 159 | }, 160 | { 161 | "cell_type": "markdown", 162 | "metadata": {}, 163 | "source": [ 164 | "### Read in the data\n", 165 | "\n", 166 | "We parse the CSV into a pandas dataframe, filling in any null values, and create a single window containing `context_length` time points. We ensure the timestamp column is a UTC datetime." 167 | ] 168 | }, 169 | { 170 | "cell_type": "code", 171 | "execution_count": null, 172 | "metadata": {}, 173 | "outputs": [], 174 | "source": [ 175 | "timestamp_column = \"dteday\"\n", 176 | "target_columns = [\"casual\", \"registered\"]\n", 177 | "\n", 178 | "# Read in the data from the downloaded file.\n", 179 | "input_df = pd.read_csv(DATA_FILE_PATH, parse_dates=[timestamp_column])\n", 180 | "\n", 181 | "# Fix missing hours in original dataset date column\n", 182 | "input_df[timestamp_column] = input_df[timestamp_column] + input_df.hr.apply(lambda x: pd.Timedelta(x, unit=\"hr\"))\n", 183 | "\n", 184 | "# Show the last few rows of the dataset.\n", 185 | "input_df[timestamp_column] = input_df[timestamp_column].apply(lambda x: x.isoformat())\n", 186 | "input_df.tail()" 187 | ] 188 | }, 189 | { 190 | "cell_type": "markdown", 191 | "metadata": {}, 192 | "source": [ 193 | "### Create the dataset for the request\n", 194 | "\n", 195 | "Rather than making a single request by passing one context length of the data to the watsonx.ai service, we select a few starting indices and provide a single payload to make multiple forecasts at once. We add an id column to distinguish these context windows.\n", 196 | "\n", 197 | "In the cell below, we construct the `input_data` DataFrame containing the context windows, while `ground_truth_data` contains the true values of the target columns." 198 | ] 199 | }, 200 | { 201 | "cell_type": "code", 202 | "execution_count": null, 203 | "metadata": {}, 204 | "outputs": [], 205 | "source": [ 206 | "start_index = [2173, 10635, 10935, 14239] # randomly chosen starting points\n", 207 | "id_column = \"id\"\n", 208 | "\n", 209 | "input_data = []\n", 210 | "ground_truth_data = []\n", 211 | "for i in start_index:\n", 212 | " df = input_df.iloc[i : i + context_length, :].copy()\n", 213 | " df[id_column] = f\"id_{i}\"\n", 214 | " input_data.append(df)\n", 215 | " df = input_df.iloc[i + context_length : i + context_length + prediction_length, :].copy()\n", 216 | " df[id_column] = f\"id_{i}\"\n", 217 | " ground_truth_data.append(df)\n", 218 | "\n", 219 | "input_data = pd.concat(input_data)\n", 220 | "ground_truth_data = pd.concat(ground_truth_data)" 221 | ] 222 | }, 223 | { 224 | "cell_type": "code", 225 | "execution_count": null, 226 | "metadata": {}, 227 | "outputs": [], 228 | "source": [ 229 | "input_data.head()" 230 | ] 231 | }, 232 | { 233 | "cell_type": "markdown", 234 | "metadata": {}, 235 | "source": [ 236 | "### Build the arguments for the forecast request\n", 237 | "\n", 238 | "We first construct the forecast parameters structure and then call the forecast method. The forecast parameters specify the id column, timestamp column, target columns, frequency, and prediction length." 239 | ] 240 | }, 241 | { 242 | "cell_type": "code", 243 | "execution_count": null, 244 | "metadata": {}, 245 | "outputs": [], 246 | "source": [ 247 | "forecasting_params = TSForecastParameters(\n", 248 | " id_columns=[id_column],\n", 249 | " timestamp_column=timestamp_column,\n", 250 | " freq=\"1h\",\n", 251 | " target_columns=target_columns,\n", 252 | " prediction_length=prediction_length,\n", 253 | ")" 254 | ] 255 | }, 256 | { 257 | "cell_type": "markdown", 258 | "metadata": {}, 259 | "source": [ 260 | "### Make the forecast request and plot results\n", 261 | "\n", 262 | "Here we use the forecast method to get the forecast for our data, then we plot the results." 263 | ] 264 | }, 265 | { 266 | "cell_type": "code", 267 | "execution_count": null, 268 | "metadata": {}, 269 | "outputs": [], 270 | "source": [ 271 | "results = ts_model.forecast(data=input_data, params=forecasting_params)\n", 272 | "df_out = pd.DataFrame(results[\"results\"][0], columns=[id_column, timestamp_column] + target_columns)\n", 273 | "df_out.head()" 274 | ] 275 | }, 276 | { 277 | "cell_type": "code", 278 | "execution_count": null, 279 | "metadata": {}, 280 | "outputs": [], 281 | "source": [ 282 | "# Set a more beautiful style\n", 283 | "plt.style.use(\"seaborn-v0_8-whitegrid\")\n", 284 | "\n", 285 | "# how much history to plot\n", 286 | "history = 60\n", 287 | "\n", 288 | "grps = input_data.groupby(id_column)\n", 289 | "\n", 290 | "num_plots = len(grps)\n", 291 | "fig, axs = plt.subplots(num_plots, 1, figsize=(10, 2 * num_plots))\n", 292 | "\n", 293 | "\n", 294 | "for i, (grp_name, grp) in enumerate(grps):\n", 295 | " # concatenate ground truth historical data with the ground truth for the future targets\n", 296 | " gt = ground_truth_data[ground_truth_data[id_column] == grp_name]\n", 297 | " gt_dt = pd.concat([grp[timestamp_column].iloc[-history:], gt[timestamp_column]])\n", 298 | " gt_val = pd.concat([grp[target_columns[0]].iloc[-history:], gt[target_columns[0]]])\n", 299 | "\n", 300 | " # plot ground truth\n", 301 | " axs[i].plot(pd.to_datetime(gt_dt), gt_val, label=\"Ground truth\", linestyle=\"-\", color=\"blue\", linewidth=2)\n", 302 | "\n", 303 | " # plot forecasts\n", 304 | " pred = df_out[df_out[id_column] == grp_name]\n", 305 | " axs[i].plot(\n", 306 | " pd.to_datetime(pred[timestamp_column]),\n", 307 | " pred[target_columns[0]],\n", 308 | " label=\"Prediction\",\n", 309 | " linestyle=\"--\",\n", 310 | " color=\"orange\",\n", 311 | " linewidth=2,\n", 312 | " )\n", 313 | "\n", 314 | " axs[i].legend()\n", 315 | " axs[i].set_title(grp_name)\n", 316 | "\n", 317 | "plt.tight_layout()" 318 | ] 319 | } 320 | ], 321 | "metadata": { 322 | "language_info": { 323 | "codemirror_mode": { 324 | "name": "ipython", 325 | "version": 3 326 | }, 327 | "file_extension": ".py", 328 | "mimetype": "text/x-python", 329 | "name": "python", 330 | "nbconvert_exporter": "python", 331 | "pygments_lexer": "ipython3" 332 | } 333 | }, 334 | "nbformat": 4, 335 | "nbformat_minor": 4 336 | } 337 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Attribution 4.0 International 2 | 3 | ======================================================================= 4 | 5 | Creative Commons Corporation ("Creative Commons") is not a law firm and 6 | does not provide legal services or legal advice. Distribution of 7 | Creative Commons public licenses does not create a lawyer-client or 8 | other relationship. Creative Commons makes its licenses and related 9 | information available on an "as-is" basis. Creative Commons gives no 10 | warranties regarding its licenses, any material licensed under their 11 | terms and conditions, or any related information. Creative Commons 12 | disclaims all liability for damages resulting from their use to the 13 | fullest extent possible. 14 | 15 | Using Creative Commons Public Licenses 16 | 17 | Creative Commons public licenses provide a standard set of terms and 18 | conditions that creators and other rights holders may use to share 19 | original works of authorship and other material subject to copyright 20 | and certain other rights specified in the public license below. The 21 | following considerations are for informational purposes only, are not 22 | exhaustive, and do not form part of our licenses. 23 | 24 | Considerations for licensors: Our public licenses are 25 | intended for use by those authorized to give the public 26 | permission to use material in ways otherwise restricted by 27 | copyright and certain other rights. Our licenses are 28 | irrevocable. Licensors should read and understand the terms 29 | and conditions of the license they choose before applying it. 30 | Licensors should also secure all rights necessary before 31 | applying our licenses so that the public can reuse the 32 | material as expected. Licensors should clearly mark any 33 | material not subject to the license. This includes other CC- 34 | licensed material, or material used under an exception or 35 | limitation to copyright. More considerations for licensors: 36 | wiki.creativecommons.org/Considerations_for_licensors 37 | 38 | Considerations for the public: By using one of our public 39 | licenses, a licensor grants the public permission to use the 40 | licensed material under specified terms and conditions. If 41 | the licensor's permission is not necessary for any reason--for 42 | example, because of any applicable exception or limitation to 43 | copyright--then that use is not regulated by the license. Our 44 | licenses grant only permissions under copyright and certain 45 | other rights that a licensor has authority to grant. Use of 46 | the licensed material may still be restricted for other 47 | reasons, including because others have copyright or other 48 | rights in the material. A licensor may make special requests, 49 | such as asking that all changes be marked or described. 50 | Although not required by our licenses, you are encouraged to 51 | respect those requests where reasonable. More considerations 52 | for the public: 53 | wiki.creativecommons.org/Considerations_for_licensees 54 | 55 | ======================================================================= 56 | 57 | Creative Commons Attribution 4.0 International Public License 58 | 59 | By exercising the Licensed Rights (defined below), You accept and agree 60 | to be bound by the terms and conditions of this Creative Commons 61 | Attribution 4.0 International Public License ("Public License"). To the 62 | extent this Public License may be interpreted as a contract, You are 63 | granted the Licensed Rights in consideration of Your acceptance of 64 | these terms and conditions, and the Licensor grants You such rights in 65 | consideration of benefits the Licensor receives from making the 66 | Licensed Material available under these terms and conditions. 67 | 68 | 69 | Section 1 -- Definitions. 70 | 71 | a. Adapted Material means material subject to Copyright and Similar 72 | Rights that is derived from or based upon the Licensed Material 73 | and in which the Licensed Material is translated, altered, 74 | arranged, transformed, or otherwise modified in a manner requiring 75 | permission under the Copyright and Similar Rights held by the 76 | Licensor. For purposes of this Public License, where the Licensed 77 | Material is a musical work, performance, or sound recording, 78 | Adapted Material is always produced where the Licensed Material is 79 | synched in timed relation with a moving image. 80 | 81 | b. Adapter's License means the license You apply to Your Copyright 82 | and Similar Rights in Your contributions to Adapted Material in 83 | accordance with the terms and conditions of this Public License. 84 | 85 | c. Copyright and Similar Rights means copyright and/or similar rights 86 | closely related to copyright including, without limitation, 87 | performance, broadcast, sound recording, and Sui Generis Database 88 | Rights, without regard to how the rights are labeled or 89 | categorized. For purposes of this Public License, the rights 90 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 91 | Rights. 92 | 93 | d. Effective Technological Measures means those measures that, in the 94 | absence of proper authority, may not be circumvented under laws 95 | fulfilling obligations under Article 11 of the WIPO Copyright 96 | Treaty adopted on December 20, 1996, and/or similar international 97 | agreements. 98 | 99 | e. Exceptions and Limitations means fair use, fair dealing, and/or 100 | any other exception or limitation to Copyright and Similar Rights 101 | that applies to Your use of the Licensed Material. 102 | 103 | f. Licensed Material means the artistic or literary work, database, 104 | or other material to which the Licensor applied this Public 105 | License. 106 | 107 | g. Licensed Rights means the rights granted to You subject to the 108 | terms and conditions of this Public License, which are limited to 109 | all Copyright and Similar Rights that apply to Your use of the 110 | Licensed Material and that the Licensor has authority to license. 111 | 112 | h. Licensor means the individual(s) or entity(ies) granting rights 113 | under this Public License. 114 | 115 | i. Share means to provide material to the public by any means or 116 | process that requires permission under the Licensed Rights, such 117 | as reproduction, public display, public performance, distribution, 118 | dissemination, communication, or importation, and to make material 119 | available to the public including in ways that members of the 120 | public may access the material from a place and at a time 121 | individually chosen by them. 122 | 123 | j. Sui Generis Database Rights means rights other than copyright 124 | resulting from Directive 96/9/EC of the European Parliament and of 125 | the Council of 11 March 1996 on the legal protection of databases, 126 | as amended and/or succeeded, as well as other essentially 127 | equivalent rights anywhere in the world. 128 | 129 | k. You means the individual or entity exercising the Licensed Rights 130 | under this Public License. Your has a corresponding meaning. 131 | 132 | 133 | Section 2 -- Scope. 134 | 135 | a. License grant. 136 | 137 | 1. Subject to the terms and conditions of this Public License, 138 | the Licensor hereby grants You a worldwide, royalty-free, 139 | non-sublicensable, non-exclusive, irrevocable license to 140 | exercise the Licensed Rights in the Licensed Material to: 141 | 142 | a. reproduce and Share the Licensed Material, in whole or 143 | in part; and 144 | 145 | b. produce, reproduce, and Share Adapted Material. 146 | 147 | 2. Exceptions and Limitations. For the avoidance of doubt, where 148 | Exceptions and Limitations apply to Your use, this Public 149 | License does not apply, and You do not need to comply with 150 | its terms and conditions. 151 | 152 | 3. Term. The term of this Public License is specified in Section 153 | 6(a). 154 | 155 | 4. Media and formats; technical modifications allowed. The 156 | Licensor authorizes You to exercise the Licensed Rights in 157 | all media and formats whether now known or hereafter created, 158 | and to make technical modifications necessary to do so. The 159 | Licensor waives and/or agrees not to assert any right or 160 | authority to forbid You from making technical modifications 161 | necessary to exercise the Licensed Rights, including 162 | technical modifications necessary to circumvent Effective 163 | Technological Measures. For purposes of this Public License, 164 | simply making modifications authorized by this Section 2(a) 165 | (4) never produces Adapted Material. 166 | 167 | 5. Downstream recipients. 168 | 169 | a. Offer from the Licensor -- Licensed Material. Every 170 | recipient of the Licensed Material automatically 171 | receives an offer from the Licensor to exercise the 172 | Licensed Rights under the terms and conditions of this 173 | Public License. 174 | 175 | b. No downstream restrictions. You may not offer or impose 176 | any additional or different terms or conditions on, or 177 | apply any Effective Technological Measures to, the 178 | Licensed Material if doing so restricts exercise of the 179 | Licensed Rights by any recipient of the Licensed 180 | Material. 181 | 182 | 6. No endorsement. Nothing in this Public License constitutes or 183 | may be construed as permission to assert or imply that You 184 | are, or that Your use of the Licensed Material is, connected 185 | with, or sponsored, endorsed, or granted official status by, 186 | the Licensor or others designated to receive attribution as 187 | provided in Section 3(a)(1)(A)(i). 188 | 189 | b. Other rights. 190 | 191 | 1. Moral rights, such as the right of integrity, are not 192 | licensed under this Public License, nor are publicity, 193 | privacy, and/or other similar personality rights; however, to 194 | the extent possible, the Licensor waives and/or agrees not to 195 | assert any such rights held by the Licensor to the limited 196 | extent necessary to allow You to exercise the Licensed 197 | Rights, but not otherwise. 198 | 199 | 2. Patent and trademark rights are not licensed under this 200 | Public License. 201 | 202 | 3. To the extent possible, the Licensor waives any right to 203 | collect royalties from You for the exercise of the Licensed 204 | Rights, whether directly or through a collecting society 205 | under any voluntary or waivable statutory or compulsory 206 | licensing scheme. In all other cases the Licensor expressly 207 | reserves any right to collect such royalties. 208 | 209 | 210 | Section 3 -- License Conditions. 211 | 212 | Your exercise of the Licensed Rights is expressly made subject to the 213 | following conditions. 214 | 215 | a. Attribution. 216 | 217 | 1. If You Share the Licensed Material (including in modified 218 | form), You must: 219 | 220 | a. retain the following if it is supplied by the Licensor 221 | with the Licensed Material: 222 | 223 | i. identification of the creator(s) of the Licensed 224 | Material and any others designated to receive 225 | attribution, in any reasonable manner requested by 226 | the Licensor (including by pseudonym if 227 | designated); 228 | 229 | ii. a copyright notice; 230 | 231 | iii. a notice that refers to this Public License; 232 | 233 | iv. a notice that refers to the disclaimer of 234 | warranties; 235 | 236 | v. a URI or hyperlink to the Licensed Material to the 237 | extent reasonably practicable; 238 | 239 | b. indicate if You modified the Licensed Material and 240 | retain an indication of any previous modifications; and 241 | 242 | c. indicate the Licensed Material is licensed under this 243 | Public License, and include the text of, or the URI or 244 | hyperlink to, this Public License. 245 | 246 | 2. You may satisfy the conditions in Section 3(a)(1) in any 247 | reasonable manner based on the medium, means, and context in 248 | which You Share the Licensed Material. For example, it may be 249 | reasonable to satisfy the conditions by providing a URI or 250 | hyperlink to a resource that includes the required 251 | information. 252 | 253 | 3. If requested by the Licensor, You must remove any of the 254 | information required by Section 3(a)(1)(A) to the extent 255 | reasonably practicable. 256 | 257 | 4. If You Share Adapted Material You produce, the Adapter's 258 | License You apply must not prevent recipients of the Adapted 259 | Material from complying with this Public License. 260 | 261 | 262 | Section 4 -- Sui Generis Database Rights. 263 | 264 | Where the Licensed Rights include Sui Generis Database Rights that 265 | apply to Your use of the Licensed Material: 266 | 267 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 268 | to extract, reuse, reproduce, and Share all or a substantial 269 | portion of the contents of the database; 270 | 271 | b. if You include all or a substantial portion of the database 272 | contents in a database in which You have Sui Generis Database 273 | Rights, then the database in which You have Sui Generis Database 274 | Rights (but not its individual contents) is Adapted Material; and 275 | 276 | c. You must comply with the conditions in Section 3(a) if You Share 277 | all or a substantial portion of the contents of the database. 278 | 279 | For the avoidance of doubt, this Section 4 supplements and does not 280 | replace Your obligations under this Public License where the Licensed 281 | Rights include other Copyright and Similar Rights. 282 | 283 | 284 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 285 | 286 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 287 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 288 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 289 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 290 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 291 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 292 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 293 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 294 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 295 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 296 | 297 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 298 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 299 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 300 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 301 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 302 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 303 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 304 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 305 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 306 | 307 | c. The disclaimer of warranties and limitation of liability provided 308 | above shall be interpreted in a manner that, to the extent 309 | possible, most closely approximates an absolute disclaimer and 310 | waiver of all liability. 311 | 312 | 313 | Section 6 -- Term and Termination. 314 | 315 | a. This Public License applies for the term of the Copyright and 316 | Similar Rights licensed here. However, if You fail to comply with 317 | this Public License, then Your rights under this Public License 318 | terminate automatically. 319 | 320 | b. Where Your right to use the Licensed Material has terminated under 321 | Section 6(a), it reinstates: 322 | 323 | 1. automatically as of the date the violation is cured, provided 324 | it is cured within 30 days of Your discovery of the 325 | violation; or 326 | 327 | 2. upon express reinstatement by the Licensor. 328 | 329 | For the avoidance of doubt, this Section 6(b) does not affect any 330 | right the Licensor may have to seek remedies for Your violations 331 | of this Public License. 332 | 333 | c. For the avoidance of doubt, the Licensor may also offer the 334 | Licensed Material under separate terms or conditions or stop 335 | distributing the Licensed Material at any time; however, doing so 336 | will not terminate this Public License. 337 | 338 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 339 | License. 340 | 341 | 342 | Section 7 -- Other Terms and Conditions. 343 | 344 | a. The Licensor shall not be bound by any additional or different 345 | terms or conditions communicated by You unless expressly agreed. 346 | 347 | b. Any arrangements, understandings, or agreements regarding the 348 | Licensed Material not stated herein are separate from and 349 | independent of the terms and conditions of this Public License. 350 | 351 | 352 | Section 8 -- Interpretation. 353 | 354 | a. For the avoidance of doubt, this Public License does not, and 355 | shall not be interpreted to, reduce, limit, restrict, or impose 356 | conditions on any use of the Licensed Material that could lawfully 357 | be made without permission under this Public License. 358 | 359 | b. To the extent possible, if any provision of this Public License is 360 | deemed unenforceable, it shall be automatically reformed to the 361 | minimum extent necessary to make it enforceable. If the provision 362 | cannot be reformed, it shall be severed from this Public License 363 | without affecting the enforceability of the remaining terms and 364 | conditions. 365 | 366 | c. No term or condition of this Public License will be waived and no 367 | failure to comply consented to unless expressly agreed to by the 368 | Licensor. 369 | 370 | d. Nothing in this Public License constitutes or may be interpreted 371 | as a limitation upon, or waiver of, any privileges and immunities 372 | that apply to the Licensor or You, including from the legal 373 | processes of any jurisdiction or authority. 374 | 375 | 376 | ======================================================================= 377 | 378 | Creative Commons is not a party to its public 379 | licenses. Notwithstanding, Creative Commons may elect to apply one of 380 | its public licenses to material it publishes and in those instances 381 | will be considered the “Licensor.” The text of the Creative Commons 382 | public licenses is dedicated to the public domain under the CC0 Public 383 | Domain Dedication. Except for the limited purpose of indicating that 384 | material is shared under a Creative Commons public license or as 385 | otherwise permitted by the Creative Commons policies published at 386 | creativecommons.org/policies, Creative Commons does not authorize the 387 | use of the trademark "Creative Commons" or any other trademark or logo 388 | of Creative Commons without its prior written consent including, 389 | without limitation, in connection with any unauthorized modifications 390 | to any of its public licenses or any other arrangements, 391 | understandings, or agreements concerning use of licensed material. For 392 | the avoidance of doubt, this paragraph does not form part of the 393 | public licenses. 394 | 395 | Creative Commons may be contacted at creativecommons.org. 396 | -------------------------------------------------------------------------------- /recipes/Retail_Forecasting/M5_retail_sales_forecasting.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "id": "5b8d62ab", 6 | "metadata": {}, 7 | "source": [ 8 | "# Retail Sales Forecasting using the M5 dataset with Granite Time Series - Few-shot finetuning, evaluation, and visualization\n", 9 | "\n", 10 | "In this tutorial, we will explore [timeseries forecasting](https://www.ibm.com/think/insights/time-series-forecasting) using the [IBM Granite Timeseries model](https://ibm.com/granite) to predict retail sales. We will cover key techniques such as few-shot forecasting and fine-tuning. We are using [M5 datasets](https://drive.google.com/drive/folders/1D6EWdVSaOtrP1LEFh1REjI3vej6iUS_4?usp=sharing) from the official M-Competitions [repository](https://github.com/Mcompetitions/M5-methods) to forecast future sales aggregated by state. The aim of this recipe is to showcase how to use a pre-trained time series foundation model for multivariate forecasting and explores various features available with Granite Time Series Foundation Models.\n", 11 | "\n", 12 | "This recipe uses TinyTimeMixers (TTMs), which are compact pre-trained models for Multivariate Time-Series Forecasting, open-sourced by IBM Research. With less than 1 Million parameters, TTM introduces the notion of the first-ever \"tiny\" pre-trained models for Time-Series Forecasting. TTM outperforms several popular benchmarks demanding billions of parameters in zero-shot and few-shot forecasting and can easily be fine-tuned for multivariate forecasts.\n", 13 | "\n", 14 | "## Setting Up\n", 15 | "\n", 16 | "### Install the TSFM Library\n", 17 | "\n", 18 | "The [granite-tsfm library](https://github.com/ibm-granite/granite-tsfm) provides utilities for working with Time Series Foundation Models (TSFM). Here we retrieve and install the latest version of the library." 19 | ] 20 | }, 21 | { 22 | "cell_type": "code", 23 | "execution_count": null, 24 | "id": "8772bb9e", 25 | "metadata": { 26 | "scrolled": true 27 | }, 28 | "outputs": [], 29 | "source": [ 30 | "# Install the tsfm library\n", 31 | "! pip install \"granite-tsfm[notebooks] @ git+https://github.com/ibm-granite/granite-tsfm.git@v0.2.22\"\n", 32 | "# Install a utility to help download data files from google drive during the data prep process\n", 33 | "! pip install gdown" 34 | ] 35 | }, 36 | { 37 | "cell_type": "markdown", 38 | "id": "1b5b62e9", 39 | "metadata": {}, 40 | "source": [ 41 | "### Import Packages\n", 42 | "\n", 43 | "From `tsfm_public`, we use the TinyTimeMixer model, forecasting pipeline, and plotting function. We also leverage a few components for the fine-tuning process." 44 | ] 45 | }, 46 | { 47 | "cell_type": "code", 48 | "execution_count": null, 49 | "id": "ff5230e2-b163-4d1a-a715-239b9190cce3", 50 | "metadata": {}, 51 | "outputs": [], 52 | "source": [ 53 | "import math\n", 54 | "import os\n", 55 | "\n", 56 | "import numpy as np\n", 57 | "import pandas as pd\n", 58 | "import torch\n", 59 | "from torch.optim import AdamW\n", 60 | "from torch.optim.lr_scheduler import OneCycleLR\n", 61 | "from torch.utils.data import Subset\n", 62 | "from transformers import EarlyStoppingCallback, Trainer, TrainingArguments, set_seed\n", 63 | "\n", 64 | "from tsfm_public import (\n", 65 | " ForecastDFDataset,\n", 66 | " TimeSeriesForecastingPipeline,\n", 67 | " TimeSeriesPreprocessor,\n", 68 | " TinyTimeMixerForPrediction,\n", 69 | " TrackingCallback,\n", 70 | " count_parameters,\n", 71 | ")\n", 72 | "from tsfm_public.toolkit.lr_finder import optimal_lr_finder\n", 73 | "from tsfm_public.toolkit.time_series_preprocessor import prepare_data_splits\n", 74 | "from tsfm_public.toolkit.util import select_by_timestamp\n", 75 | "from tsfm_public.toolkit.visualization import plot_predictions" 76 | ] 77 | }, 78 | { 79 | "cell_type": "markdown", 80 | "id": "47dcdc5f", 81 | "metadata": {}, 82 | "source": [ 83 | "### Specify configuration variables\n", 84 | "\n", 85 | "The forecast length is specified as well as the context length (in time steps) which is set to match the pretrained model. Additionally, we declare the Granite Time Series Model and the specific revision we are targeting.\n", 86 | "\n", 87 | "The granite-timeseries TTM R2 card has several different revisions of the model available for various context lengths and prediction lengths. In this example we will be working with daily data, so we choose a model suitable for that resolution -- 90 days of history to forecast the next 30 days." 88 | ] 89 | }, 90 | { 91 | "cell_type": "code", 92 | "execution_count": null, 93 | "id": "d39d6461", 94 | "metadata": {}, 95 | "outputs": [], 96 | "source": [ 97 | "forecast_length = 28\n", 98 | "context_length = 90\n", 99 | "\n", 100 | "TTM_MODEL_PATH = \"ibm-granite/granite-timeseries-ttm-r2\"\n", 101 | "REVISION = \"90-30-ft-l1-r2.1\"\n", 102 | "\n", 103 | "device = \"cuda\" if torch.cuda.is_available() else \"cpu\"" 104 | ] 105 | }, 106 | { 107 | "cell_type": "markdown", 108 | "id": "ccfd3add-8948-453e-bd1c-13977979ecee", 109 | "metadata": {}, 110 | "source": [ 111 | "## Preparing the Data\n", 112 | "\n", 113 | "As mentioned in the introduction, this notebook makes use of the [M5 datasets](https://drive.google.com/drive/folders/1D6EWdVSaOtrP1LEFh1REjI3vej6iUS_4?usp=sharing) from the official M-Competitions [repository](https://github.com/Mcompetitions/M5-methods). \n", 114 | "\n", 115 | "\n", 116 | "The original data includes hierarchy and product information. For this example we aggregate the sales by state into three separate time series. The code for downloading the datasets and preparing them is available in `M5_retail_data_prep.py`. Here, we first make sure we have access to the `M5_retail_data_prep.py` file (in an environment like colab, we need to download the file) and then we simply run the `prepare_data()` function to save the prepared dataset.\n" 117 | ] 118 | }, 119 | { 120 | "cell_type": "code", 121 | "execution_count": null, 122 | "id": "2bff4ef6", 123 | "metadata": {}, 124 | "outputs": [], 125 | "source": [ 126 | "import requests\n", 127 | "\n", 128 | "\n", 129 | "def download_file(file_url, destination):\n", 130 | " if os.path.exists(destination):\n", 131 | " return\n", 132 | " response = requests.get(file_url)\n", 133 | " if response.status_code == 200:\n", 134 | " with open(destination, \"wb\") as file:\n", 135 | " file.write(response.content)\n", 136 | " # logger.info(f\"Downloaded: {destination}\")\n", 137 | " else:\n", 138 | " print(f\"Failed to download {file_url}. Status code: {response.status_code}\")\n", 139 | "\n", 140 | "\n", 141 | "download_file(\n", 142 | " file_url=\"https://raw.githubusercontent.com/ibm-granite-community/granite-timeseries-cookbook/refs/heads/main/recipes/Retail_Forecasting/M5_retail_data_prep.py\",\n", 143 | " destination=\"./M5_retail_data_prep.py\",\n", 144 | ")" 145 | ] 146 | }, 147 | { 148 | "cell_type": "code", 149 | "execution_count": null, 150 | "id": "37127509", 151 | "metadata": {}, 152 | "outputs": [], 153 | "source": [ 154 | "# From the file we just made sure we had access to, import the data prep method\n", 155 | "from M5_retail_data_prep import prepare_data\n", 156 | "\n", 157 | "prepare_data()" 158 | ] 159 | }, 160 | { 161 | "cell_type": "markdown", 162 | "id": "cce78a17", 163 | "metadata": {}, 164 | "source": [ 165 | "### Read in the data\n", 166 | "\n", 167 | "We parse the CSV into a pandas dataframe and ensure the timestamp column is a UTC datetime and drop two unnecessary columns." 168 | ] 169 | }, 170 | { 171 | "cell_type": "code", 172 | "execution_count": null, 173 | "id": "aa99c39c-04d4-4df6-8bfe-500d4c973b6a", 174 | "metadata": {}, 175 | "outputs": [], 176 | "source": [ 177 | "data_path = \"m5_for_state_level_forecasting.csv.gz\"\n", 178 | "\n", 179 | "data = pd.read_csv(data_path, parse_dates=[\"date\"]).drop(columns=[\"d\", \"weekday\"])\n", 180 | "data.head()" 181 | ] 182 | }, 183 | { 184 | "cell_type": "markdown", 185 | "id": "386c127c", 186 | "metadata": {}, 187 | "source": [ 188 | "Next, we must clean up the columns in our data and declare the names of the timestamp column, the target column to be predicted as well as the categorical column used to aggregate the data." 189 | ] 190 | }, 191 | { 192 | "cell_type": "code", 193 | "execution_count": null, 194 | "id": "075d0d68-bd82-47d1-afab-fd4e7a3ffe94", 195 | "metadata": {}, 196 | "outputs": [], 197 | "source": [ 198 | "cols = list(data.columns)\n", 199 | "[cols.remove(c) for c in [\"date\", \"sales\", \"state_id\", \"state_id_cat\"]]\n", 200 | "cols\n", 201 | "\n", 202 | "column_specifiers = {\n", 203 | " \"timestamp_column\": \"date\",\n", 204 | " \"id_columns\": [\"state_id\"],\n", 205 | " \"target_columns\": [\"sales\"],\n", 206 | " \"control_columns\": cols,\n", 207 | " \"static_categorical_columns\": [\"state_id_cat\"],\n", 208 | " \"categorical_columns\": [\n", 209 | " \"event_name_1\",\n", 210 | " \"event_type_1\",\n", 211 | " \"event_name_2\",\n", 212 | " \"event_type_2\",\n", 213 | " ],\n", 214 | "}" 215 | ] 216 | }, 217 | { 218 | "cell_type": "markdown", 219 | "id": "4011a6cc", 220 | "metadata": {}, 221 | "source": [ 222 | "### Train the Preprocessor\n", 223 | "\n", 224 | "The preprocessor is trained on the training portion of the input data to learn the scaling factors. The scaling will be applied when we use the preprocess method of the time series preprocessor." 225 | ] 226 | }, 227 | { 228 | "cell_type": "code", 229 | "execution_count": null, 230 | "id": "3aa71ff5-f6ba-4c51-8f4f-9a12438845fd", 231 | "metadata": {}, 232 | "outputs": [], 233 | "source": [ 234 | "tsp = TimeSeriesPreprocessor(\n", 235 | " **column_specifiers,\n", 236 | " context_length=context_length,\n", 237 | " prediction_length=forecast_length,\n", 238 | " scaling=True,\n", 239 | " encode_categorical=True,\n", 240 | " scaler_type=\"standard\",\n", 241 | ")\n", 242 | "\n", 243 | "df_train = select_by_timestamp(\n", 244 | " data, timestamp_column=column_specifiers[\"timestamp_column\"], end_timestamp=\"2016-05-23\"\n", 245 | ")\n", 246 | "\n", 247 | "trained_tsp = tsp.train(df_train)" 248 | ] 249 | }, 250 | { 251 | "cell_type": "markdown", 252 | "id": "543737f6", 253 | "metadata": {}, 254 | "source": [ 255 | "## Finetune the model\n", 256 | "\n", 257 | "Now we will focus on fine-tuning the pretrained model. We use the same data splits we defined above, but now include extra columns during the fine-tuning process.\n", 258 | "\n", 259 | "### Preparing the data for fine-tuning\n", 260 | "\n", 261 | "We split the data into training, validation, and test sets. The training set is used to train the model, while the test set is used to evaluate its performance." 262 | ] 263 | }, 264 | { 265 | "cell_type": "code", 266 | "execution_count": null, 267 | "id": "5340414e", 268 | "metadata": {}, 269 | "outputs": [], 270 | "source": [ 271 | "split_params = {\"train\": 0.5, \"test\": 0.25}\n", 272 | "\n", 273 | "train_data, valid_data, test_data = prepare_data_splits(\n", 274 | " data, id_columns=column_specifiers[\"id_columns\"], split_config=split_params, context_length=context_length\n", 275 | ")" 276 | ] 277 | }, 278 | { 279 | "cell_type": "markdown", 280 | "id": "0e6279d1", 281 | "metadata": {}, 282 | "source": [ 283 | "Here we will construct the torch dataset because we cant pass panda dataframes using our torch dataset class specifically designed for forecasting usecases. " 284 | ] 285 | }, 286 | { 287 | "cell_type": "code", 288 | "execution_count": null, 289 | "id": "665fa12a", 290 | "metadata": {}, 291 | "outputs": [], 292 | "source": [ 293 | "frequency_token = tsp.get_frequency_token(tsp.freq)\n", 294 | "\n", 295 | "dataset_params = column_specifiers.copy()\n", 296 | "dataset_params[\"frequency_token\"] = frequency_token\n", 297 | "dataset_params[\"context_length\"] = context_length\n", 298 | "dataset_params[\"prediction_length\"] = forecast_length\n", 299 | "\n", 300 | "\n", 301 | "train_dataset = ForecastDFDataset(tsp.preprocess(train_data), **dataset_params)\n", 302 | "valid_dataset = ForecastDFDataset(tsp.preprocess(valid_data), **dataset_params)\n", 303 | "test_dataset = ForecastDFDataset(tsp.preprocess(test_data), **dataset_params)" 304 | ] 305 | }, 306 | { 307 | "cell_type": "markdown", 308 | "id": "9d0f9cce", 309 | "metadata": {}, 310 | "source": [ 311 | "Now let's take a smaller sample from the torch datasets produced above." 312 | ] 313 | }, 314 | { 315 | "cell_type": "code", 316 | "execution_count": null, 317 | "id": "4500fc58", 318 | "metadata": {}, 319 | "outputs": [], 320 | "source": [ 321 | "# 20% training and validation data (few-shot finetuning)\n", 322 | "fewshot_fraction = 0.20\n", 323 | "n_train_all = len(train_dataset)\n", 324 | "train_index = np.random.permutation(n_train_all)[: int(fewshot_fraction * n_train_all)]\n", 325 | "train_dataset = Subset(train_dataset, train_index)\n", 326 | "\n", 327 | "n_valid_all = len(valid_dataset)\n", 328 | "valid_index = np.random.permutation(n_valid_all)[: int(fewshot_fraction * n_valid_all)]\n", 329 | "valid_dataset = Subset(valid_dataset, valid_index)\n", 330 | "\n", 331 | "n_train_all, len(train_dataset), n_valid_all, len(valid_dataset)" 332 | ] 333 | }, 334 | { 335 | "cell_type": "markdown", 336 | "id": "22337b16-1e82-494a-bce8-8c49b9758cb2", 337 | "metadata": {}, 338 | "source": [ 339 | "### Load the model for fine-tuning\n", 340 | "\n", 341 | "We must first load the TTM model available on HuggingFace using the model and revision set above. We have one target channel, several exogenous channels, and one static categorical input. To take these into account, we use the `TimeSeriesPreprocessor` to provide the `prediction_channel_indices`, `exogenous_channel_indices`, and `categorical_vocab_size_list` information to the model. Note that we also enable channel mixing in the decoder and forecast channel mising. This allows the decoder to be tuned to capture interactions between the channels as well as adjust the forecasts based on interactions with the exogenous." 342 | ] 343 | }, 344 | { 345 | "cell_type": "code", 346 | "execution_count": null, 347 | "id": "12c77656-42d4-4b51-a6c3-a4245a794cd7", 348 | "metadata": {}, 349 | "outputs": [], 350 | "source": [ 351 | "set_seed(1234)\n", 352 | "\n", 353 | "finetune_forecast_model = TinyTimeMixerForPrediction.from_pretrained(\n", 354 | " TTM_MODEL_PATH,\n", 355 | " revision=REVISION,\n", 356 | " context_length=context_length,\n", 357 | " prediction_filter_length=forecast_length,\n", 358 | " num_input_channels=tsp.num_input_channels,\n", 359 | " decoder_mode=\"mix_channel\", # exog: set to mix_channel for mixing channels in history\n", 360 | " prediction_channel_indices=tsp.prediction_channel_indices,\n", 361 | " exogenous_channel_indices=tsp.exogenous_channel_indices,\n", 362 | " fcm_context_length=1, # exog: indicates lag length to use in the exog fusion. for Ex. if today sales can get affected by discount on +/- 2 days, mention 2\n", 363 | " fcm_use_mixer=True, # exog: Try true (1st option) or false\n", 364 | " fcm_mix_layers=2, # exog: Number of layers for exog mixing\n", 365 | " enable_forecast_channel_mixing=True, # exog: set true for exog mixing\n", 366 | " categorical_vocab_size_list=tsp.categorical_vocab_size_list, # sizes of the static categorical variables\n", 367 | " fcm_prepend_past=True, # exog: set true to include lag from history during exog infusion.\n", 368 | ")" 369 | ] 370 | }, 371 | { 372 | "cell_type": "markdown", 373 | "id": "10bf182c", 374 | "metadata": {}, 375 | "source": [ 376 | "### Optional: Freeze the TTM Backbone\n", 377 | "\n", 378 | "Oftentimes, during fine-tuning we freeze the backbone and focus on tuning only the parameters in the decoder. This reduces the overall number of parameters being tuned and maintains what the encoder learned during pretraining.\n", 379 | "\n", 380 | "For this dataset, however, we found that performance was better when the backbone remained unfrozen -- for other datasets one might prefer to freeze the backbone. We have disabled the backbone freezing code, but left it intact as an example of what might need to be done for other datasets." 381 | ] 382 | }, 383 | { 384 | "cell_type": "code", 385 | "execution_count": null, 386 | "id": "d168ae35", 387 | "metadata": {}, 388 | "outputs": [], 389 | "source": [ 390 | "freeze_backbone = False\n", 391 | "if freeze_backbone:\n", 392 | " print(\n", 393 | " \"Number of params before freezing backbone\",\n", 394 | " count_parameters(finetune_forecast_model),\n", 395 | " )\n", 396 | "\n", 397 | " # Freeze the backbone of the model\n", 398 | " for param in finetune_forecast_model.backbone.parameters():\n", 399 | " param.requires_grad = False\n", 400 | "\n", 401 | " # Count params\n", 402 | " print(\n", 403 | " \"Number of params after freezing the backbone\",\n", 404 | " count_parameters(finetune_forecast_model),\n", 405 | " )" 406 | ] 407 | }, 408 | { 409 | "cell_type": "markdown", 410 | "id": "e12d1996", 411 | "metadata": {}, 412 | "source": [ 413 | "### Set up a Trainer for Fine-tuning\n", 414 | "\n", 415 | "Configure a Trainer for use in fine-tuning and evaluating the model." 416 | ] 417 | }, 418 | { 419 | "cell_type": "code", 420 | "execution_count": null, 421 | "id": "2e625c63-0dff-4c13-85af-22e7848b5ec3", 422 | "metadata": {}, 423 | "outputs": [], 424 | "source": [ 425 | "num_epochs = 50\n", 426 | "batch_size = 64\n", 427 | "\n", 428 | "learning_rate, finetune_forecast_model = optimal_lr_finder(\n", 429 | " finetune_forecast_model,\n", 430 | " train_dataset,\n", 431 | " batch_size=batch_size,\n", 432 | " enable_prefix_tuning=True,\n", 433 | ")\n", 434 | "print(\"OPTIMAL SUGGESTED LEARNING RATE =\", learning_rate)" 435 | ] 436 | }, 437 | { 438 | "cell_type": "markdown", 439 | "id": "a2c4049d", 440 | "metadata": {}, 441 | "source": [ 442 | "### Train the Model\n", 443 | "\n", 444 | "Here we train the model on the training data." 445 | ] 446 | }, 447 | { 448 | "cell_type": "code", 449 | "execution_count": null, 450 | "id": "39944f77-4bb7-4066-b5a7-6f3a76cb1f6c", 451 | "metadata": {}, 452 | "outputs": [], 453 | "source": [ 454 | "OUT_DIR = \"ttm_finetuned_models/\"\n", 455 | "\n", 456 | "print(f\"Using learning rate = {learning_rate}\")\n", 457 | "finetune_forecast_args = TrainingArguments(\n", 458 | " output_dir=os.path.join(OUT_DIR, \"output\"),\n", 459 | " overwrite_output_dir=True,\n", 460 | " learning_rate=learning_rate,\n", 461 | " num_train_epochs=num_epochs,\n", 462 | " do_eval=True,\n", 463 | " eval_strategy=\"epoch\",\n", 464 | " per_device_train_batch_size=batch_size,\n", 465 | " per_device_eval_batch_size=2 * batch_size,\n", 466 | " dataloader_num_workers=1,\n", 467 | " report_to=\"none\",\n", 468 | " save_strategy=\"epoch\",\n", 469 | " logging_strategy=\"epoch\",\n", 470 | " save_total_limit=1,\n", 471 | " logging_dir=os.path.join(OUT_DIR, \"logs\"), # Make sure to specify a logging directory\n", 472 | " load_best_model_at_end=True, # Load the best model when training ends\n", 473 | " metric_for_best_model=\"eval_loss\", # Metric to monitor for early stopping\n", 474 | " greater_is_better=False, # For loss\n", 475 | " use_cpu=device == \"cpu\",\n", 476 | ")\n", 477 | "\n", 478 | "# Create the early stopping callback\n", 479 | "early_stopping_callback = EarlyStoppingCallback(\n", 480 | " early_stopping_patience=10, # Number of epochs with no improvement after which to stop\n", 481 | " early_stopping_threshold=0.0, # Minimum improvement required to consider as improvement\n", 482 | ")\n", 483 | "tracking_callback = TrackingCallback()\n", 484 | "\n", 485 | "# Optimizer and scheduler\n", 486 | "optimizer = AdamW(finetune_forecast_model.parameters(), lr=learning_rate)\n", 487 | "scheduler = OneCycleLR(\n", 488 | " optimizer,\n", 489 | " learning_rate,\n", 490 | " epochs=num_epochs,\n", 491 | " steps_per_epoch=math.ceil(len(train_dataset) / (batch_size)),\n", 492 | ")\n", 493 | "\n", 494 | "finetune_forecast_trainer = Trainer(\n", 495 | " model=finetune_forecast_model,\n", 496 | " args=finetune_forecast_args,\n", 497 | " train_dataset=train_dataset,\n", 498 | " eval_dataset=valid_dataset,\n", 499 | " callbacks=[early_stopping_callback, tracking_callback],\n", 500 | " optimizers=(optimizer, scheduler),\n", 501 | ")\n", 502 | "\n", 503 | "# Fine tune\n", 504 | "finetune_forecast_trainer.train()\n", 505 | "\n", 506 | "finetune_forecast_trainer.evaluate(test_dataset)" 507 | ] 508 | }, 509 | { 510 | "cell_type": "markdown", 511 | "id": "2460da14", 512 | "metadata": {}, 513 | "source": [ 514 | "### Evaluate the Model\n", 515 | "\n", 516 | "Evaluate the fine-tuned model on the test dataset." 517 | ] 518 | }, 519 | { 520 | "cell_type": "code", 521 | "execution_count": null, 522 | "id": "bdc24936", 523 | "metadata": {}, 524 | "outputs": [], 525 | "source": [ 526 | "# Define some standard metrics.\n", 527 | "def custom_metric(actual, prediction, column_header=\"results\"):\n", 528 | " \"\"\"Simple function to compute MSE\"\"\"\n", 529 | " a = np.asarray(actual.tolist())\n", 530 | " p = np.asarray(prediction.tolist())\n", 531 | " if p.shape[1] < a.shape[1]:\n", 532 | " a = a[:, : p.shape[1]]\n", 533 | "\n", 534 | " mask = ~np.any(np.isnan(a), axis=1)\n", 535 | "\n", 536 | " mse = np.mean(np.square(a[mask, :] - p[mask, :]))\n", 537 | " mae = np.mean(np.abs(a[mask, :] - p[mask, :]))\n", 538 | " return pd.DataFrame(\n", 539 | " {\n", 540 | " column_header: {\n", 541 | " \"mean_squared_error\": mse,\n", 542 | " \"root_mean_squared_error\": np.sqrt(mse),\n", 543 | " \"mean_absolute_error\": mae,\n", 544 | " }\n", 545 | " }\n", 546 | " )" 547 | ] 548 | }, 549 | { 550 | "cell_type": "code", 551 | "execution_count": null, 552 | "id": "94067d76", 553 | "metadata": {}, 554 | "outputs": [], 555 | "source": [ 556 | "# generate forecasts using the finetuned model\n", 557 | "pipeline = TimeSeriesForecastingPipeline(\n", 558 | " finetune_forecast_model,\n", 559 | " device=device, # Specify your local GPU or CPU.\n", 560 | " feature_extractor=tsp,\n", 561 | " batch_size=batch_size,\n", 562 | ")\n", 563 | "\n", 564 | "# Make a forecast on the target column given the input data.\n", 565 | "finetune_forecast = pipeline(test_data)\n", 566 | "finetune_forecast.head()" 567 | ] 568 | }, 569 | { 570 | "cell_type": "code", 571 | "execution_count": null, 572 | "id": "d26d4982", 573 | "metadata": {}, 574 | "outputs": [], 575 | "source": [ 576 | "custom_metric(finetune_forecast[\"sales\"], finetune_forecast[\"sales_prediction\"], \"fine-tune forecast\")" 577 | ] 578 | }, 579 | { 580 | "cell_type": "markdown", 581 | "id": "47c74b17", 582 | "metadata": {}, 583 | "source": [ 584 | "### Plot the Predictions vs. Actuals\n", 585 | "\n", 586 | "Plot the predictions vs. actuals for some random samples of time intervals in test dataset." 587 | ] 588 | }, 589 | { 590 | "cell_type": "code", 591 | "execution_count": null, 592 | "id": "bb4d1bf6", 593 | "metadata": {}, 594 | "outputs": [], 595 | "source": [ 596 | "plot_predictions(\n", 597 | " input_df=test_data[test_data.state_id == \"CA\"],\n", 598 | " predictions_df=finetune_forecast[finetune_forecast.state_id == \"CA\"],\n", 599 | " freq=\"d\",\n", 600 | " timestamp_column=column_specifiers[\"timestamp_column\"],\n", 601 | " channel=column_specifiers[\"target_columns\"][0],\n", 602 | ")" 603 | ] 604 | } 605 | ], 606 | "metadata": { 607 | "kernelspec": { 608 | "display_name": ".venv (3.11.11)", 609 | "language": "python", 610 | "name": "python3" 611 | }, 612 | "language_info": { 613 | "codemirror_mode": { 614 | "name": "ipython", 615 | "version": 3 616 | }, 617 | "file_extension": ".py", 618 | "mimetype": "text/x-python", 619 | "name": "python", 620 | "nbconvert_exporter": "python", 621 | "pygments_lexer": "ipython3", 622 | "version": "3.11.11" 623 | } 624 | }, 625 | "nbformat": 4, 626 | "nbformat_minor": 5 627 | } 628 | -------------------------------------------------------------------------------- /recipes/Classification/Getting_Started_with_TSPulse_Classification.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "id": "0", 6 | "metadata": {}, 7 | "source": [ 8 | "# BasicMotions Classification with Granite Time Series TSPulse\n", 9 | "\n", 10 | "TSPulse are compact pre-trained models specialized for various multivariate time-series analysis tasks namely classification, anomaly-detection, imputation and similarity search, open-sourced by IBM Research. With 1 Million parameters, TSPulse introduces the notion of the first-ever \"tiny\" pre-trained models for Time-Series tasks like classification, anomaly-detection, imputation and similarity search. TSPulse outperforms several popular benchmarks demanding billions of parameters in zero-shot and few-shot setting and can easily be fine-tuned for different downstream tasks.\n", 11 | "\n", 12 | "In this recipe, we demonstrates the usage of a pre-trained TSPulse model for time-series classification task. This example makes use of the [BasicMotions](https://www.timeseriesclassification.com/description.php?Dataset=BasicMotions) dataset from the [UEA](https://arxiv.org/abs/1811.00075) multivariate time-series classification archive.\n", 13 | "\n", 14 | "The data was generated as part of a student project where four students performed four activities whilst wearing a smart watch. The watch collects 3D accelerometer and a 3D gyroscope. The data order is accelerometer x, y, z then gyroscope x, y, z. There are four different classes: walking, resting, running and badminton.\n" 15 | ] 16 | }, 17 | { 18 | "cell_type": "markdown", 19 | "id": "1", 20 | "metadata": {}, 21 | "source": [ 22 | "## Install the TSFM Library\n", 23 | "\n", 24 | "The [granite-tsfm library](https://github.com/ibm-granite/granite-tsfm) provides utilities for working with Time Series Foundation Models (TSFM). Here the pinned version is retrieved and installed.\n" 25 | ] 26 | }, 27 | { 28 | "cell_type": "code", 29 | "execution_count": null, 30 | "id": "2", 31 | "metadata": {}, 32 | "outputs": [], 33 | "source": [ 34 | "# Install the tsfm library\n", 35 | "! pip install \"granite-tsfm[notebooks]==0.3.1\"" 36 | ] 37 | }, 38 | { 39 | "cell_type": "markdown", 40 | "id": "3", 41 | "metadata": {}, 42 | "source": [ 43 | "## Imports" 44 | ] 45 | }, 46 | { 47 | "cell_type": "code", 48 | "execution_count": null, 49 | "id": "4", 50 | "metadata": {}, 51 | "outputs": [], 52 | "source": [ 53 | "import math\n", 54 | "import os\n", 55 | "import tempfile\n", 56 | "import requests\n", 57 | "import zipfile\n", 58 | "import io\n", 59 | "import numpy as np\n", 60 | "import torch\n", 61 | "from torch.optim import AdamW\n", 62 | "from torch.optim.lr_scheduler import OneCycleLR\n", 63 | "from torch.utils.data import DataLoader, random_split\n", 64 | "from transformers import EarlyStoppingCallback, Trainer, TrainingArguments, set_seed\n", 65 | "from transformers.data.data_collator import default_data_collator\n", 66 | "from transformers.trainer_utils import RemoveColumnsCollator" 67 | ] 68 | }, 69 | { 70 | "cell_type": "markdown", 71 | "id": "5", 72 | "metadata": {}, 73 | "source": [ 74 | "### Imports from `tsfm_public`" 75 | ] 76 | }, 77 | { 78 | "cell_type": "code", 79 | "execution_count": null, 80 | "id": "6", 81 | "metadata": {}, 82 | "outputs": [], 83 | "source": [ 84 | "from tsfm_public.models.tspulse import TSPulseForClassification\n", 85 | "from tsfm_public.toolkit.dataset import ClassificationDFDataset\n", 86 | "from tsfm_public.toolkit.lr_finder import optimal_lr_finder\n", 87 | "from tsfm_public.toolkit.time_series_classification_preprocessor import TimeSeriesClassificationPreprocessor\n", 88 | "from tsfm_public.toolkit.util import convert_tsfile_to_dataframe" 89 | ] 90 | }, 91 | { 92 | "cell_type": "code", 93 | "execution_count": null, 94 | "id": "7", 95 | "metadata": {}, 96 | "outputs": [], 97 | "source": [ 98 | "# set the seed\n", 99 | "seed = 42\n", 100 | "set_seed(seed)" 101 | ] 102 | }, 103 | { 104 | "cell_type": "markdown", 105 | "id": "8", 106 | "metadata": {}, 107 | "source": [ 108 | "## Data Preprocessing\n", 109 | "\n", 110 | "We will download the BasicMotions dataset and extract the train and test `.ts files`." 111 | ] 112 | }, 113 | { 114 | "cell_type": "code", 115 | "execution_count": null, 116 | "id": "9", 117 | "metadata": {}, 118 | "outputs": [], 119 | "source": [ 120 | "url = \"https://www.timeseriesclassification.com/aeon-toolkit/BasicMotions.zip\"\n", 121 | "\n", 122 | "extract_dir = \"BasicMotions\"\n", 123 | "os.makedirs(extract_dir, exist_ok=True)\n", 124 | "\n", 125 | "print(\"Downloading ZIP file...\")\n", 126 | "response = requests.get(url)\n", 127 | "response.raise_for_status()\n", 128 | "\n", 129 | "with zipfile.ZipFile(io.BytesIO(response.content)) as zip_ref:\n", 130 | " ts_files = [f for f in zip_ref.namelist() if f.endswith(\".ts\")]\n", 131 | "\n", 132 | " print(f\"Extracting {len(ts_files)} .ts files...\")\n", 133 | " for file in ts_files:\n", 134 | " zip_ref.extract(file, extract_dir)\n", 135 | "\n", 136 | "print(f\"Extraction completed. Files are saved in '{extract_dir}'\")" 137 | ] 138 | }, 139 | { 140 | "cell_type": "markdown", 141 | "id": "10", 142 | "metadata": {}, 143 | "source": [ 144 | "## Read in the data and train the preprocessor" 145 | ] 146 | }, 147 | { 148 | "cell_type": "code", 149 | "execution_count": null, 150 | "id": "11", 151 | "metadata": {}, 152 | "outputs": [], 153 | "source": [ 154 | "dataset_name = \"BasicMotions\"" 155 | ] 156 | }, 157 | { 158 | "cell_type": "code", 159 | "execution_count": null, 160 | "id": "12", 161 | "metadata": {}, 162 | "outputs": [], 163 | "source": [ 164 | "path = f\"{dataset_name}/{dataset_name}_TRAIN.ts\" # training data path\n", 165 | "\n", 166 | "# .ts files to pandas df\n", 167 | "df_base = convert_tsfile_to_dataframe(\n", 168 | " path,\n", 169 | " return_separate_X_and_y=False,\n", 170 | ")\n", 171 | "label_column = \"class_vals\" # target column containing the labels\n", 172 | "input_columns = [f\"dim_{i}\" for i in range(df_base.shape[1] - 1)] # columns with the time-series data\n", 173 | "\n", 174 | "tsp = TimeSeriesClassificationPreprocessor(\n", 175 | " input_columns=input_columns,\n", 176 | " label_column=label_column,\n", 177 | " scaling=True,\n", 178 | ")\n", 179 | "\n", 180 | "tsp.train(df_base) # training the tsp (gets the scaling params for the data if scaling=True in tsp)\n", 181 | "df_prep = tsp.preprocess(df_base)\n", 182 | "base_dataset = ClassificationDFDataset(\n", 183 | " df_prep,\n", 184 | " id_columns=[],\n", 185 | " timestamp_column=None,\n", 186 | " input_columns=input_columns,\n", 187 | " label_column=label_column,\n", 188 | " context_length=512,\n", 189 | " static_categorical_columns=[],\n", 190 | " stride=1,\n", 191 | " enable_padding=False,\n", 192 | " full_series=True,\n", 193 | ")\n", 194 | "\n", 195 | "path = f\"{dataset_name}/{dataset_name}_TEST.ts\" # test data path\n", 196 | "\n", 197 | "# .ts files to pandas df\n", 198 | "df_test = convert_tsfile_to_dataframe(\n", 199 | " path,\n", 200 | " return_separate_X_and_y=False,\n", 201 | ")\n", 202 | "label_column = \"class_vals\" # target column containing the labels\n", 203 | "input_columns = [f\"dim_{i}\" for i in range(df_test.shape[1] - 1)] # columns with the time-series data\n", 204 | "\n", 205 | "df_test_prep = tsp.preprocess(df_test) # scaling the test data\n", 206 | "\n", 207 | "test_dataset = ClassificationDFDataset(\n", 208 | " df_test_prep,\n", 209 | " id_columns=[],\n", 210 | " timestamp_column=None,\n", 211 | " input_columns=input_columns,\n", 212 | " label_column=label_column,\n", 213 | " context_length=512,\n", 214 | " static_categorical_columns=[],\n", 215 | " stride=1,\n", 216 | " enable_padding=False,\n", 217 | " full_series=True,\n", 218 | ")" 219 | ] 220 | }, 221 | { 222 | "cell_type": "markdown", 223 | "id": "13", 224 | "metadata": {}, 225 | "source": [ 226 | "## Creating a validation set " 227 | ] 228 | }, 229 | { 230 | "cell_type": "code", 231 | "execution_count": null, 232 | "id": "14", 233 | "metadata": {}, 234 | "outputs": [], 235 | "source": [ 236 | "# Will use 10% of the data from training set as validation\n", 237 | "dataset_size = len(base_dataset)\n", 238 | "print(dataset_size)\n", 239 | "split_valid_ratio = 0.1\n", 240 | "val_size = int(split_valid_ratio * dataset_size) # 10% valid split\n", 241 | "train_size = dataset_size - val_size\n", 242 | "train_dataset, valid_dataset = random_split(base_dataset, [train_size, val_size])" 243 | ] 244 | }, 245 | { 246 | "cell_type": "markdown", 247 | "id": "15", 248 | "metadata": {}, 249 | "source": [ 250 | "## Configs for the TSPulse model" 251 | ] 252 | }, 253 | { 254 | "cell_type": "markdown", 255 | "id": "16", 256 | "metadata": {}, 257 | "source": [ 258 | "### Hyperparameters to Optimize and suggested values :\n", 259 | "**head_reduce_d_model** = 1 or 2 (Projection dimension each final layer embedding gets projected to as part of TSLens)\n", 260 | "\n", 261 | "**decoder_mode** = mix_channel or common_channel (The decoder can be finetuned either in a `mix channel` or `common channel` fashion. In `mix channel` mode the decoder tries to learn correlations between different channels in the multivariate dataset by mixing the patches along the channel dimension)\n", 262 | "\n", 263 | "**head_gated_attention_activation** = softmax or sigmoid (Activation Function used in Gated Attention in the decoder)\n", 264 | "\n", 265 | "**mask_ratio** = 0 or 0.3 (If Mask ratio is enabled (non-zero), block masking is applied during fine-tuning but disabled during evaluation to improve generalization and reduce overfitting on the data)\n", 266 | "\n", 267 | "**channel_virtual_expand_scale** = 1 or 2 (To increase the size of the channel mixer)" 268 | ] 269 | }, 270 | { 271 | "cell_type": "code", 272 | "execution_count": null, 273 | "id": "17", 274 | "metadata": {}, 275 | "outputs": [], 276 | "source": [ 277 | "config_dict = {\n", 278 | " \"head_reduce_d_model\": 1,\n", 279 | " \"decoder_mode\": \"mix_channel\",\n", 280 | " \"head_gated_attention_activation\": \"softmax\",\n", 281 | " \"mask_ratio\": 0.3,\n", 282 | " \"channel_virtual_expand_scale\": 2,\n", 283 | " \"loss\": \"cross_entropy\",\n", 284 | " \"disable_mask_in_classification_eval\": True,\n", 285 | " \"ignore_mismatched_sizes\": True,\n", 286 | "}\n", 287 | "\n", 288 | "config_dict[\"num_input_channels\"] = (\n", 289 | " tsp.num_input_channels\n", 290 | ") # Add the number of channels in the input dataset for model config\n", 291 | "config_dict[\"num_targets\"] = df_base[\n", 292 | " \"class_vals\"\n", 293 | "].nunique() # Add the number of different classes in the dataset for model config" 294 | ] 295 | }, 296 | { 297 | "cell_type": "markdown", 298 | "id": "18", 299 | "metadata": {}, 300 | "source": [ 301 | "## Getting the Pretrained TSPulse Model from HuggingFace with above configs" 302 | ] 303 | }, 304 | { 305 | "cell_type": "code", 306 | "execution_count": null, 307 | "id": "19", 308 | "metadata": {}, 309 | "outputs": [], 310 | "source": [ 311 | "model = TSPulseForClassification.from_pretrained(\n", 312 | " \"ibm-granite/granite-timeseries-tspulse-r1\", revision=\"tspulse-block-dualhead-512-p16-r1\", **config_dict\n", 313 | ")" 314 | ] 315 | }, 316 | { 317 | "cell_type": "code", 318 | "execution_count": null, 319 | "id": "20", 320 | "metadata": {}, 321 | "outputs": [], 322 | "source": [ 323 | "device = \"cuda\" if torch.cuda.is_available() else \"mps\" if torch.mps.is_available() else \"cpu\"\n", 324 | "print(device)\n", 325 | "model = model.to(device).float()" 326 | ] 327 | }, 328 | { 329 | "cell_type": "markdown", 330 | "id": "21", 331 | "metadata": {}, 332 | "source": [ 333 | "## Backbone of the pre-trained model is freezed and the classifier head along with the input patch embedding layer is finetuned on the classification dataset." 334 | ] 335 | }, 336 | { 337 | "cell_type": "code", 338 | "execution_count": null, 339 | "id": "22", 340 | "metadata": {}, 341 | "outputs": [], 342 | "source": [ 343 | "# Freezing the Backbone\n", 344 | "for param in model.backbone.parameters():\n", 345 | " param.requires_grad = False\n", 346 | "\n", 347 | "# Unfreezing the patch embedding layers\n", 348 | "for param in model.backbone.time_encoding.parameters():\n", 349 | " param.requires_grad = True\n", 350 | "for param in model.backbone.fft_encoding.parameters():\n", 351 | " param.requires_grad = True" 352 | ] 353 | }, 354 | { 355 | "cell_type": "markdown", 356 | "id": "23", 357 | "metadata": {}, 358 | "source": [ 359 | "## Finetuning the classifier head and patch embedding layer" 360 | ] 361 | }, 362 | { 363 | "cell_type": "code", 364 | "execution_count": null, 365 | "id": "24", 366 | "metadata": {}, 367 | "outputs": [], 368 | "source": [ 369 | "OUT_DIR = \"tspulse_finetuned_models/\"" 370 | ] 371 | }, 372 | { 373 | "cell_type": "code", 374 | "execution_count": null, 375 | "id": "25", 376 | "metadata": { 377 | "keep_output": true 378 | }, 379 | "outputs": [ 380 | { 381 | "name": "stderr", 382 | "output_type": "stream", 383 | "text": [ 384 | "INFO:p-6717:t-8353009472:lr_finder.py:optimal_lr_finder:LR Finder: Running learning rate (LR) finder algorithm. If the suggested LR is very low, we suggest setting the LR manually.\n", 385 | "INFO:p-6717:t-8353009472:lr_finder.py:optimal_lr_finder:LR Finder: Using mps.\n", 386 | "INFO:p-6717:t-8353009472:lr_finder.py:optimal_lr_finder:LR Finder: Suggested learning rate = 0.004037017258596558\n" 387 | ] 388 | }, 389 | { 390 | "name": "stdout", 391 | "output_type": "stream", 392 | "text": [ 393 | "Suggested LR : 0.004037017258596558\n" 394 | ] 395 | }, 396 | { 397 | "data": { 398 | "text/html": [ 399 | "\n", 400 | "
\n", 401 | " \n", 402 | " \n", 403 | " [356/400 1:42:55 < 12:47, 0.06 it/s, Epoch 178/200]\n", 404 | "
\n", 405 | " \n", 406 | " \n", 407 | " \n", 408 | " \n", 409 | " \n", 410 | " \n", 411 | " \n", 412 | " \n", 413 | " \n", 414 | " \n", 415 | " \n", 416 | " \n", 417 | " \n", 418 | " \n", 419 | " \n", 420 | " \n", 421 | " \n", 422 | " \n", 423 | " \n", 424 | " \n", 425 | " \n", 426 | " \n", 427 | " \n", 428 | " \n", 429 | " \n", 430 | " \n", 431 | " \n", 432 | " \n", 433 | " \n", 434 | " \n", 435 | " \n", 436 | " \n", 437 | " \n", 438 | " \n", 439 | " \n", 440 | " \n", 441 | " \n", 442 | " \n", 443 | " \n", 444 | " \n", 445 | " \n", 446 | " \n", 447 | " \n", 448 | " \n", 449 | " \n", 450 | " \n", 451 | " \n", 452 | " \n", 453 | " \n", 454 | " \n", 455 | " \n", 456 | " \n", 457 | " \n", 458 | " \n", 459 | " \n", 460 | " \n", 461 | " \n", 462 | " \n", 463 | " \n", 464 | " \n", 465 | " \n", 466 | " \n", 467 | " \n", 468 | " \n", 469 | " \n", 470 | " \n", 471 | " \n", 472 | " \n", 473 | " \n", 474 | " \n", 475 | " \n", 476 | " \n", 477 | " \n", 478 | " \n", 479 | " \n", 480 | " \n", 481 | " \n", 482 | " \n", 483 | " \n", 484 | " \n", 485 | " \n", 486 | " \n", 487 | " \n", 488 | " \n", 489 | " \n", 490 | " \n", 491 | " \n", 492 | " \n", 493 | " \n", 494 | " \n", 495 | " \n", 496 | " \n", 497 | " \n", 498 | " \n", 499 | " \n", 500 | " \n", 501 | " \n", 502 | " \n", 503 | " \n", 504 | " \n", 505 | " \n", 506 | " \n", 507 | " \n", 508 | " \n", 509 | " \n", 510 | " \n", 511 | " \n", 512 | " \n", 513 | " \n", 514 | " \n", 515 | " \n", 516 | " \n", 517 | " \n", 518 | " \n", 519 | " \n", 520 | " \n", 521 | " \n", 522 | " \n", 523 | " \n", 524 | " \n", 525 | " \n", 526 | " \n", 527 | " \n", 528 | " \n", 529 | " \n", 530 | " \n", 531 | " \n", 532 | " \n", 533 | " \n", 534 | " \n", 535 | " \n", 536 | " \n", 537 | " \n", 538 | " \n", 539 | " \n", 540 | " \n", 541 | " \n", 542 | " \n", 543 | " \n", 544 | " \n", 545 | " \n", 546 | " \n", 547 | " \n", 548 | " \n", 549 | " \n", 550 | " \n", 551 | " \n", 552 | " \n", 553 | " \n", 554 | " \n", 555 | " \n", 556 | " \n", 557 | " \n", 558 | " \n", 559 | " \n", 560 | " \n", 561 | " \n", 562 | " \n", 563 | " \n", 564 | " \n", 565 | " \n", 566 | " \n", 567 | " \n", 568 | " \n", 569 | " \n", 570 | " \n", 571 | " \n", 572 | " \n", 573 | " \n", 574 | " \n", 575 | " \n", 576 | " \n", 577 | " \n", 578 | " \n", 579 | " \n", 580 | " \n", 581 | " \n", 582 | " \n", 583 | " \n", 584 | " \n", 585 | " \n", 586 | " \n", 587 | " \n", 588 | " \n", 589 | " \n", 590 | " \n", 591 | " \n", 592 | " \n", 593 | " \n", 594 | " \n", 595 | " \n", 596 | " \n", 597 | " \n", 598 | " \n", 599 | " \n", 600 | " \n", 601 | " \n", 602 | " \n", 603 | " \n", 604 | " \n", 605 | " \n", 606 | " \n", 607 | " \n", 608 | " \n", 609 | " \n", 610 | " \n", 611 | " \n", 612 | " \n", 613 | " \n", 614 | " \n", 615 | " \n", 616 | " \n", 617 | " \n", 618 | " \n", 619 | " \n", 620 | " \n", 621 | " \n", 622 | " \n", 623 | " \n", 624 | " \n", 625 | " \n", 626 | " \n", 627 | " \n", 628 | " \n", 629 | " \n", 630 | " \n", 631 | " \n", 632 | " \n", 633 | " \n", 634 | " \n", 635 | " \n", 636 | " \n", 637 | " \n", 638 | " \n", 639 | " \n", 640 | " \n", 641 | " \n", 642 | " \n", 643 | " \n", 644 | " \n", 645 | " \n", 646 | " \n", 647 | " \n", 648 | " \n", 649 | " \n", 650 | " \n", 651 | " \n", 652 | " \n", 653 | " \n", 654 | " \n", 655 | " \n", 656 | " \n", 657 | " \n", 658 | " \n", 659 | " \n", 660 | " \n", 661 | " \n", 662 | " \n", 663 | " \n", 664 | " \n", 665 | " \n", 666 | " \n", 667 | " \n", 668 | " \n", 669 | " \n", 670 | " \n", 671 | " \n", 672 | " \n", 673 | " \n", 674 | " \n", 675 | " \n", 676 | " \n", 677 | " \n", 678 | " \n", 679 | " \n", 680 | " \n", 681 | " \n", 682 | " \n", 683 | " \n", 684 | " \n", 685 | " \n", 686 | " \n", 687 | " \n", 688 | " \n", 689 | " \n", 690 | " \n", 691 | " \n", 692 | " \n", 693 | " \n", 694 | " \n", 695 | " \n", 696 | " \n", 697 | " \n", 698 | " \n", 699 | " \n", 700 | " \n", 701 | " \n", 702 | " \n", 703 | " \n", 704 | " \n", 705 | " \n", 706 | " \n", 707 | " \n", 708 | " \n", 709 | " \n", 710 | " \n", 711 | " \n", 712 | " \n", 713 | " \n", 714 | " \n", 715 | " \n", 716 | " \n", 717 | " \n", 718 | " \n", 719 | " \n", 720 | " \n", 721 | " \n", 722 | " \n", 723 | " \n", 724 | " \n", 725 | " \n", 726 | " \n", 727 | " \n", 728 | " \n", 729 | " \n", 730 | " \n", 731 | " \n", 732 | " \n", 733 | " \n", 734 | " \n", 735 | " \n", 736 | " \n", 737 | " \n", 738 | " \n", 739 | " \n", 740 | " \n", 741 | " \n", 742 | " \n", 743 | " \n", 744 | " \n", 745 | " \n", 746 | " \n", 747 | " \n", 748 | " \n", 749 | " \n", 750 | " \n", 751 | " \n", 752 | " \n", 753 | " \n", 754 | " \n", 755 | " \n", 756 | " \n", 757 | " \n", 758 | " \n", 759 | " \n", 760 | " \n", 761 | " \n", 762 | " \n", 763 | " \n", 764 | " \n", 765 | " \n", 766 | " \n", 767 | " \n", 768 | " \n", 769 | " \n", 770 | " \n", 771 | " \n", 772 | " \n", 773 | " \n", 774 | " \n", 775 | " \n", 776 | " \n", 777 | " \n", 778 | " \n", 779 | " \n", 780 | " \n", 781 | " \n", 782 | " \n", 783 | " \n", 784 | " \n", 785 | " \n", 786 | " \n", 787 | " \n", 788 | " \n", 789 | " \n", 790 | " \n", 791 | " \n", 792 | " \n", 793 | " \n", 794 | " \n", 795 | " \n", 796 | " \n", 797 | " \n", 798 | " \n", 799 | " \n", 800 | " \n", 801 | " \n", 802 | " \n", 803 | " \n", 804 | " \n", 805 | " \n", 806 | " \n", 807 | " \n", 808 | " \n", 809 | " \n", 810 | " \n", 811 | " \n", 812 | " \n", 813 | " \n", 814 | " \n", 815 | " \n", 816 | " \n", 817 | " \n", 818 | " \n", 819 | " \n", 820 | " \n", 821 | " \n", 822 | " \n", 823 | " \n", 824 | " \n", 825 | " \n", 826 | " \n", 827 | " \n", 828 | " \n", 829 | " \n", 830 | " \n", 831 | " \n", 832 | " \n", 833 | " \n", 834 | " \n", 835 | " \n", 836 | " \n", 837 | " \n", 838 | " \n", 839 | " \n", 840 | " \n", 841 | " \n", 842 | " \n", 843 | " \n", 844 | " \n", 845 | " \n", 846 | " \n", 847 | " \n", 848 | " \n", 849 | " \n", 850 | " \n", 851 | " \n", 852 | " \n", 853 | " \n", 854 | " \n", 855 | " \n", 856 | " \n", 857 | " \n", 858 | " \n", 859 | " \n", 860 | " \n", 861 | " \n", 862 | " \n", 863 | " \n", 864 | " \n", 865 | " \n", 866 | " \n", 867 | " \n", 868 | " \n", 869 | " \n", 870 | " \n", 871 | " \n", 872 | " \n", 873 | " \n", 874 | " \n", 875 | " \n", 876 | " \n", 877 | " \n", 878 | " \n", 879 | " \n", 880 | " \n", 881 | " \n", 882 | " \n", 883 | " \n", 884 | " \n", 885 | " \n", 886 | " \n", 887 | " \n", 888 | " \n", 889 | " \n", 890 | " \n", 891 | " \n", 892 | " \n", 893 | " \n", 894 | " \n", 895 | " \n", 896 | " \n", 897 | " \n", 898 | " \n", 899 | " \n", 900 | " \n", 901 | " \n", 902 | " \n", 903 | " \n", 904 | " \n", 905 | " \n", 906 | " \n", 907 | " \n", 908 | " \n", 909 | " \n", 910 | " \n", 911 | " \n", 912 | " \n", 913 | " \n", 914 | " \n", 915 | " \n", 916 | " \n", 917 | " \n", 918 | " \n", 919 | " \n", 920 | " \n", 921 | " \n", 922 | " \n", 923 | " \n", 924 | " \n", 925 | " \n", 926 | " \n", 927 | " \n", 928 | " \n", 929 | " \n", 930 | " \n", 931 | " \n", 932 | " \n", 933 | " \n", 934 | " \n", 935 | " \n", 936 | " \n", 937 | " \n", 938 | " \n", 939 | " \n", 940 | " \n", 941 | " \n", 942 | " \n", 943 | " \n", 944 | " \n", 945 | " \n", 946 | " \n", 947 | " \n", 948 | " \n", 949 | " \n", 950 | " \n", 951 | " \n", 952 | " \n", 953 | " \n", 954 | " \n", 955 | " \n", 956 | " \n", 957 | " \n", 958 | " \n", 959 | " \n", 960 | " \n", 961 | " \n", 962 | " \n", 963 | " \n", 964 | " \n", 965 | " \n", 966 | " \n", 967 | " \n", 968 | " \n", 969 | " \n", 970 | " \n", 971 | " \n", 972 | " \n", 973 | " \n", 974 | " \n", 975 | " \n", 976 | " \n", 977 | " \n", 978 | " \n", 979 | " \n", 980 | " \n", 981 | " \n", 982 | " \n", 983 | " \n", 984 | " \n", 985 | " \n", 986 | " \n", 987 | " \n", 988 | " \n", 989 | " \n", 990 | " \n", 991 | " \n", 992 | " \n", 993 | " \n", 994 | " \n", 995 | " \n", 996 | " \n", 997 | " \n", 998 | " \n", 999 | " \n", 1000 | " \n", 1001 | " \n", 1002 | " \n", 1003 | " \n", 1004 | " \n", 1005 | " \n", 1006 | " \n", 1007 | " \n", 1008 | " \n", 1009 | " \n", 1010 | " \n", 1011 | " \n", 1012 | " \n", 1013 | " \n", 1014 | " \n", 1015 | " \n", 1016 | " \n", 1017 | " \n", 1018 | " \n", 1019 | " \n", 1020 | " \n", 1021 | " \n", 1022 | " \n", 1023 | " \n", 1024 | " \n", 1025 | " \n", 1026 | " \n", 1027 | " \n", 1028 | " \n", 1029 | " \n", 1030 | " \n", 1031 | " \n", 1032 | " \n", 1033 | " \n", 1034 | " \n", 1035 | " \n", 1036 | " \n", 1037 | " \n", 1038 | " \n", 1039 | " \n", 1040 | " \n", 1041 | " \n", 1042 | " \n", 1043 | " \n", 1044 | " \n", 1045 | " \n", 1046 | " \n", 1047 | " \n", 1048 | " \n", 1049 | " \n", 1050 | " \n", 1051 | " \n", 1052 | " \n", 1053 | " \n", 1054 | " \n", 1055 | " \n", 1056 | " \n", 1057 | " \n", 1058 | " \n", 1059 | " \n", 1060 | " \n", 1061 | " \n", 1062 | " \n", 1063 | " \n", 1064 | " \n", 1065 | " \n", 1066 | " \n", 1067 | " \n", 1068 | " \n", 1069 | " \n", 1070 | " \n", 1071 | " \n", 1072 | " \n", 1073 | " \n", 1074 | " \n", 1075 | " \n", 1076 | " \n", 1077 | " \n", 1078 | " \n", 1079 | " \n", 1080 | " \n", 1081 | " \n", 1082 | " \n", 1083 | " \n", 1084 | " \n", 1085 | " \n", 1086 | " \n", 1087 | " \n", 1088 | " \n", 1089 | " \n", 1090 | " \n", 1091 | " \n", 1092 | " \n", 1093 | " \n", 1094 | " \n", 1095 | " \n", 1096 | " \n", 1097 | " \n", 1098 | " \n", 1099 | " \n", 1100 | " \n", 1101 | " \n", 1102 | " \n", 1103 | " \n", 1104 | " \n", 1105 | " \n", 1106 | " \n", 1107 | " \n", 1108 | " \n", 1109 | " \n", 1110 | " \n", 1111 | " \n", 1112 | " \n", 1113 | " \n", 1114 | " \n", 1115 | " \n", 1116 | " \n", 1117 | " \n", 1118 | " \n", 1119 | " \n", 1120 | " \n", 1121 | " \n", 1122 | " \n", 1123 | " \n", 1124 | " \n", 1125 | " \n", 1126 | " \n", 1127 | " \n", 1128 | " \n", 1129 | " \n", 1130 | " \n", 1131 | " \n", 1132 | " \n", 1133 | " \n", 1134 | " \n", 1135 | " \n", 1136 | " \n", 1137 | " \n", 1138 | " \n", 1139 | " \n", 1140 | " \n", 1141 | " \n", 1142 | " \n", 1143 | " \n", 1144 | " \n", 1145 | " \n", 1146 | " \n", 1147 | " \n", 1148 | " \n", 1149 | " \n", 1150 | " \n", 1151 | " \n", 1152 | " \n", 1153 | " \n", 1154 | " \n", 1155 | " \n", 1156 | " \n", 1157 | " \n", 1158 | " \n", 1159 | " \n", 1160 | " \n", 1161 | " \n", 1162 | " \n", 1163 | " \n", 1164 | " \n", 1165 | " \n", 1166 | " \n", 1167 | " \n", 1168 | " \n", 1169 | " \n", 1170 | " \n", 1171 | " \n", 1172 | " \n", 1173 | " \n", 1174 | " \n", 1175 | " \n", 1176 | " \n", 1177 | " \n", 1178 | " \n", 1179 | " \n", 1180 | " \n", 1181 | " \n", 1182 | " \n", 1183 | " \n", 1184 | " \n", 1185 | " \n", 1186 | " \n", 1187 | " \n", 1188 | " \n", 1189 | " \n", 1190 | " \n", 1191 | " \n", 1192 | " \n", 1193 | " \n", 1194 | " \n", 1195 | " \n", 1196 | " \n", 1197 | " \n", 1198 | " \n", 1199 | " \n", 1200 | " \n", 1201 | " \n", 1202 | " \n", 1203 | " \n", 1204 | " \n", 1205 | " \n", 1206 | " \n", 1207 | " \n", 1208 | " \n", 1209 | " \n", 1210 | " \n", 1211 | " \n", 1212 | " \n", 1213 | " \n", 1214 | " \n", 1215 | " \n", 1216 | " \n", 1217 | " \n", 1218 | " \n", 1219 | " \n", 1220 | " \n", 1221 | " \n", 1222 | " \n", 1223 | " \n", 1224 | " \n", 1225 | " \n", 1226 | " \n", 1227 | " \n", 1228 | " \n", 1229 | " \n", 1230 | " \n", 1231 | " \n", 1232 | " \n", 1233 | " \n", 1234 | " \n", 1235 | " \n", 1236 | " \n", 1237 | " \n", 1238 | " \n", 1239 | " \n", 1240 | " \n", 1241 | " \n", 1242 | " \n", 1243 | " \n", 1244 | " \n", 1245 | " \n", 1246 | " \n", 1247 | " \n", 1248 | " \n", 1249 | " \n", 1250 | " \n", 1251 | " \n", 1252 | " \n", 1253 | " \n", 1254 | " \n", 1255 | " \n", 1256 | " \n", 1257 | " \n", 1258 | " \n", 1259 | " \n", 1260 | " \n", 1261 | " \n", 1262 | " \n", 1263 | " \n", 1264 | " \n", 1265 | " \n", 1266 | " \n", 1267 | " \n", 1268 | " \n", 1269 | " \n", 1270 | " \n", 1271 | " \n", 1272 | " \n", 1273 | " \n", 1274 | " \n", 1275 | " \n", 1276 | " \n", 1277 | " \n", 1278 | " \n", 1279 | " \n", 1280 | " \n", 1281 | " \n", 1282 | " \n", 1283 | " \n", 1284 | " \n", 1285 | " \n", 1286 | " \n", 1287 | " \n", 1288 | " \n", 1289 | " \n", 1290 | " \n", 1291 | " \n", 1292 | " \n", 1293 | " \n", 1294 | " \n", 1295 | " \n", 1296 | " \n", 1297 | " \n", 1298 | " \n", 1299 | " \n", 1300 | " \n", 1301 | " \n", 1302 | " \n", 1303 | " \n", 1304 | " \n", 1305 | "
EpochTraining LossValidation Loss
11.6399001.453306
21.4383001.445638
31.4208001.437968
41.4599001.432224
51.3969001.428331
61.4139001.426167
71.4201001.426166
81.5508001.427413
91.4320001.428102
101.4322001.427513
111.4780001.426048
121.2923001.423473
131.3223001.424342
141.2131001.427539
151.1591001.436816
161.0601001.446607
171.0912001.441536
181.1642001.419283
191.0848001.384548
201.0593001.320123
210.9797001.232783
220.9213001.146906
230.9872001.073195
240.9157001.011746
250.8233000.955031
260.7119000.898865
270.7078000.869616
280.5042000.836212
290.4398000.780413
300.4270000.639821
310.3742000.527213
320.2656000.480379
330.1869000.456565
340.1471000.385372
350.0788000.302945
360.1305000.331878
370.0799000.346033
380.0507000.339857
390.0950000.315303
400.0367000.152956
410.0182000.099610
420.0242000.115569
430.0205000.158272
440.0347000.094213
450.0136000.055601
460.0283000.051443
470.0117000.059635
480.0164000.056245
490.0181000.044631
500.0269000.072916
510.0122000.132457
520.0106000.123472
530.0071000.102167
540.0070000.089179
550.0084000.051932
560.0167000.058287
570.0093000.096944
580.0065000.101712
590.0127000.077231
600.0050000.048469
610.0085000.023316
620.0069000.013692
630.0057000.009152
640.0057000.007506
650.0071000.009395
660.0017000.013297
670.0015000.017547
680.0043000.018828
690.0021000.018991
700.0015000.018569
710.0038000.016002
720.0046000.013317
730.0010000.011652
740.0007000.010674
750.0107000.007814
760.0016000.012548
770.0063000.005862
780.0070000.002127
790.0027000.002558
800.0019000.004588
810.0126000.004968
820.0053000.006956
830.0016000.005280
840.0023000.007087
850.0139000.016613
860.0081000.021444
870.0019000.036337
880.0155000.025013
890.0028000.025288
900.0052000.021512
910.0146000.052308
920.0066000.104700
930.0059000.091845
940.0014000.065498
950.0017000.043243
960.0051000.028275
970.0012000.020108
980.0026000.019708
990.0005000.020374
1000.0005000.021043
1010.0021000.024295
1020.0016000.031856
1030.0016000.038888
1040.0010000.042329
1050.0003000.044966
1060.0010000.042500
1070.0004000.040708
1080.0006000.038000
1090.0009000.033279
1100.0007000.030622
1110.0018000.025987
1120.0013000.020501
1130.0004000.017051
1140.0006000.014982
1150.0005000.013498
1160.0003000.012563
1170.0010000.012730
1180.0007000.013491
1190.0003000.014173
1200.0004000.014783
1210.0011000.015869
1220.0013000.016323
1230.0002000.016727
1240.0005000.016988
1250.0005000.016735
1260.0002000.016115
1270.0004000.015434
1280.0006000.014995
1290.0010000.014653
1300.0006000.014476
1310.0001000.014345
1320.0002000.014203
1330.0026000.013231
1340.0003000.011789
1350.0004000.010679
1360.0006000.009528
1370.0005000.008712
1380.0002000.008125
1390.0002000.007716
1400.0007000.007631
1410.0009000.007751
1420.0021000.007976
1430.0010000.008179
1440.0006000.008270
1450.0005000.008377
1460.0010000.008517
1470.0002000.008637
1480.0008000.008728
1490.0003000.008801
1500.0003000.008835
1510.0007000.008812
1520.0001000.008764
1530.0005000.008700
1540.0006000.008704
1550.0002000.008700
1560.0003000.008690
1570.0002000.008684
1580.0002000.008697
1590.0002000.008701
1600.0002000.008700
1610.0001000.008703
1620.0008000.008803
1630.0003000.008899
1640.0002000.008974
1650.0005000.009033
1660.0005000.009049
1670.0003000.009080
1680.0003000.009105
1690.0009000.009114
1700.0003000.009132
1710.0003000.009150
1720.0003000.009170
1730.0006000.009209
1740.0008000.009241
1750.0002000.009280
1760.0005000.009308
1770.0008000.009326
1780.0003000.009335

" 1306 | ], 1307 | "text/plain": [ 1308 | "" 1309 | ] 1310 | }, 1311 | "metadata": {}, 1312 | "output_type": "display_data" 1313 | }, 1314 | { 1315 | "data": { 1316 | "text/plain": [ 1317 | "TrainOutput(global_step=356, training_loss=0.20193236314891405, metrics={'train_runtime': 6177.9467, 'train_samples_per_second': 1.165, 'train_steps_per_second': 0.065, 'total_flos': 43968114081792.0, 'train_loss': 0.20193236314891405, 'epoch': 178.0})" 1318 | ] 1319 | }, 1320 | "execution_count": null, 1321 | "metadata": {}, 1322 | "output_type": "execute_result" 1323 | } 1324 | ], 1325 | "source": [ 1326 | "temp_dir = tempfile.mkdtemp()\n", 1327 | "\n", 1328 | "suggested_lr = None\n", 1329 | "\n", 1330 | "train_dict = {\"per_device_train_batch_size\": 32, \"num_train_epochs\": 200, \"eval_accumulation_steps\": None}\n", 1331 | "EPOCHS = train_dict[\"num_train_epochs\"]\n", 1332 | "BATCH_SIZE = train_dict[\"per_device_train_batch_size\"]\n", 1333 | "eval_accumulation_steps = train_dict[\"eval_accumulation_steps\"]\n", 1334 | "NUM_WORKERS = 1\n", 1335 | "NUM_GPUS = 1\n", 1336 | "\n", 1337 | "set_seed(42)\n", 1338 | "if suggested_lr is None:\n", 1339 | " lr, model = optimal_lr_finder(\n", 1340 | " model,\n", 1341 | " train_dataset,\n", 1342 | " batch_size=BATCH_SIZE,\n", 1343 | " )\n", 1344 | " suggested_lr = lr\n", 1345 | "print(\"Suggested LR : \", suggested_lr)\n", 1346 | "finetune_args = TrainingArguments(\n", 1347 | " output_dir=temp_dir,\n", 1348 | " overwrite_output_dir=True,\n", 1349 | " learning_rate=suggested_lr,\n", 1350 | " num_train_epochs=EPOCHS,\n", 1351 | " do_eval=True,\n", 1352 | " eval_strategy=\"epoch\",\n", 1353 | " per_device_train_batch_size=BATCH_SIZE,\n", 1354 | " per_device_eval_batch_size=BATCH_SIZE,\n", 1355 | " eval_accumulation_steps=eval_accumulation_steps,\n", 1356 | " dataloader_num_workers=NUM_WORKERS,\n", 1357 | " report_to=\"tensorboard\",\n", 1358 | " save_strategy=\"epoch\",\n", 1359 | " logging_strategy=\"epoch\",\n", 1360 | " save_total_limit=1,\n", 1361 | " logging_dir=os.path.join(OUT_DIR, \"output\"), # Make sure to specify a logging directory\n", 1362 | " load_best_model_at_end=True, # Load the best model when training ends\n", 1363 | " metric_for_best_model=\"eval_loss\", # Metric to monitor for early stopping\n", 1364 | " greater_is_better=False, # For loss\n", 1365 | ")\n", 1366 | "\n", 1367 | "# Create the early stopping callback\n", 1368 | "early_stopping_callback = EarlyStoppingCallback(\n", 1369 | " early_stopping_patience=100, # Number of epochs with no improvement after which to stop\n", 1370 | " early_stopping_threshold=0.0001, # Minimum improvement required to consider as improvement\n", 1371 | ")\n", 1372 | "\n", 1373 | "# Optimizer and scheduler\n", 1374 | "optimizer = AdamW(model.parameters(), lr=suggested_lr)\n", 1375 | "scheduler = OneCycleLR(\n", 1376 | " optimizer,\n", 1377 | " suggested_lr,\n", 1378 | " epochs=EPOCHS,\n", 1379 | " steps_per_epoch=math.ceil(len(train_dataset) / (BATCH_SIZE * NUM_GPUS)),\n", 1380 | ")\n", 1381 | "\n", 1382 | "finetune_trainer = Trainer(\n", 1383 | " model=model,\n", 1384 | " args=finetune_args,\n", 1385 | " train_dataset=train_dataset,\n", 1386 | " eval_dataset=valid_dataset,\n", 1387 | " callbacks=[early_stopping_callback],\n", 1388 | " optimizers=(optimizer, scheduler),\n", 1389 | ")\n", 1390 | "\n", 1391 | "# Fine tune\n", 1392 | "finetune_trainer.train()" 1393 | ] 1394 | }, 1395 | { 1396 | "cell_type": "markdown", 1397 | "id": "26", 1398 | "metadata": {}, 1399 | "source": [ 1400 | "## Evaluating the model" 1401 | ] 1402 | }, 1403 | { 1404 | "cell_type": "code", 1405 | "execution_count": null, 1406 | "id": "27", 1407 | "metadata": { 1408 | "keep_output": true 1409 | }, 1410 | "outputs": [ 1411 | { 1412 | "data": { 1413 | "text/html": [], 1414 | "text/plain": [ 1415 | "" 1416 | ] 1417 | }, 1418 | "metadata": {}, 1419 | "output_type": "display_data" 1420 | }, 1421 | { 1422 | "name": "stdout", 1423 | "output_type": "stream", 1424 | "text": [ 1425 | "test_accuracy : 1.0\n" 1426 | ] 1427 | } 1428 | ], 1429 | "source": [ 1430 | "# Getting the classification accuracy score\n", 1431 | "predictions_dict = finetune_trainer.predict(test_dataset)\n", 1432 | "preds_np = predictions_dict.predictions[0]\n", 1433 | "\n", 1434 | "remove_columns_collator = RemoveColumnsCollator(\n", 1435 | " data_collator=default_data_collator,\n", 1436 | " signature_columns=[\"target_values\"],\n", 1437 | " logger=None,\n", 1438 | " description=None,\n", 1439 | " model_name=\"temp\",\n", 1440 | ")\n", 1441 | "\n", 1442 | "test_dataloader = DataLoader(test_dataset, batch_size=32, shuffle=False, collate_fn=remove_columns_collator)\n", 1443 | "target_list = []\n", 1444 | "for batch in test_dataloader:\n", 1445 | " batch_labels = batch[\"target_values\"].numpy()\n", 1446 | " target_list.append(batch_labels)\n", 1447 | "targets_np = np.concatenate(target_list, axis=0)\n", 1448 | "test_accuracy = np.mean(targets_np == np.argmax(preds_np, axis=1))\n", 1449 | "print(\"test_accuracy : \", test_accuracy)" 1450 | ] 1451 | }, 1452 | { 1453 | "cell_type": "markdown", 1454 | "id": "28", 1455 | "metadata": {}, 1456 | "source": [ 1457 | "## Using Classification Pipeline for inference with the finetuned model" 1458 | ] 1459 | }, 1460 | { 1461 | "cell_type": "code", 1462 | "execution_count": null, 1463 | "id": "29", 1464 | "metadata": {}, 1465 | "outputs": [], 1466 | "source": [ 1467 | "from tsfm_public.toolkit.time_series_classification_pipeline import TimeSeriesClassificationPipeline\n", 1468 | "\n", 1469 | "pipe = TimeSeriesClassificationPipeline(finetune_trainer.model, feature_extractor=tsp, device=device)" 1470 | ] 1471 | }, 1472 | { 1473 | "cell_type": "code", 1474 | "execution_count": null, 1475 | "id": "30", 1476 | "metadata": {}, 1477 | "outputs": [], 1478 | "source": [ 1479 | "out = pipe(df_test) # passing the test dataframe to pipeline for inference" 1480 | ] 1481 | }, 1482 | { 1483 | "cell_type": "markdown", 1484 | "id": "31", 1485 | "metadata": {}, 1486 | "source": [ 1487 | "### Actual ground truth labels vs the labels predicted\n", 1488 | "This dataset has four different classes: Walking, Running, Standing and Badminton" 1489 | ] 1490 | }, 1491 | { 1492 | "cell_type": "code", 1493 | "execution_count": null, 1494 | "id": "32", 1495 | "metadata": { 1496 | "keep_output": true 1497 | }, 1498 | "outputs": [ 1499 | { 1500 | "data": { 1501 | "text/html": [ 1502 | "

\n", 1503 | "\n", 1516 | "\n", 1517 | " \n", 1518 | " \n", 1519 | " \n", 1520 | " \n", 1521 | " \n", 1522 | " \n", 1523 | " \n", 1524 | " \n", 1525 | " \n", 1526 | " \n", 1527 | " \n", 1528 | " \n", 1529 | " \n", 1530 | " \n", 1531 | " \n", 1532 | " \n", 1533 | " \n", 1534 | " \n", 1535 | " \n", 1536 | " \n", 1537 | " \n", 1538 | " \n", 1539 | " \n", 1540 | " \n", 1541 | " \n", 1542 | " \n", 1543 | " \n", 1544 | " \n", 1545 | " \n", 1546 | " \n", 1547 | " \n", 1548 | " \n", 1549 | " \n", 1550 | " \n", 1551 | " \n", 1552 | " \n", 1553 | " \n", 1554 | " \n", 1555 | " \n", 1556 | " \n", 1557 | " \n", 1558 | " \n", 1559 | " \n", 1560 | " \n", 1561 | " \n", 1562 | " \n", 1563 | " \n", 1564 | " \n", 1565 | " \n", 1566 | " \n", 1567 | " \n", 1568 | " \n", 1569 | " \n", 1570 | " \n", 1571 | " \n", 1572 | " \n", 1573 | " \n", 1574 | " \n", 1575 | " \n", 1576 | " \n", 1577 | " \n", 1578 | " \n", 1579 | " \n", 1580 | " \n", 1581 | " \n", 1582 | " \n", 1583 | " \n", 1584 | " \n", 1585 | " \n", 1586 | " \n", 1587 | " \n", 1588 | " \n", 1589 | " \n", 1590 | " \n", 1591 | " \n", 1592 | " \n", 1593 | " \n", 1594 | " \n", 1595 | " \n", 1596 | " \n", 1597 | " \n", 1598 | " \n", 1599 | " \n", 1600 | " \n", 1601 | " \n", 1602 | " \n", 1603 | " \n", 1604 | " \n", 1605 | " \n", 1606 | " \n", 1607 | " \n", 1608 | " \n", 1609 | " \n", 1610 | " \n", 1611 | " \n", 1612 | " \n", 1613 | " \n", 1614 | " \n", 1615 | " \n", 1616 | " \n", 1617 | " \n", 1618 | " \n", 1619 | " \n", 1620 | " \n", 1621 | " \n", 1622 | " \n", 1623 | " \n", 1624 | " \n", 1625 | " \n", 1626 | " \n", 1627 | " \n", 1628 | " \n", 1629 | " \n", 1630 | " \n", 1631 | " \n", 1632 | " \n", 1633 | " \n", 1634 | " \n", 1635 | " \n", 1636 | " \n", 1637 | " \n", 1638 | " \n", 1639 | " \n", 1640 | " \n", 1641 | " \n", 1642 | " \n", 1643 | " \n", 1644 | " \n", 1645 | " \n", 1646 | " \n", 1647 | " \n", 1648 | " \n", 1649 | " \n", 1650 | " \n", 1651 | " \n", 1652 | " \n", 1653 | " \n", 1654 | " \n", 1655 | " \n", 1656 | " \n", 1657 | " \n", 1658 | " \n", 1659 | " \n", 1660 | " \n", 1661 | " \n", 1662 | " \n", 1663 | " \n", 1664 | " \n", 1665 | " \n", 1666 | " \n", 1667 | " \n", 1668 | " \n", 1669 | " \n", 1670 | " \n", 1671 | " \n", 1672 | " \n", 1673 | " \n", 1674 | " \n", 1675 | " \n", 1676 | " \n", 1677 | " \n", 1678 | " \n", 1679 | " \n", 1680 | " \n", 1681 | " \n", 1682 | " \n", 1683 | " \n", 1684 | " \n", 1685 | " \n", 1686 | " \n", 1687 | " \n", 1688 | " \n", 1689 | " \n", 1690 | " \n", 1691 | " \n", 1692 | " \n", 1693 | " \n", 1694 | " \n", 1695 | " \n", 1696 | " \n", 1697 | " \n", 1698 | " \n", 1699 | " \n", 1700 | " \n", 1701 | " \n", 1702 | " \n", 1703 | " \n", 1704 | " \n", 1705 | " \n", 1706 | " \n", 1707 | " \n", 1708 | " \n", 1709 | " \n", 1710 | " \n", 1711 | " \n", 1712 | " \n", 1713 | " \n", 1714 | " \n", 1715 | " \n", 1716 | " \n", 1717 | " \n", 1718 | " \n", 1719 | " \n", 1720 | " \n", 1721 | " \n", 1722 | " \n", 1723 | " \n", 1724 | " \n", 1725 | " \n", 1726 | "
class_valsclass_vals_prediction
0standingstanding
1standingstanding
2standingstanding
3standingstanding
4standingstanding
5standingstanding
6standingstanding
7standingstanding
8standingstanding
9standingstanding
10runningrunning
11runningrunning
12runningrunning
13runningrunning
14runningrunning
15runningrunning
16runningrunning
17runningrunning
18runningrunning
19runningrunning
20walkingwalking
21walkingwalking
22walkingwalking
23walkingwalking
24walkingwalking
25walkingwalking
26walkingwalking
27walkingwalking
28walkingwalking
29walkingwalking
30badmintonbadminton
31badmintonbadminton
32badmintonbadminton
33badmintonbadminton
34badmintonbadminton
35badmintonbadminton
36badmintonbadminton
37badmintonbadminton
38badmintonbadminton
39badmintonbadminton
\n", 1727 | "
" 1728 | ], 1729 | "text/plain": [ 1730 | " class_vals class_vals_prediction\n", 1731 | "0 standing standing\n", 1732 | "1 standing standing\n", 1733 | "2 standing standing\n", 1734 | "3 standing standing\n", 1735 | "4 standing standing\n", 1736 | "5 standing standing\n", 1737 | "6 standing standing\n", 1738 | "7 standing standing\n", 1739 | "8 standing standing\n", 1740 | "9 standing standing\n", 1741 | "10 running running\n", 1742 | "11 running running\n", 1743 | "12 running running\n", 1744 | "13 running running\n", 1745 | "14 running running\n", 1746 | "15 running running\n", 1747 | "16 running running\n", 1748 | "17 running running\n", 1749 | "18 running running\n", 1750 | "19 running running\n", 1751 | "20 walking walking\n", 1752 | "21 walking walking\n", 1753 | "22 walking walking\n", 1754 | "23 walking walking\n", 1755 | "24 walking walking\n", 1756 | "25 walking walking\n", 1757 | "26 walking walking\n", 1758 | "27 walking walking\n", 1759 | "28 walking walking\n", 1760 | "29 walking walking\n", 1761 | "30 badminton badminton\n", 1762 | "31 badminton badminton\n", 1763 | "32 badminton badminton\n", 1764 | "33 badminton badminton\n", 1765 | "34 badminton badminton\n", 1766 | "35 badminton badminton\n", 1767 | "36 badminton badminton\n", 1768 | "37 badminton badminton\n", 1769 | "38 badminton badminton\n", 1770 | "39 badminton badminton" 1771 | ] 1772 | }, 1773 | "execution_count": null, 1774 | "metadata": {}, 1775 | "output_type": "execute_result" 1776 | } 1777 | ], 1778 | "source": [ 1779 | "# Actual and Ground Truth columns from the pipeline's output df\n", 1780 | "out[[\"class_vals\", \"class_vals_prediction\"]]" 1781 | ] 1782 | }, 1783 | { 1784 | "cell_type": "markdown", 1785 | "id": "33", 1786 | "metadata": {}, 1787 | "source": [ 1788 | "## Links\n", 1789 | "* Library: [Granite TSFM on Github](https://github.com/ibm-granite/granite-tsfm)\n", 1790 | "* Model: [TSPulse on HuggingFace](https://huggingface.co/ibm-granite/granite-timeseries-tspulse-r1)\n", 1791 | "* Dataset: [BasicMotions from UEA Classification Archive](https://www.timeseriesclassification.com/description.php?Dataset=BasicMotions)" 1792 | ] 1793 | } 1794 | ], 1795 | "metadata": { 1796 | "language_info": { 1797 | "codemirror_mode": { 1798 | "name": "ipython", 1799 | "version": 3 1800 | }, 1801 | "file_extension": ".py", 1802 | "mimetype": "text/x-python", 1803 | "name": "python", 1804 | "nbconvert_exporter": "python", 1805 | "pygments_lexer": "ipython3" 1806 | } 1807 | }, 1808 | "nbformat": 4, 1809 | "nbformat_minor": 5 1810 | } 1811 | --------------------------------------------------------------------------------