# HDFORCE v1.1.2 <img src="docs/img/hdlogo_sm.png" align="right" alt="" width="120" />
**Get your data from the Hawkin Dynamics API**
<!-- badges: start -->
[](https://github.com/HawkinDynamics/hawkinPy/actions/workflows/push-test.yml)
[](https://www.repostatus.org/#active)
[](https://www.tidyverse.org/lifecycle/#stable)
[](https://choosealicense.com/)
<!-- badges: end -->
## How To Use The HDFORCE Package
HDFORCE provides simple functionality with Hawkin Dynamics API. These functions are for use with ‘Hawkin Dynamics Beta API’ version 1.10-beta. You must be a Hawkin Dynamics user with an active integration account to utilize functions within the package.
## Functions
This API is designed to get data out of your Hawkin Dynamics server and interact with your data more intimately. It is not designed to be accessed from client applications directly. There is a limit on the amount of data that can be returned in a single request (256 MB). As your database grows, it will be necessary to use the `from_` and `to_` parameters to limit the size of the responses. Responses that exceed the memory limit will timeout and fail. It is advised that you design your client to handle this from the beginning. A recommended pattern would be to have two methods of fetching data. A scheduled pull that uses the `from_` and `to_` parameters to constrain the returned data to only tests that have occurred since the last fetch e.g. every day or every 5 minutes. And then a pull that fetches the entire database since you began testing that is only executed when necessary. A recommended way of doing this is to generate the `from_` and `to_` parameters for each month since you started and send a request for each either in parallel or sequentially.
This package was meant to help execute requests to the Hawkin Dynamics API with a single line of code. There are 13 functions to help execute 4 primary objectives:
### Authentication
Use the Refresh Token generated by https://cloud.hawkindynamics.com/integrations to get a valid Access Token. Only the organization administrator account can generate API tokens. Use this function to initiate access to your data in the cloud. All other HDFORCE functions will depend on the values returned from this function.
In HDFORCE, we can create and manage your authentication settings with the `authManager` function. The arguments passed will be used to handle authentication for the other functions used in the program. With this function, you can control these settings:
* __region__: Sets the URL prefix of your cloud site.
* __authMethod__: Sets storage method of auth variables. One of env, file, or manual. Default to 'env'.
* __refreshToken_name__: Provide or set the name of the refresh Token variable. Default to "HD_REFRESH_TOKEN".
* __refreshToken__: Optionally provided to pass a token for authentication when authMethod="manual". Else it will set the refresh token value when provided.
* __env_file_name__: Required when authManager="file". Directs storage location of variables.
The authentication manager allows the user to manage authentication with various development strategies. The 'env' method was designed to allow for simple authentication while developing in a local or contained environment, where the refresh token and variables are stored in the system environment. The 'file' method can be used for more visible and dynamic interaction with the auth variables, as the refresh token and variables are stored with a .env file. While the 'manual' method allows for the use of the package without storing sensitive data, in so the refresh token is not stored and is only used for authentication. This could be helpful in the scenario of developing a password-protected application where the token can be used as a password.
In the case of the "file" method, the user will need to save a .env file in the source directory. When using this method, you will also need to pass the file name to the `env_file_name` argument as a string. It's most common to use something as simple as ".env", but you can name your file anything ending with .env.
Below is an example of what the .env file can look like. This can be used as a template, as the variable name "HD_REFRESH_TOKEN" is the default to what the `authManager` function will use for the `refreshToken_name`. If you want to use a different variable name, simply pass the string through the `refreshToken_name` argument, along with the token to the `refreshToken` argument. The other values for ACCESS_TOKEN, TOKEN_EXPIRATION, and CLOUD_URL are defaults within the `authManager` function and should be maintained.
``` PowerShell
# Inside your .env file
HD_REFRESH_TOKEN=your_api_token # Replace With Your Refresh Token
REGION=your_region # Replace With Your URL region
ACCESS_TOKEN= # Access token will be stored here
TOKEN_EXPIRATION= # Token Expiration will be stored here
CLOUD_URL= # Your region's URL here
```
With the variables stored, we can use them with our other functions without worrying about authentication for each call.
``` Python
# Run authentication manager
AuthManager(authMethod="env", region= "Americas")
# Run authentication manager with file method
AuthManager(authMethod="file", env_file_name=".env", region= "Americas")
# Run authentication manager with manual method
AuthManager(authMethod="manual", region="Americas", refreshToken="your_refresh_token")
```
### Hawkin Specific data
While the purpose of the package is to help with accessing data specific to your organization, it may be helpful to store some data that is specific to Hawkin and the Hawkin Dynamics system. Things like test types and test metrics will help you call your data more efficiently and better understand the values you are seeing.
* `GetTypes` - Get the test type names and IDs for all the test types in the system. The response will be a data frame containing the tests that are in the HD system.
* `GetMetrics` - Get all the metrics for each test type. The response will be a data frame containing the test canonical ID, test type name, metric ID, metric label, a metric unit of measure, and description.
### Organization Specific Data
Every organization has data specific to them. With that, these entities will have unique IDs. It is important to have these IDs available to make the most of your test calls.
* `GetAthletes()` - Get the athletes for an account. Inactive players will only be included if `inactive` = True. The response will be a data frame containing the athletes that match this query.
* `GetTeams()` - Get the team names and IDs for all the teams in the org. The response will be a data frame containing the teams that are in the organization.
* `GetGroups()` - Get the group names and IDs for all the groups in the org. The response will be a data frame containing the groups that are in the organization.
* `GetTags()` - Get the tag names, IDs, and descriptions for tags created by users in your org. The response will be a data frame.
### Get Test Data
This is what you are here for. These functions allow you to call test data most efficiently. It is encouraged that you take advantage of the `from_`, `to_`, and `sync` parameters. This will help prevent from having calls with large payloads that may timeout and fail.
#### Get Test Arguments
* `from_` = Optionally supply a time (Unix timestamp) you want the tests from. If you do not supply this
value you will receive every test. This parameter is best suited for bulk exports of historical data.
* `to_` = Optionally supply a time (Unix timestamp) you want the tests to. If you do not supply this value
you will receive every test from the beginning of time or the optionally supplied `from_`
parameter. This parameter is best suited for bulk exports of historical data
* `sync` = The result set will include updated and newly created tests, following the time constraints of `from_` and `to_`. This parameter is best suited to keep your database in sync with the Hawkin database. It cannot and should not be used to fetch your entire database. A recommended strategy would be to have a job that runs on a short interval e.g. every five minutes that sends the `lastSyncTime` that it received as the `from_` parameter with `sync=True`.
* `active` = If True, only active tests are fetched. If False, all tests including inactive ones are fetched. The default is set to True.
#### Get Test Function
* `GetTests()` - Get the tests for your account. You can specify a time frame `from_`, or `to_`, which the tests should come (or be synced). The Response will be a data frame containing the trials within the time range (if specified).
* `GetTestsAth()` - Get only tests of the specified athlete from your organization. You can specify a time frame `from_`, or `to_`, which the tests should come (or be synced). Response will be a data frame containing the trials from the athlete, within the time range (if specified).
* `GetTestsType()` - Get only tests of the specified test type from your organization. You can specify a time frame `from_`, or `to_`, which the tests should come (or be synced). Response will be a data frame containing the trials from that test type, within the time range (if specified).
* `GetTestsTeam()` - Get only tests of the specified teams from your organization. Requires a `teamId` argument, which expects a text string, list or tuple (max of 10 teams). You can specify a time frame `from_`, or `to_`, which the tests should come (or be synced). Response will be a data frame containing the trials from those teams, within the time range (if specified).
* `GetTestsGroup()` - Get only tests of the specified groups from your organization. Requires a `groupId` argument, which expects a text string, list or tuple (max of 10 groups). You can specify a time frame `from_`, or `to_`, which the tests should come (or be synced). Response will be a data frame containing the trials from those groups, within the time range (if specified).
* `GetForceTime()` - Get the force-time data for a specific test by id. This includes both left, right and combined force data at 1000hz (per millisecond). Calculated velocity, displacement, and power at each time interval will also be included.
## Examples
This is a basic example that shows a common workflow:
### Authenticate Session
``` Python
# Dependencies
import hdforce
# Run authentication manager
AuthManager(authMethod="env", region= "Americas")
```
### Get HD Data
#### Test Types
``` Python
# Test Types
types = hdforce.GetTypes()
types
```
### Organization Data
#### Get Athletes
``` Python
# Get Athletes
roster = hdforce.GetAthletes( inactive= False) # inactive is default to False
# Athlete example
roster[roster['name'] =="Lauren Green"]
```
#### Get Tags
``` Python
# Get Tags
tags = hdforce.GetTags()
# Tags example
tags[0:6]
```
### Get Tests
``` Python
# Get Tags
allTests = hdforce.GetTests()
# Filter my tests
mytests = allTests[allTests['athlete.name'] =="Lauren Green"]
# Slice some rows and columns
df = mytests.iloc[:5,:15]
df
```
Raw data
{
"_id": null,
"home_page": "https://www.hawkindynamics.com/",
"name": "hdforce",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "hawkin, force plates, sports science",
"author": "laureng-hd",
"author_email": "lauren@hawkindynamics.com",
"download_url": "https://files.pythonhosted.org/packages/72/8c/c4665d733d8f559d12c7ac21cfbf2f829868affec72a2752e1dc38e973a3/hdforce-1.1.2.tar.gz",
"platform": null,
"description": "# HDFORCE v1.1.2 <img src=\"docs/img/hdlogo_sm.png\" align=\"right\" alt=\"\" width=\"120\" />\n\n\n**Get your data from the Hawkin Dynamics API**\n\n<!-- badges: start -->\n\n[](https://github.com/HawkinDynamics/hawkinPy/actions/workflows/push-test.yml)\n\n[](https://www.repostatus.org/#active)\n[](https://www.tidyverse.org/lifecycle/#stable)\n[](https://choosealicense.com/)\n<!-- badges: end -->\n\n## How To Use The HDFORCE Package\n\nHDFORCE provides simple functionality with Hawkin Dynamics API. These functions are for use with \u2018Hawkin Dynamics Beta API\u2019 version 1.10-beta. You must be a Hawkin Dynamics user with an active integration account to utilize functions within the package.\n\n## Functions\nThis API is designed to get data out of your Hawkin Dynamics server and interact with your data more intimately. It is not designed to be accessed from client applications directly. There is a limit on the amount of data that can be returned in a single request (256 MB). As your database grows, it will be necessary to use the `from_` and `to_` parameters to limit the size of the responses. Responses that exceed the memory limit will timeout and fail. It is advised that you design your client to handle this from the beginning. A recommended pattern would be to have two methods of fetching data. A scheduled pull that uses the `from_` and `to_` parameters to constrain the returned data to only tests that have occurred since the last fetch e.g. every day or every 5 minutes. And then a pull that fetches the entire database since you began testing that is only executed when necessary. A recommended way of doing this is to generate the `from_` and `to_` parameters for each month since you started and send a request for each either in parallel or sequentially.\n\nThis package was meant to help execute requests to the Hawkin Dynamics API with a single line of code. There are 13 functions to help execute 4 primary objectives:\n\n### Authentication\nUse the Refresh Token generated by https://cloud.hawkindynamics.com/integrations to get a valid Access Token. Only the organization administrator account can generate API tokens. Use this function to initiate access to your data in the cloud. All other HDFORCE functions will depend on the values returned from this function.\n\nIn HDFORCE, we can create and manage your authentication settings with the `authManager` function. The arguments passed will be used to handle authentication for the other functions used in the program. With this function, you can control these settings:\n\n* __region__: Sets the URL prefix of your cloud site.\n* __authMethod__: Sets storage method of auth variables. One of env, file, or manual. Default to 'env'.\n* __refreshToken_name__: Provide or set the name of the refresh Token variable. Default to \"HD_REFRESH_TOKEN\".\n* __refreshToken__: Optionally provided to pass a token for authentication when authMethod=\"manual\". Else it will set the refresh token value when provided.\n* __env_file_name__: Required when authManager=\"file\". Directs storage location of variables.\n\nThe authentication manager allows the user to manage authentication with various development strategies. The 'env' method was designed to allow for simple authentication while developing in a local or contained environment, where the refresh token and variables are stored in the system environment. The 'file' method can be used for more visible and dynamic interaction with the auth variables, as the refresh token and variables are stored with a .env file. While the 'manual' method allows for the use of the package without storing sensitive data, in so the refresh token is not stored and is only used for authentication. This could be helpful in the scenario of developing a password-protected application where the token can be used as a password.\n\nIn the case of the \"file\" method, the user will need to save a .env file in the source directory. When using this method, you will also need to pass the file name to the `env_file_name` argument as a string. It's most common to use something as simple as \".env\", but you can name your file anything ending with .env.\n\nBelow is an example of what the .env file can look like. This can be used as a template, as the variable name \"HD_REFRESH_TOKEN\" is the default to what the `authManager` function will use for the `refreshToken_name`. If you want to use a different variable name, simply pass the string through the `refreshToken_name` argument, along with the token to the `refreshToken` argument. The other values for ACCESS_TOKEN, TOKEN_EXPIRATION, and CLOUD_URL are defaults within the `authManager` function and should be maintained.\n\n``` PowerShell\n# Inside your .env file\n\nHD_REFRESH_TOKEN=your_api_token # Replace With Your Refresh Token\nREGION=your_region # Replace With Your URL region\nACCESS_TOKEN= # Access token will be stored here\nTOKEN_EXPIRATION= # Token Expiration will be stored here\nCLOUD_URL= # Your region's URL here\n```\n\nWith the variables stored, we can use them with our other functions without worrying about authentication for each call.\n\n``` Python\n# Run authentication manager\nAuthManager(authMethod=\"env\", region= \"Americas\")\n\n# Run authentication manager with file method\nAuthManager(authMethod=\"file\", env_file_name=\".env\", region= \"Americas\")\n\n# Run authentication manager with manual method\nAuthManager(authMethod=\"manual\", region=\"Americas\", refreshToken=\"your_refresh_token\")\n\n```\n\n### Hawkin Specific data\nWhile the purpose of the package is to help with accessing data specific to your organization, it may be helpful to store some data that is specific to Hawkin and the Hawkin Dynamics system. Things like test types and test metrics will help you call your data more efficiently and better understand the values you are seeing.\n\n* `GetTypes` - Get the test type names and IDs for all the test types in the system. The response will be a data frame containing the tests that are in the HD system.\n* `GetMetrics` - Get all the metrics for each test type. The response will be a data frame containing the test canonical ID, test type name, metric ID, metric label, a metric unit of measure, and description.\n\n### Organization Specific Data\nEvery organization has data specific to them. With that, these entities will have unique IDs. It is important to have these IDs available to make the most of your test calls.\n\n* `GetAthletes()` - Get the athletes for an account. Inactive players will only be included if `inactive` = True. The response will be a data frame containing the athletes that match this query.\n* `GetTeams()` - Get the team names and IDs for all the teams in the org. The response will be a data frame containing the teams that are in the organization.\n* `GetGroups()` - Get the group names and IDs for all the groups in the org. The response will be a data frame containing the groups that are in the organization.\n* `GetTags()` - Get the tag names, IDs, and descriptions for tags created by users in your org. The response will be a data frame.\n\n### Get Test Data\nThis is what you are here for. These functions allow you to call test data most efficiently. It is encouraged that you take advantage of the `from_`, `to_`, and `sync` parameters. This will help prevent from having calls with large payloads that may timeout and fail.\n\n#### Get Test Arguments\n* `from_` = Optionally supply a time (Unix timestamp) you want the tests from. If you do not supply this\nvalue you will receive every test. This parameter is best suited for bulk exports of historical data.\n* `to_` = Optionally supply a time (Unix timestamp) you want the tests to. If you do not supply this value\nyou will receive every test from the beginning of time or the optionally supplied `from_`\nparameter. This parameter is best suited for bulk exports of historical data\n* `sync` = The result set will include updated and newly created tests, following the time constraints of `from_` and `to_`. This parameter is best suited to keep your database in sync with the Hawkin database. It cannot and should not be used to fetch your entire database. A recommended strategy would be to have a job that runs on a short interval e.g. every five minutes that sends the `lastSyncTime` that it received as the `from_` parameter with `sync=True`.\n* `active` = If True, only active tests are fetched. If False, all tests including inactive ones are fetched. The default is set to True.\n\n#### Get Test Function\n* `GetTests()` - Get the tests for your account. You can specify a time frame `from_`, or `to_`, which the tests should come (or be synced). The Response will be a data frame containing the trials within the time range (if specified).\n* `GetTestsAth()` - Get only tests of the specified athlete from your organization. You can specify a time frame `from_`, or `to_`, which the tests should come (or be synced). Response will be a data frame containing the trials from the athlete, within the time range (if specified).\n* `GetTestsType()` - Get only tests of the specified test type from your organization. You can specify a time frame `from_`, or `to_`, which the tests should come (or be synced). Response will be a data frame containing the trials from that test type, within the time range (if specified).\n* `GetTestsTeam()` - Get only tests of the specified teams from your organization. Requires a `teamId` argument, which expects a text string, list or tuple (max of 10 teams). You can specify a time frame `from_`, or `to_`, which the tests should come (or be synced). Response will be a data frame containing the trials from those teams, within the time range (if specified).\n* `GetTestsGroup()` - Get only tests of the specified groups from your organization. Requires a `groupId` argument, which expects a text string, list or tuple (max of 10 groups). You can specify a time frame `from_`, or `to_`, which the tests should come (or be synced). Response will be a data frame containing the trials from those groups, within the time range (if specified).\n* `GetForceTime()` - Get the force-time data for a specific test by id. This includes both left, right and combined force data at 1000hz (per millisecond). Calculated velocity, displacement, and power at each time interval will also be included.\n\n## Examples\nThis is a basic example that shows a common workflow:\n\n### Authenticate Session\n``` Python\n# Dependencies\nimport hdforce\n# Run authentication manager\nAuthManager(authMethod=\"env\", region= \"Americas\")\n```\n### Get HD Data\n#### Test Types\n``` Python\n# Test Types\ntypes = hdforce.GetTypes()\n\ntypes\n```\n\n### Organization Data\n#### Get Athletes\n``` Python\n# Get Athletes\nroster = hdforce.GetAthletes( inactive= False) # inactive is default to False\n\n# Athlete example\nroster[roster['name'] ==\"Lauren Green\"]\n```\n\n#### Get Tags\n``` Python\n# Get Tags\ntags = hdforce.GetTags()\n\n# Tags example\ntags[0:6]\n```\n\n### Get Tests\n``` Python\n# Get Tags\nallTests = hdforce.GetTests()\n# Filter my tests\nmytests = allTests[allTests['athlete.name'] ==\"Lauren Green\"]\n# Slice some rows and columns\ndf = mytests.iloc[:5,:15]\n\ndf\n```",
"bugtrack_url": null,
"license": null,
"summary": "Get your data from the Hawkin Dynamics API",
"version": "1.1.2",
"project_urls": {
"Documentation": "https://hawkindynamics.github.io/hawkinPy/",
"Homepage": "https://www.hawkindynamics.com/",
"Repository": "https://github.com/HawkinDynamics/hawkinPy"
},
"split_keywords": [
"hawkin",
" force plates",
" sports science"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "91d93b1f4f39386f14844e21e15bdc23a39f60712422c07b18c11816eb417859",
"md5": "f5737058dcf11dc775d4cdb6dba96560",
"sha256": "887851f7fef362cfb4ba679ab60491ac77836f1a589ac9718b31e468fc9b4535"
},
"downloads": -1,
"filename": "hdforce-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f5737058dcf11dc775d4cdb6dba96560",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 40317,
"upload_time": "2024-08-01T15:47:51",
"upload_time_iso_8601": "2024-08-01T15:47:51.598441Z",
"url": "https://files.pythonhosted.org/packages/91/d9/3b1f4f39386f14844e21e15bdc23a39f60712422c07b18c11816eb417859/hdforce-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "728cc4665d733d8f559d12c7ac21cfbf2f829868affec72a2752e1dc38e973a3",
"md5": "4c8f5196e44a844c59e4bb3240fccd5d",
"sha256": "b1b7c2c7ad1eefcf0a707bbb8f30b268d9996d5d57d203ad80990602ed1acbde"
},
"downloads": -1,
"filename": "hdforce-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "4c8f5196e44a844c59e4bb3240fccd5d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 23645,
"upload_time": "2024-08-01T15:47:53",
"upload_time_iso_8601": "2024-08-01T15:47:53.140729Z",
"url": "https://files.pythonhosted.org/packages/72/8c/c4665d733d8f559d12c7ac21cfbf2f829868affec72a2752e1dc38e973a3/hdforce-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-01 15:47:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "HawkinDynamics",
"github_project": "hawkinPy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hdforce"
}
JSON
