{"id":17535774,"url":"https://github.com/steffilazerte/cavityuse","last_synced_at":"2025-04-23T19:49:17.548Z","repository":{"id":44053513,"uuid":"143923939","full_name":"steffilazerte/cavityuse","owner":"steffilazerte","description":"An R package for detecting cavity use from geolocator data","archived":false,"fork":false,"pushed_at":"2022-08-04T17:05:19.000Z","size":1887,"stargazers_count":6,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-30T03:01:46.724Z","etag":null,"topics":["animal-behaviour","animals","biology","data","geolocator","r"],"latest_commit_sha":null,"homepage":"https://steffilazerte.github.io/cavityuse","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/steffilazerte.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-08-07T20:32:12.000Z","updated_at":"2022-08-04T16:40:36.000Z","dependencies_parsed_at":"2022-08-27T07:02:11.627Z","dependency_job_id":null,"html_url":"https://github.com/steffilazerte/cavityuse","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steffilazerte%2Fcavityuse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steffilazerte%2Fcavityuse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steffilazerte%2Fcavityuse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steffilazerte%2Fcavityuse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/steffilazerte","download_url":"https://codeload.github.com/steffilazerte/cavityuse/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250504085,"owners_count":21441527,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["animal-behaviour","animals","biology","data","geolocator","r"],"created_at":"2024-10-20T19:24:09.669Z","updated_at":"2025-04-23T19:49:17.530Z","avatar_url":"https://github.com/steffilazerte.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\u003c!-- badges: start --\u003e\n[![R-CMD-check](https://github.com/steffilazerte/cavityuse/workflows/R-CMD-check/badge.svg)](https://github.com/steffilazerte/cavityuse/actions)\n[![codecov](https://codecov.io/gh/steffilazerte/cavityuse/branch/master/graph/badge.svg)](https://codecov.io/gh/steffilazerte/cavityuse)\n\u003c!-- badges: end --\u003e\n\n# cavityuse  \n_Detecting Cavity Use From Geolocator Data_  \n\n`cavityuse` is an R package for calculating patterns of cavity use from geolocator light data. Patterns of light and dark are used to identify daytime usage, while patterns of sunrise/sunset are used to identify nighttime usage.\n\n\u003e While `cavityuse` is ready to be experimented with, it's still in early development and should be considered **experimental**. Please give me a hand by letting me know of any problems you have (missing functionality, difficult to use, bugs, etc.)\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(fig.path = \"man/figures/\", out.width = \"100%\", \n                      fig.asp = 0.5, fig.width = 10)\n```\n\n## Installing `cavityuse`\n\nYou can install `cavityuse` directly from my R-Universe:\n\n```{r, eval = FALSE}\ninstall.packages(\"cavityuse\", \n                 repos = c(\"https://steffilazerte.r-universe.dev\", \n                           \"https://cloud.r-project.org\"))\n```\n\n## Getting started\n\nLoad the package\n```{r}\nlibrary(cavityuse)\n```\n\nWe'll get started with the built in example file `calib` which clearly shows\nsunrise/sunset events\n\nLet's take a look at the patterns in the raw data:\n```{r}\ncavity_plot(calib)\n```\n\nLook for any sunrise/sunset events in your geolocator data\n```{r}\ns \u003c- sun_detect(calib)\ns\n```\n\nLet's see what these look like\n```{r}\ncavity_plot(data = calib, sun = s, days = 1)\n```\n\nNow let's move on to the `flicker` data set:\n\n```{r}\ncavity_plot(flicker)\ns \u003c- sun_detect(flicker) # Nothing detected\ne \u003c- cavity_detect(flicker, sun = s)\ne\n```\n\nLet's see how these assignments match the patterns we see\n\n```{r}\ncavity_plot(data = flicker, cavity = e)\n```\n\n\n## With your own data\n\nYou data must be in a data frame with the columns called `time` and `light`.\n\n- `time` must be in a `date/time` format\n- `light` must be a number, representing light levels in lux (low = dark, high = light)\n\nFor example:\n\n```{r, echo = FALSE}\ndplyr::select(flicker, time, light)\n```\n\nConsider using the [`lubridate`](https://lubridate.tidyverse.org/) package to format your times\n\n### Timezones  \n\nMost geolocator data is in the UTC timezone, and although previous versions of cavityuse recommended converting your data to your the timezone of your location (non-daylight savings), I now recommend \nkeeping it in UTC. cavityuse will apply a timezone offset to your data according to the location.\n\nThis means that the time output by cavityuse will be in UTC according to R, however it will actually have had an offset applied (noted in the new column `tz_offset`). This just makes things simpler.\n \n### Coordinates\n`cavityuse` functions require coordinates in order to more efficiently detect sunrise/sunset times, but also to estimate sunrise/sunset when they are not detected in the data. \n\nYou can supply coordinates in one of two ways.\n\n- You can have `lon` and `lat` columns, indicating the decimal coordinates for your location either in your data\n```{r, echo = FALSE}\ndplyr::select(flicker, time, light, lon, lat)\n```\n\n- You can have a separate variable that you supply to each function (order matters, and must be `lon`, `lat`):\n```{r, eval = FALSE}\nsun_times(data, loc = c(-120.3408, 50.67611))\n```\n\n\n## Limitations\n\nRight now, `cavityuse` is limited to the follow scenarios:\n\n- **No big changes in location (i.e. No migration)**\n  Changes in location can interfere with how `cavityuse` assigns activity based on sunrise/sunset times which are inferred from lon/lat (this may change in the future). Minor migratory changes can be accommodated, and larger ones can be somewhat handled by splitting the data by location (different lat/lons) and applying `cavity_detect()` to each set of locations. But this isn't perfect.\n- **No extreme latitudes**\n  Because of the way `cavityuse` detects sunrise and sunset, extremely latitudes may result in unpredicatable behaviour (this should hopefully be fixed in the future)\n- **Animals which use cavities at night, must normally enter their cavity _before_ it gets dark and exit _after_ it gets light**\n  With out the ability to detect sunrise/sunset it is impossible to determine cavityuse at night\n\n\n\nPlease note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). By participating in this project you agree to abide by its terms.\n\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteffilazerte%2Fcavityuse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsteffilazerte%2Fcavityuse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteffilazerte%2Fcavityuse/lists"}