##########################################################################################

       GPXIN-33: Create Stats for routes

##########################################################################################


Issue Type: New Feature 
-----------------------------------------------------------------------------------------

Issue Information
====================

Priority: Major					Status:      Closed
Resolution:  Done (2017-07-04 11:59:33)
Project: PHP GPXIngest (GPXIN)


Reported By: btasker					
Assigned To: btasker



Targeted for fix in version: 
	- 1.03


Time Estimate: 0 minutes
Time Logged:   85 minutes


-----------------------------------------------------------------------------------------

Issue Description
==================

Stats are currently only generated based upon the tracks. Most of them won't actually
apply to a route (as there won't be an indication of speed etc) however stats like bounds
may have some use.

This issue is to add a new routes child to the stats object and then populate it with the
relevant entries

-----------------------------------------------------------------------------------------

Activity
==========

	
-----------------------------------------------------------------------------------------
2017-07-04 09:37:30              git
-----------------------------------------------------------------------------------------


-- BEGIN QUOTE --


Repo: PHP-GPX-Ingest
Commit: f266d275f16bd3973e670671a91c3d81a2f1782a
Author: B Tasker <github@<Domain Hidden>>

Date: Tue Jul 04 09:36:27 2017 +0100
Commit Message: GPXIN-33 Create route related general stats object.

We don't currently populate these statistics, just making them available ready to do so.



Modified (-)(+)
-------
src/GPXIngest/GPXIngest.php



-- END QUOTE --

*Webhook User-Agent*


-- BEGIN SNIPPET --

GitHub-Hookshot/18889e1
 -- END SNIPPET --

https://github.com/bentasker/PHP-GPX-Ingest/commit/f266d275f16bd3973e670671a91c3d81a2f1782a


	
-----------------------------------------------------------------------------------------
2017-07-04 09:57:30              git
-----------------------------------------------------------------------------------------


-- BEGIN QUOTE --


Repo: PHP-GPX-Ingest
Commit: caf629990da9d34fcbe6b52acba79b6b5906e3a5
Author: B Tasker <github@<Domain Hidden>>

Date: Tue Jul 04 09:55:05 2017 +0100
Commit Message: GPXIN-33 Populate route stats

Had to remove the tidying done in the previous commit, as PHP was linking to two
properties (even when created with clone?) so if you updated routestats->bounds->lat with
a value it'd also show in the main stats

Will take a different approach to tidying up creating the various bounds objects shortly



Modified (-)(+)
-------
src/GPXIngest/GPXIngest.php



-- END QUOTE --

*Webhook User-Agent*


-- BEGIN SNIPPET --

GitHub-Hookshot/18889e1
 -- END SNIPPET --

https://github.com/bentasker/PHP-GPX-Ingest/commit/caf629990da9d34fcbe6b52acba79b6b5906e3a5


	
-----------------------------------------------------------------------------------------
2017-07-04 10:11:30              git
-----------------------------------------------------------------------------------------


-- BEGIN QUOTE --


Repo: PHP-GPX-Ingest
Commit: 59f877ed2d56aed72424bb8ae9c1693472ed26e9
Author: B Tasker <github@<Domain Hidden>>

Date: Tue Jul 04 10:09:43 2017 +0100
Commit Message: GPXIN-33 Move insantiation of Bounds object to private method

Avoiding duplication as we were otherwise creating duplicate objects in multiple places.
Can't see that we'd need to add an attribute, but it's now easier to do if the need
arises



Modified (-)(+)
-------
src/GPXIngest/GPXIngest.php



-- END QUOTE --

*Webhook User-Agent*


-- BEGIN SNIPPET --

GitHub-Hookshot/18889e1
 -- END SNIPPET --

https://github.com/bentasker/PHP-GPX-Ingest/commit/59f877ed2d56aed72424bb8ae9c1693472ed26e9


	
-----------------------------------------------------------------------------------------
2017-07-04 10:14:25              btasker
-----------------------------------------------------------------------------------------

Although the usual use for route points doesn't provide the need for many stats, looking
at the GPX schema documentation, the type does allow for various bits that we support in
other areas:


-- BEGIN SNIPPET --

<...
lat="latitudeType [1] ?"
lon="longitudeType [1] ?"> 
<ele> xsd:decimal </ele> [0..1] ?
<time> xsd:dateTime </time> [0..1] ?
<magvar> degreesType </magvar> [0..1] ?
<geoidheight> xsd:decimal </geoidheight> [0..1] ?
<name> xsd:string </name> [0..1] ?
<cmt> xsd:string </cmt> [0..1] ?
<desc> xsd:string </desc> [0..1] ?
<src> xsd:string </src> [0..1] ?
<link> linkType </link> [0..*] ?
<sym> xsd:string </sym> [0..1] ?
<type> xsd:string </type> [0..1] ?
<fix> fixType </fix> [0..1] ?
<sat> xsd:nonNegativeInteger </sat> [0..1] ?
<hdop> xsd:decimal </hdop> [0..1] ?
<vdop> xsd:decimal </vdop> [0..1] ?
<pdop> xsd:decimal </pdop> [0..1] ?
<ageofdgpsdata> xsd:decimal </ageofdgpsdata> [0..1] ?
<dgpsid> dgpsStationType </dgpsid> [0..1] ?
<extensions> extensionsType </extensions> [0..1] ?
</...>

 -- END SNIPPET --

We set each of these (assuming they're present), so might want to consider whether any of
them are of any use in amongst the stats.

I can see a potential use for having bounds on elevation (eles) for example.
	
-----------------------------------------------------------------------------------------
2017-07-04 10:30:04              
-----------------------------------------------------------------------------------------

btasker changed timespent from '0 minutes' to '25 minutes'
	
-----------------------------------------------------------------------------------------
2017-07-04 11:09:30              git
-----------------------------------------------------------------------------------------


-- BEGIN QUOTE --


Repo: PHP-GPX-Ingest
Commit: 189293cfa51ad53ef76d1db86b48043dfe4ae912
Author: B Tasker <github@<Domain Hidden>>

Date: Tue Jul 04 11:08:05 2017 +0100
Commit Message: GPXIN-33 Create elevation stats for routes.

Generates max/min bounds for elevations defined within a route. Elevation can be
suppressed by suppressing type 'wptele'



Added (+)
-------
src/GPXIngest/.GPXIngest.php.kate-swp


Modified (-)(+)
-------
src/GPXIngest/GPXIngest.php



-- END QUOTE --

*Webhook User-Agent*


-- BEGIN SNIPPET --

GitHub-Hookshot/18889e1
 -- END SNIPPET --

https://github.com/bentasker/PHP-GPX-Ingest/commit/189293cfa51ad53ef76d1db86b48043dfe4ae912


	
-----------------------------------------------------------------------------------------
2017-07-04 11:11:30              git
-----------------------------------------------------------------------------------------


-- BEGIN QUOTE --


Repo: PHP-GPX-Ingest
Commit: ff6cb6c22d3080d5ce965f9d1c8d79e6659d5dd3
Author: B Tasker <github@<Domain Hidden>>

Date: Tue Jul 04 11:09:53 2017 +0100
Commit Message: GPXIN-33 Add ability to unsuppress both wptlocation and wptele



Modified (-)(+)
-------
src/GPXIngest/GPXIngest.php



-- END QUOTE --

*Webhook User-Agent*


-- BEGIN SNIPPET --

GitHub-Hookshot/18889e1
 -- END SNIPPET --

https://github.com/bentasker/PHP-GPX-Ingest/commit/ff6cb6c22d3080d5ce965f9d1c8d79e6659d5dd3


	
-----------------------------------------------------------------------------------------
2017-07-04 11:15:24              btasker
-----------------------------------------------------------------------------------------

OK, so we now have the following within the stats object

-- BEGIN SNIPPET --

        "routestats": {
            "bounds": {
                "Ele": {
                    "max": "60",
                    "min": "-15"
                },
                "Lat": {
                    "max": "39.68865",
                    "min": "39.6856861"
                },
                "Lon": {
                    "max": "-105.50693",
                    "min": "-105.5073323"
                }
            }
        },

 -- END SNIPPET --

But, because "ele" has been added to the bounds object, it now also shows for tracks, so
need to make sure that's either populated or unset (I'd prefer the former) too.
	
-----------------------------------------------------------------------------------------
2017-07-04 11:16:08              
-----------------------------------------------------------------------------------------

btasker changed timespent from '25 minutes' to '40 minutes'
	
-----------------------------------------------------------------------------------------
2017-07-04 11:27:03              btasker
-----------------------------------------------------------------------------------------

Actually, looking at it some more, this change is inconsistent with how the track stats
are built.

Within the track stats, "elevation" is a standalone attribute:

-- BEGIN SNIPPET --

        "elevation": {
            "avgChange": -0.02,
            "max": "89",
            "min": "25"
        },

 -- END SNIPPET --

Although I think it probably makes more sense in bounds, that's been the structure for
quite some time, so it'd be better to replicate it and keep things consistent between the
two objects. 

Will look at shuffling things around.


	
-----------------------------------------------------------------------------------------
2017-07-04 11:32:58              btasker
-----------------------------------------------------------------------------------------

The new structure is now

-- BEGIN SNIPPET --

        "routestats": {
            "bounds": {
                "Lat": {
                    "max": "39.68865",
                    "min": "39.6856861"
                },
                "Lon": {
                    "max": "-105.50693",
                    "min": "-105.5073323"
                }
            },
            "elevation": {
                "max": "60",
                "min": "-15"
            }
        },

 -- END SNIPPET --

Probably worth calculating and adding avgChange as well
	
-----------------------------------------------------------------------------------------
2017-07-04 11:33:30              git
-----------------------------------------------------------------------------------------


-- BEGIN QUOTE --


Repo: PHP-GPX-Ingest
Commit: c1a4c77a218f6bbeb0669081030c207e1e684c64
Author: B Tasker <github@<Domain Hidden>>

Date: Tue Jul 04 11:31:17 2017 +0100
Commit Message: GPXIN-33 Elevation should be it's own attribute in route stats

Changed to keep it consistent with the structure of the track related stats object



Modified (-)(+)
-------
src/GPXIngest/GPXIngest.php



-- END QUOTE --

*Webhook User-Agent*


-- BEGIN SNIPPET --

GitHub-Hookshot/18889e1
 -- END SNIPPET --

https://github.com/bentasker/PHP-GPX-Ingest/commit/c1a4c77a218f6bbeb0669081030c207e1e684c64


	
-----------------------------------------------------------------------------------------
2017-07-04 11:45:30              git
-----------------------------------------------------------------------------------------


-- BEGIN QUOTE --


Repo: PHP-GPX-Ingest
Commit: 24415d1a2ee2216645304ab5e37c3daec01c5b78
Author: B Tasker <github@<Domain Hidden>>

Date: Tue Jul 04 11:43:55 2017 +0100
Commit Message: GPXIN-33 Add AvgChange to route elevation stats. Have also added maxChange
and minChange

Will need to add maxChange and minChange to the track stats to help keep things
consistent, but I figure they could be helpful if the route describes a marathon or cycle
route so you can gauge how knackering it's likely to be



Modified (-)(+)
-------
src/GPXIngest/GPXIngest.php



-- END QUOTE --

*Webhook User-Agent*


-- BEGIN SNIPPET --

GitHub-Hookshot/18889e1
 -- END SNIPPET --

https://github.com/bentasker/PHP-GPX-Ingest/commit/24415d1a2ee2216645304ab5e37c3daec01c5b78


	
-----------------------------------------------------------------------------------------
2017-07-04 11:57:34              btasker
-----------------------------------------------------------------------------------------

OK, the elevation attribute is now structured the same between both routes and tracks

Track:

-- BEGIN SNIPPET --

        "elevation": {
            "avgChange": -0.02,
            "max": "89",
            "maxChange": 20,
            "min": "25",
            "minChange": -28
        },

 -- END SNIPPET --

Route:

-- BEGIN SNIPPET --

            "elevation": {
                "avgChange": -2.29,
                "max": "60",
                "maxChange": 50,
                "min": "-15",
                "minChange": -40
            }

 -- END SNIPPET --

At the track level, elevation might have an additional attribute "gain" but that's an
unfinished experimental feature (from https://github.com/bentasker/PHP-GPX-Ingest/pull/18
) so I'm ignoring it for now, especially as it's only added at the track level.
	
-----------------------------------------------------------------------------------------
2017-07-04 11:58:29              
-----------------------------------------------------------------------------------------

btasker changed timespent from '40 minutes' to '85 minutes'
	
-----------------------------------------------------------------------------------------
2017-07-04 11:59:24              btasker
-----------------------------------------------------------------------------------------

I can't think of any other stats that will actually be of real-world interest for routes,
so I'm going to mark this issue as complete. Can always create a new issue for any new
stats that need to be added.
	
-----------------------------------------------------------------------------------------
2017-07-04 11:59:34              
-----------------------------------------------------------------------------------------

btasker changed status from 'Open' to 'Resolved'
	
-----------------------------------------------------------------------------------------
2017-07-04 11:59:34              
-----------------------------------------------------------------------------------------

btasker added 'Done' to resolution
	
-----------------------------------------------------------------------------------------
2017-07-04 11:59:37              
-----------------------------------------------------------------------------------------

btasker changed status from 'Resolved' to 'Closed'
	
-----------------------------------------------------------------------------------------
2017-07-04 14:27:27              btasker
-----------------------------------------------------------------------------------------

Added to the docs here -
https://www.bentasker.co.uk/documentation/development-programming/222-php-gpx-ingest#getroutestats


-----------------------------------------------------------------------------------------

Worklog
========

 
-----------------------------------------------------------------------------------------
2017-07-04 10:30:04              btasker

25 minutes
-----------------------------------------------------------------------------------------

Implementing and testing
 
-----------------------------------------------------------------------------------------
2017-07-04 11:16:08              btasker

15 minutes
-----------------------------------------------------------------------------------------

Adding ele stats and testing
 
-----------------------------------------------------------------------------------------
2017-07-04 11:58:29              btasker

45 minutes
-----------------------------------------------------------------------------------------

Restructuring stats, tweaking elevation processing etc