marine-tracker / docs /predict.html
narniagooooo's picture
Initial commit: marine mammal tracking dashboard and route prediction
27b6a20
Raw History Blame Contribute Delete
6.96 kB
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Python: module predict</title>
</head><body>
<table class="heading">
<tr class="heading-text decor">
<td class="title">&nbsp;<br><strong class="title">predict</strong></td>
<td class="extra"><a href=".">index</a><br><a href="file:/Users/samuelveliveli/Downloads/marine-tracker/src/predict.py">/Users/samuelveliveli/Downloads/marine-tracker/src/predict.py</a></td></tr></table>
<p><span class="code">Near-term&nbsp;movement&nbsp;projection:&nbsp;two&nbsp;honesty-first&nbsp;tiers.<br>
&nbsp;<br>
`heading`&nbsp;(default):&nbsp;estimate&nbsp;current&nbsp;bearing&nbsp;and&nbsp;speed&nbsp;from&nbsp;the&nbsp;last&nbsp;N<br>
fixes,&nbsp;project&nbsp;forward&nbsp;linearly,&nbsp;and&nbsp;grow&nbsp;an&nbsp;uncertainty&nbsp;cone&nbsp;whose&nbsp;width&nbsp;is<br>
grounded&nbsp;in&nbsp;that&nbsp;individual's&nbsp;own&nbsp;historical&nbsp;bearing/speed&nbsp;variance&nbsp;--&nbsp;not&nbsp;an<br>
arbitrary&nbsp;constant.&nbsp;This&nbsp;is&nbsp;the&nbsp;credible&nbsp;baseline.<br>
&nbsp;<br>
`markov`&nbsp;(optional&nbsp;upgrade):&nbsp;discretize&nbsp;the&nbsp;individual's&nbsp;own&nbsp;historical<br>
bearing&nbsp;changes&nbsp;into&nbsp;direction&nbsp;bins,&nbsp;build&nbsp;a&nbsp;transition&nbsp;model&nbsp;from&nbsp;its&nbsp;own<br>
track,&nbsp;and&nbsp;simulate&nbsp;a&nbsp;small&nbsp;ensemble&nbsp;of&nbsp;forward&nbsp;paths.&nbsp;The&nbsp;output&nbsp;is&nbsp;a<br>
spread&nbsp;of&nbsp;plausible&nbsp;paths,&nbsp;not&nbsp;one&nbsp;line.<br>
&nbsp;<br>
Neither&nbsp;tier&nbsp;should&nbsp;be&nbsp;read&nbsp;as&nbsp;a&nbsp;forecast&nbsp;of&nbsp;certainty.&nbsp;Both&nbsp;are&nbsp;labeled<br>
"projected&nbsp;range&nbsp;of&nbsp;motion"&nbsp;by&nbsp;the&nbsp;callers&nbsp;in&nbsp;analysis.py/app.py.</span></p>
<p>
<table class="section">
<tr class="decor pkg-content-decor heading-text">
<td class="section-title" colspan=3>&nbsp;<br><strong class="bigsection">Modules</strong></td></tr>
<tr><td class="decor pkg-content-decor"><span class="code">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></td><td>&nbsp;</td>
<td class="singlecolumn"><table><tr><td class="multicolumn"><a href="numpy.html">numpy</a><br>
</td><td class="multicolumn"><a href="pandas.html">pandas</a><br>
</td><td class="multicolumn"></td><td class="multicolumn"></td></tr></table></td></tr></table><p>
<table class="section">
<tr class="decor functions-decor heading-text">
<td class="section-title" colspan=3>&nbsp;<br><strong class="bigsection">Functions</strong></td></tr>
<tr><td class="decor functions-decor"><span class="code">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></td><td>&nbsp;</td>
<td class="singlecolumn"><dl><dt><a name="-bearing_deg"><strong>bearing_deg</strong></a>(lat1, lon1, lat2, lon2)</dt><dd><span class="code">Initial&nbsp;great-circle&nbsp;bearing&nbsp;in&nbsp;degrees&nbsp;(0=north,&nbsp;90=east)&nbsp;from&nbsp;point&nbsp;1&nbsp;to&nbsp;point&nbsp;2.</span></dd></dl>
<dl><dt><a name="-circular_mean_deg"><strong>circular_mean_deg</strong></a>(bearings)</dt><dd><span class="code">Mean&nbsp;of&nbsp;a&nbsp;list&nbsp;of&nbsp;compass&nbsp;bearings&nbsp;(degrees),&nbsp;handling&nbsp;the&nbsp;0/360&nbsp;wraparound.</span></dd></dl>
<dl><dt><a name="-circular_std_deg"><strong>circular_std_deg</strong></a>(bearings)</dt><dd><span class="code">Circular&nbsp;standard&nbsp;deviation&nbsp;of&nbsp;compass&nbsp;bearings&nbsp;(degrees),&nbsp;handling&nbsp;wraparound.</span></dd></dl>
<dl><dt><a name="-destination_point"><strong>destination_point</strong></a>(lat, lon, bearing, distance_km)</dt><dd><span class="code">Great-circle&nbsp;destination&nbsp;point&nbsp;given&nbsp;a&nbsp;start&nbsp;point,&nbsp;bearing&nbsp;(deg),&nbsp;and&nbsp;distance&nbsp;(km).</span></dd></dl>
<dl><dt><a name="-predict"><strong>predict</strong></a>(individual_df, mode='heading', **kwargs)</dt><dd><span class="code">Dispatch&nbsp;to&nbsp;predict_heading&nbsp;(default)&nbsp;or&nbsp;predict_markov.</span></dd></dl>
<dl><dt><a name="-predict_heading"><strong>predict_heading</strong></a>(individual_df, window=10, horizon_hours=24, step_hours=1)</dt><dd><span class="code">Linear&nbsp;heading/speed&nbsp;projection&nbsp;with&nbsp;a&nbsp;variance-grounded&nbsp;expanding&nbsp;uncertainty&nbsp;cone.<br>
&nbsp;<br>
Uses&nbsp;the&nbsp;last&nbsp;`window`&nbsp;segments&nbsp;to&nbsp;estimate&nbsp;current&nbsp;heading&nbsp;and&nbsp;speed,<br>
and&nbsp;the&nbsp;individual's&nbsp;*entire*&nbsp;track&nbsp;history&nbsp;to&nbsp;estimate&nbsp;bearing/speed<br>
variance&nbsp;(so&nbsp;the&nbsp;cone&nbsp;reflects&nbsp;how&nbsp;erratically&nbsp;this&nbsp;individual&nbsp;actually<br>
moves,&nbsp;not&nbsp;an&nbsp;arbitrary&nbsp;assumption).&nbsp;Returns&nbsp;a&nbsp;dict&nbsp;with:<br>
&nbsp;&nbsp;-&nbsp;centerline:&nbsp;list&nbsp;of&nbsp;(timestamp,&nbsp;lat,&nbsp;lon)&nbsp;for&nbsp;the&nbsp;projected&nbsp;path<br>
&nbsp;&nbsp;-&nbsp;cone_left&nbsp;/&nbsp;cone_right:&nbsp;matching&nbsp;boundary&nbsp;lat/lon&nbsp;lists<br>
&nbsp;&nbsp;-&nbsp;summary:&nbsp;short&nbsp;plain-language&nbsp;description<br>
&nbsp;&nbsp;-&nbsp;heading_deg,&nbsp;speed_kmh,&nbsp;bearing_std_deg,&nbsp;speed_std_deg&nbsp;(for&nbsp;transparency)</span></dd></dl>
<dl><dt><a name="-predict_markov"><strong>predict_markov</strong></a>(
individual_df,
n_bins=16,
horizon_hours=24,
step_hours=1,
n_runs=50,
random_state=None
)</dt><dd><span class="code">Sample&nbsp;an&nbsp;ensemble&nbsp;of&nbsp;forward&nbsp;paths&nbsp;from&nbsp;a&nbsp;bearing-transition&nbsp;model&nbsp;built&nbsp;on&nbsp;this&nbsp;individual's&nbsp;own&nbsp;history.<br>
&nbsp;<br>
Returns&nbsp;a&nbsp;dict&nbsp;with&nbsp;`paths`:&nbsp;a&nbsp;list&nbsp;of&nbsp;n_runs&nbsp;paths,&nbsp;each&nbsp;a&nbsp;list&nbsp;of<br>
(timestamp,&nbsp;lat,&nbsp;lon),&nbsp;plus&nbsp;a&nbsp;`summary`.&nbsp;Communicates&nbsp;uncertainty&nbsp;as&nbsp;a<br>
spread&nbsp;of&nbsp;simulated&nbsp;paths&nbsp;rather&nbsp;than&nbsp;a&nbsp;single&nbsp;predicted&nbsp;line.</span></dd></dl>
<dl><dt><a name="-track_segments"><strong>track_segments</strong></a>(individual_df)</dt><dd><span class="code">Return&nbsp;per-consecutive-fix&nbsp;bearing&nbsp;(deg)&nbsp;and&nbsp;speed&nbsp;(km/h)&nbsp;for&nbsp;one&nbsp;individual's&nbsp;sorted&nbsp;track.<br>
&nbsp;<br>
Expects&nbsp;individual_df&nbsp;sorted&nbsp;by&nbsp;timestamp&nbsp;with&nbsp;location_lat/location_long&nbsp;columns.<br>
Returns&nbsp;a&nbsp;DataFrame&nbsp;of&nbsp;len(individual_df)&nbsp;-&nbsp;1&nbsp;rows&nbsp;with&nbsp;columns&nbsp;bearing,&nbsp;speed_kmh,&nbsp;dt_hours.</span></dd></dl>
</td></tr></table><p>
<table class="section">
<tr class="decor data-decor heading-text">
<td class="section-title" colspan=3>&nbsp;<br><strong class="bigsection">Data</strong></td></tr>
<tr><td class="decor data-decor"><span class="code">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></td><td>&nbsp;</td>
<td class="singlecolumn"><strong>EARTH_RADIUS_KM</strong> = 6371.0088</td></tr></table>
</body></html>