{"id":16707120,"url":"https://github.com/expandingman/timeseriessegmentation","last_synced_at":"2025-12-29T10:05:52.241Z","repository":{"id":82272142,"uuid":"78784453","full_name":"ExpandingMan/TimeSeriesSegmentation","owner":"ExpandingMan","description":"Segmentation algorithms for time series data.  Compatible with the JuliaStats/TimeSeries.jl package.","archived":false,"fork":false,"pushed_at":"2020-02-08T17:19:46.000Z","size":598,"stargazers_count":6,"open_issues_count":1,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-21T09:48:20.575Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Julia","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ExpandingMan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-12T20:32:32.000Z","updated_at":"2024-01-30T15:49:07.000Z","dependencies_parsed_at":null,"dependency_job_id":"9143d32a-8cab-4220-892c-5ccf88701c4d","html_url":"https://github.com/ExpandingMan/TimeSeriesSegmentation","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExpandingMan%2FTimeSeriesSegmentation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExpandingMan%2FTimeSeriesSegmentation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExpandingMan%2FTimeSeriesSegmentation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ExpandingMan%2FTimeSeriesSegmentation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ExpandingMan","download_url":"https://codeload.github.com/ExpandingMan/TimeSeriesSegmentation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243606960,"owners_count":20318314,"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":[],"created_at":"2024-10-12T19:37:39.213Z","updated_at":"2025-12-29T10:05:52.155Z","avatar_url":"https://github.com/ExpandingMan.png","language":"Julia","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TimeSeriesSegmentation\nThis package implements some basic time series segmentation algorithms.  It is compatible\nwith the \"TimeSeries.jl\" package.  Results are provided using the `SegmentSeries` type, \nwhich is useful for easily dealing with discontinuous functions and easily computing\nproperties of the segments themselves.\n\nA glance at the source code of this package may reveal it to be unexpectedly complicated.\nThis is because there are three things that it deals with which are rather a huge headache:\n* Time series with non-regular intervals.\n* The functions resulting from the segmentation are in general discontinuous.\n* Conversion to and from `DateTime`.\n\nSo far I haven't gone crazy trying to make this package computationally efficient, \nbut for the most part it seems pretty performant.\n\n\n## Using the Segmentation Algorithms\nThe following algorithms are currently available\n* `slidingwindow_interpolation`, `slidingwindow_regression`\n* `topdown_interpolation`, `topdown_regression`\n* `bottomup_interpolation`, `bottomup_regression`\n* `bottomup_stocahstic_interpolation`, `bottomup_stochastic_regression`\n\n`_interpolation` or `_regression` denotes whether the segments generated will be determined\nby linearly interpolating between endpoints, or performing a least-squares linear regression.\nThe latter is obviously more accurate (roughly speaking) but in general results in \npiecewise continuous functions.\n\nTo invoke one of these algorithms on a `TimeArray` (see \n[TimeSeries.jl](https://github.com/JuliaStats/TimeSeries.jl)) one can simply do, for example\n```julia\nss = bottomup_regression(ts, Day, max_error, loss_metric=L₁)\n```\nHere `ts` is a `TimeArray` and `ss` is the resulting `SegmentSeries` object.  The second \nargument (in this case `Day`) is the period of time (a subtype of `Dates.Period`) which\nis to be considered a unit of `1.0`.  For example, the sequence `[Date(3147, 1, 1),\nDate(3147, 1, 2), Date(3147, 1, 3)]` converted to floats using `Hour` would be\n`[0.0, 24.0, 48.0]`.  The parameter `max_error` determines the maximum error of a segment\nproduced by the algorithm.  The `loss_metric` parameter is the function which should be\nused to determine the error. `L₁, L₂, LInfty` are exported by this package.\n\n### The Stochastic Bottom-Up Algorithm\nThe `bottomup_stochastic` algorithm is similar to the bottomup algorithm except instead\nor merging the segments that most reduce the total error on each iteration, it merges\na random pair of segments the merger of which produces a segment with error less than\nthe maximum error.  This can be useful for producing multiple different segmentations from\nthe same series with the total error of the segmentation approximation still being controlled.\nThis may be useful in cases where the segmentation is being used as a training dataset for\nmachine learning.  Note that the `bottomup_stochastic` algorithm uses the Julia `rand`\nfunction so its seed can be set using `TimeSeriesSegmentation.srand`.\n\n\n## `SegmentSeries`\nThe `SegmentSeries` type contains a vector of `LinearSegment` objects which simply\nspecify the end-points of each segment.  Note that a `SegmentSeries` in general describes\nonly a piecewise-continuous function, so it is not always trivial to convert them into\nanother time series.  Several useful functions are available when dealing with \n`SegmentSeries`.  If the series was produced by one of the segmentation algorithms called\non a `TimeArray`, the `SegmentSeries` can be easily converted back into a `TimeArray` using\n```julia\ntsPrime = TimeArray(ss)\n```\nIf the `SegmentSeries` is discontinuous, the interpolation between points in the resulting\n`TimeArray` will be a continuous approximation (i.e. discontinuities will be replaced with\nline segments with an appropriately large slope).  One can also do\n```julia\nslope(ss)  # this returns a `Vector{Float64}` with the slope of each segment\nintercept(ss) # this returns a `Vector{Float64}` with the y-intercept of each segment\ngetfunction(ss) # this returns the segment series as a piecewise-continuous Julia function\n```\n\n\n## Example\nTo run a complete example, one can include `\"test/sunspotdata/import.jl` and use the\nfunction `get_sunspot_daily_ts(:SpotsTotal)` (currently the segmentation algorithms only\nsupport 1-dimensional time series).  What follows is a complete example of segmenting\nthe sunspots data\n```julia\nts = get_sunspot_daily_ts(:SpotsTotal)\nts = from(ts, Date(1974, 1, 1)) # no missing data beyond this point\n\nss = bottomup_regression(ts, Day, 1.0e6)\n\nts_segmented = TimeArray(ss) # this can now be plotted along with ts\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexpandingman%2Ftimeseriessegmentation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexpandingman%2Ftimeseriessegmentation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexpandingman%2Ftimeseriessegmentation/lists"}