Geographic selection of inventory/network/station

[claudiodsf]

What does this PR do?

Add geographic options to [Inventory,Network,Station].select(), following
the same syntax of Client.get_stations().

Also add documentation to "sampling_rate" parameter.

Why was it initiated? Any relevant Issues?

Sometimes datacenter provides preassembled datasets with data and metadata for all the stations in the network (ex.: http://cnt.rm.ingv.it/event/23558121 --> Download). This PR adds possibility of filtering metadata based on geographic parameters, following the same syntax of Client.get_stations().
Not covered by this PR is the possibility of selecting data in stream based on the inventory content (next time ;-)

PR Checklist

• Correct base branch selected? master for new features, maintenance_... for bug fixes
• This PR is not directly related to an existing issue (which has no PR yet).
• If the PR is making changes to documentation, docs pages can be built automatically.
  Just remove the space in the following string after the + sign: "+DOCS"
• If any network modules should be tested for the PR, add them as a comma separated list
  (e.g. clients.fdsn,clients.arclink) after the colon in the following magic string: "+TESTS:"
  (you can also add "ALL" to just simply run all tests across all modules)
• All tests still pass.
• Any new features or fixed regressions are be covered via new tests.
• Any new or changed features have are fully documented.
• Significant changes have been added to CHANGELOG.txt .

[claudiodsf]

Fixed a typo in documentation and force-pushed.

[ThomasLecocq]

would it make sense to put the location-based filtering in some generic util module to avoid the large copy/paste of identical codes ?

[megies]

• please move keep_empty to old position
• please add a changelog one-liner
• CircleCI fails are unrelated

Otherwise good to go, looks like (didn't check tests in detail).

[claudiodsf]

would it make sense to put the location-based filtering in some generic util module to avoid the large copy/paste of identical codes ?

I thought about it. Where would you put this generic code?

[ThomasLecocq]

would it make sense to put the location-based filtering in some generic util module to avoid the large copy/paste of identical codes ?

I thought about it. Where would you put this generic code?

Yeah, not easy indeed, and the way you skip the channel is indeed not so easily "generalizable"...

maybe something like this:

def _filter_object_geographically(object, min_latitude, max_latitude, ...):
    if minlatitude is not None:
        if obj.latitude is None or obj.latitude < minlatitude:
            return False
    if maxlatitude is not None:
        if obj.latitude is None or obj.latitude > maxlatitude:
            return False
    if minlongitude is not None:
        if obj.longitude is None or obj.longitude < minlongitude:
            return False
    if maxlongitude is not None:
        if obj.longitude is None or obj.longitude > maxlongitude:
            return False
    if all([l is not None for l in
           (latitude, longitude, obj.latitude, obj.longitude)]):
        distance = locations2degrees(latitude, longitude,
                                     obj.latitude, obj.longitude)
        if minradius is not None and distance < minradius:
            return False
        if maxradius is not None and distance > maxradius:
            return False
    return True

and then in your calls:

for cha in self.channels:
    if _filter_object_geographically(cha, min_latitude, max_latitude, ...):
        channels.append(cha)

and

for sta in self.stations:
    if not _filter_object_geographically(sta, min_latitude, max_latitude, ...):
        continue

[megies]

would it make sense to put the location-based filtering in some generic util module to avoid the large copy/paste of identical codes ?

avoiding code duplication is always good 👍

[claudiodsf]

would it make sense to put the location-based filtering in some generic util module to avoid the large copy/paste of identical codes ?

avoiding code duplication is always good 👍

Ok, should I put then this common code in core/inventory/util.py ?

[megies]

Ok, should I put then this common code in core/inventory/util.py ?

I guess it could be useful for events/catalog as well? Then it should go into core/util/misc.py or maybe better geodetics/base.py (the latter might create a circular import though, didnt check)

[ThomasLecocq]

actually, I think it could be in geodetics/base.py and be a public function, as long as an object exposes the latitude and longitude parameters, it could be used.

[megies]

Yes, agree. If it causes a circular import we see it in CI

[calum-chamberlain]

It might be a good idea to add a test that this works across hemispheres - e.g. in New Zealand we have stations both sides of 180W and have run into issues in the past with simple minlatitude and maxlatitude not wrapping the search around +/- 180 (GeoNet fixed this issue here).

[megies]

We had some issue with wrapping around longitude +-180° at some point, I was pretty sure, but I can't find it now..

[ThomasLecocq]

@claudiodsf while you are at it, maybe think about making the selection inclusive or not( > or >= etc.) ?

[claudiodsf]

Finally found some time to work on this. Let me know what do you think.
I'll add a CHANGELOG entry before merging 😉

[claudiodsf]

@claudiodsf while you are at it, maybe think about making the selection inclusive or not( > or >= etc.) ?

Not sure whether this is essential: geographic coordinates are never that precise to require strict equality. And that would make the code and the function interface more complex.

Edit: also equality of floating numbers makes little sense to me.

[claudiodsf]

Not sure which kind of errors the docs builds reports...

[claudiodsf]

Also, feel free to propose a better name for filter_object_geographically().
It is more a check than a filter : check that an object is within a certain geographic range.

[claudiodsf]

Possible alternative names:

object_within_geographic_bounds()
object_inside_geographic_bounds()
object_within_geographic_range()
object_inside_geographic_range()

Other ideas?

[ThomasLecocq]

inside_geobounds ? :-)

[claudiodsf]

inside_geobounds ? :-)

@megies what do you think?

[megies]

Works for me

[ThomasLecocq]

@claudiodsf please make the name change and I'll pass for another (hopefully last) review of the code.

[claudiodsf]

@claudiodsf please make the name change and I'll pass for another (hopefully last) review of the code.

@ThomasLecocq Done! Let's wait on CI tests, then please review!

[ThomasLecocq]

small stuff, nothing major

[megies]

Made some final changes, will merge when CI is green, CC @claudiodsf

[claudiodsf]

@megies @ThomasLecocq Thanks for taking care of this: I have been sick and unable to work during the last few days.