matplotlib-map-utils 2.0.1__tar.gz → 2.1.0__tar.gz

{matplotlib_map_utils-2.0.1 → matplotlib_map_utils-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: matplotlib-map-utils
-Version: 2.0.1
+Version: 2.1.0
 Summary: A suite of tools for creating maps in matplotlib
 Author-email: David Moss <davidmoss1221@gmail.com>
 Project-URL: Homepage, https://github.com/moss-xyz/matplotlib-map-utils/
@@ -8,12 +8,13 @@ Project-URL: Bug Tracker, https://github.com/moss-xyz/matplotlib-map-utils/issue
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: GNU General Public License (GPL)
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: matplotlib>=3.9.0
 Requires-Dist: cartopy>=0.23.0
 Requires-Dist: great-circle-calculator>=1.3.1
+Dynamic: license-file
 
 # matplotlib-map-utils
  
@@ -29,12 +30,14 @@ Requires-Dist: great-circle-calculator>=1.3.1
 
 `matplotlib_map_utils` is intended to be a package that provides various functions and objects that assist with the the creation of maps using [`matplotlib`](https://matplotlib.org/stable/).
 
-As of `v2.x` (the current version), this includes two tools: 
+As of `v2.x` (the current version), this includes two tools and one utility: 
 
 * `north_arrow.py`, which generates a high quality, context-aware north arrow for a given plot. 
 
 * `scale_bar.py`, which generates a high quality, context-aware scale bar to a given plot. 
 
+* `usa.py`, which contains a class that helps filter for states and territories within the USA based on given characteristics.
+
 Future releases (if the project is continued) might provide a similar tool inset maps, or other functions that I have created myself that give more control in the formatting of maps.
 
 ---
@@ -49,11 +52,11 @@ pip install matplotlib-map-utils
 
 The requirements for this package are:
 
-* `python >= 3.9.0` (due to the dictionary-concatenation method utilized)
+* `python >= 3.10` (due to the use of the pipe operator to concatenate dictionaries and types)
 
-* `matplotlib >= 3.9.0` (might work with lower versions but not guaranteed)
+* `matplotlib >= 3.9` (might work with lower versions but not guaranteed)
 
-* `cartopy >= 0.23.0` (due to earlier bug with calling `copy()` on `CRS` objects)
+* `cartopy >= 0.23` (due to earlier bug with calling `copy()` on `CRS` objects)
 
 ---
 
@@ -78,6 +81,10 @@ package_name/
 │   ├── __init__.py
 │   ├── north_arrow.py
 │   └── scale_bar.py
+├── utils/
+│   ├── __init__.py
+│   ├── usa.py
+│   └── usa.json
 ```
 
 Where:
@@ -230,6 +237,38 @@ Refer to `docs\howto_scale_bar` for details on how to customize each facet of th
 
 ---
 
+### Utilities
+
+<details>
+<summary><i>Expand instructions</i></summary>
+
+#### Quick Start
+
+Importing the bundled utility functions and classes can be done like so:
+
+```py
+from matplotlib_map_utils.utils import USA
+```
+
+As of `v2.1.0`, there is only one utility class available: `USA`, an object to help quickly filter for subsets of US states and territories. This utility class is still in beta, and might change.
+
+An example:
+
+```python
+# Loading the object
+usa = USA()
+# Getting a list FIPS codes for US States
+usa.filter(states=True, to_return="fips")
+# Getting a list of State Names for states in the South and Midwest regions
+usa.filter(region=["South","Midtwest"], to_return="name")
+```
+
+Refer to `docs\howto_utils` for details on how to use this class, including with `pandas.apply()`.
+
+</details>
+
+---
+
 ### Development Notes
 
 #### Inspiration and Thanks
@@ -246,6 +285,10 @@ Two more projects assisted with the creation of this script:
 
 - `v2.0.1`: Fixed a bug in the `dual_bars()` function that prevented empty dictionaries to be passed. Also added a warning when auto-calculated bar widths appear to be exceeding the dimension of the axis (usually occurs when the axis is <2 kilometeres or miles long, depending on the units selected).
 
+- `v2.0.2`: Changed f-string formatting to alternate double and single quotes, so as to maintain compatibility with versions of Python before 3.12 (see [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/3)). However, this did reveal that another aspect of the code, namely concatenating `type` in function arguments, requires 3.10, and so the minimum python version was incremented.
+
+- `v2.1.0`: Added a utility class, `USA`, for filtering subsets of US states and territories based on FIPS code, name, abbreviation, region, division, and more. This is considered a beta release, and might be subject to change later on.
+
 #### Future Roadmap
 
 With the release of `v2.x`, and the addition of **Scale Bar** tools, this project has achieved the two main objectives that I set out to.
@@ -268,7 +311,15 @@ If I continue development of this project, I will be looking to add or fix the f
 
   * Create more styles for the bar, potentiallly including dual boxes and a sawtooth bar
 
-If that goes well, `v3` can then either create a tool for generating inset maps (which `matplotlib` has *some* support for), or the various functions that I have created in the past that assist with formatting a map "properly", such as centering on a given object and coverting FIPS codes.
+* **Utils:**
+
+  * (USA): Stronger fuzzy search mechanics, so that it will accept flexible inputs for FIPS/abbr/name
+
+  * (USA): More integrated class types to allow for a more fully-formed object model (USA being a `Country`, with subclasses related to `State` and `Territory` that have their own classes of attributes, etc.)
+
+  * (USA): Stronger typing options, so you don't have to recall which `region` or `division` types are available, etc.
+
+If that goes well, `v3` can then either create a tool for generating inset maps (which `matplotlib` has *some* support for), or the various functions that I have created in the past that assist with formatting a map "properly", such as centering on a given object.
 
 I am also open to ideas for other extensions to create!
 

{matplotlib_map_utils-2.0.1 → matplotlib_map_utils-2.1.0}/README.md

@@ -12,12 +12,14 @@
 
 `matplotlib_map_utils` is intended to be a package that provides various functions and objects that assist with the the creation of maps using [`matplotlib`](https://matplotlib.org/stable/).
 
-As of `v2.x` (the current version), this includes two tools: 
+As of `v2.x` (the current version), this includes two tools and one utility: 
 
 * `north_arrow.py`, which generates a high quality, context-aware north arrow for a given plot. 
 
 * `scale_bar.py`, which generates a high quality, context-aware scale bar to a given plot. 
 
+* `usa.py`, which contains a class that helps filter for states and territories within the USA based on given characteristics.
+
 Future releases (if the project is continued) might provide a similar tool inset maps, or other functions that I have created myself that give more control in the formatting of maps.
 
 ---
@@ -32,11 +34,11 @@ pip install matplotlib-map-utils
 
 The requirements for this package are:
 
-* `python >= 3.9.0` (due to the dictionary-concatenation method utilized)
+* `python >= 3.10` (due to the use of the pipe operator to concatenate dictionaries and types)
 
-* `matplotlib >= 3.9.0` (might work with lower versions but not guaranteed)
+* `matplotlib >= 3.9` (might work with lower versions but not guaranteed)
 
-* `cartopy >= 0.23.0` (due to earlier bug with calling `copy()` on `CRS` objects)
+* `cartopy >= 0.23` (due to earlier bug with calling `copy()` on `CRS` objects)
 
 ---
 
@@ -61,6 +63,10 @@ package_name/
 │   ├── __init__.py
 │   ├── north_arrow.py
 │   └── scale_bar.py
+├── utils/
+│   ├── __init__.py
+│   ├── usa.py
+│   └── usa.json
 ```
 
 Where:
@@ -213,6 +219,38 @@ Refer to `docs\howto_scale_bar` for details on how to customize each facet of th
 
 ---
 
+### Utilities
+
+<details>
+<summary><i>Expand instructions</i></summary>
+
+#### Quick Start
+
+Importing the bundled utility functions and classes can be done like so:
+
+```py
+from matplotlib_map_utils.utils import USA
+```
+
+As of `v2.1.0`, there is only one utility class available: `USA`, an object to help quickly filter for subsets of US states and territories. This utility class is still in beta, and might change.
+
+An example:
+
+```python
+# Loading the object
+usa = USA()
+# Getting a list FIPS codes for US States
+usa.filter(states=True, to_return="fips")
+# Getting a list of State Names for states in the South and Midwest regions
+usa.filter(region=["South","Midtwest"], to_return="name")
+```
+
+Refer to `docs\howto_utils` for details on how to use this class, including with `pandas.apply()`.
+
+</details>
+
+---
+
 ### Development Notes
 
 #### Inspiration and Thanks
@@ -229,6 +267,10 @@ Two more projects assisted with the creation of this script:
 
 - `v2.0.1`: Fixed a bug in the `dual_bars()` function that prevented empty dictionaries to be passed. Also added a warning when auto-calculated bar widths appear to be exceeding the dimension of the axis (usually occurs when the axis is <2 kilometeres or miles long, depending on the units selected).
 
+- `v2.0.2`: Changed f-string formatting to alternate double and single quotes, so as to maintain compatibility with versions of Python before 3.12 (see [here](https://github.com/moss-xyz/matplotlib-map-utils/issues/3)). However, this did reveal that another aspect of the code, namely concatenating `type` in function arguments, requires 3.10, and so the minimum python version was incremented.
+
+- `v2.1.0`: Added a utility class, `USA`, for filtering subsets of US states and territories based on FIPS code, name, abbreviation, region, division, and more. This is considered a beta release, and might be subject to change later on.
+
 #### Future Roadmap
 
 With the release of `v2.x`, and the addition of **Scale Bar** tools, this project has achieved the two main objectives that I set out to.
@@ -251,7 +293,15 @@ If I continue development of this project, I will be looking to add or fix the f
 
   * Create more styles for the bar, potentiallly including dual boxes and a sawtooth bar
 
-If that goes well, `v3` can then either create a tool for generating inset maps (which `matplotlib` has *some* support for), or the various functions that I have created in the past that assist with formatting a map "properly", such as centering on a given object and coverting FIPS codes.
+* **Utils:**
+
+  * (USA): Stronger fuzzy search mechanics, so that it will accept flexible inputs for FIPS/abbr/name
+
+  * (USA): More integrated class types to allow for a more fully-formed object model (USA being a `Country`, with subclasses related to `State` and `Territory` that have their own classes of attributes, etc.)
+
+  * (USA): Stronger typing options, so you don't have to recall which `region` or `division` types are available, etc.
+
+If that goes well, `v3` can then either create a tool for generating inset maps (which `matplotlib` has *some* support for), or the various functions that I have created in the past that assist with formatting a map "properly", such as centering on a given object.
 
 I am also open to ideas for other extensions to create!
 

{matplotlib_map_utils-2.0.1 → matplotlib_map_utils-2.1.0}/matplotlib_map_utils/core/scale_bar.py

@@ -679,7 +679,7 @@ def _config_bar(ax, bar):
     # If the provided units are in degrees, we will convert to meters first
     # This will recalculate the ax_range
     if units_proj=="degree":
-        warnings.warn(f"Provided CRS {bar["projection"]} uses degrees. An attempt will be made at conversion, but there will be accuracy issues: it is recommended that you use a projected CRS instead.")
+        warnings.warn(f"Provided CRS {bar['projection']} uses degrees. An attempt will be made at conversion, but there will be accuracy issues: it is recommended that you use a projected CRS instead.")
         ylim = ax.get_ylim()
         xlim = ax.get_xlim()
         # Using https://github.com/seangrogan/great_circle_calculator/blob/master/great_circle_calculator/great_circle_calculator.py
@@ -706,7 +706,7 @@ def _config_bar(ax, bar):
     try:
         units_user = sbt.units_standard.get(bar["unit"])
     except:
-        warnings.warn(f"Desired output units selected by user ({bar["unit"]}) are considered invalid; please use one of the units specified in the units_standard dictionary in defaults.py")
+        warnings.warn(f"Desired output units selected by user ({bar['unit']}) are considered invalid; please use one of the units specified in the units_standard dictionary in defaults.py")
         units_user = None
 
     # Converting
@@ -749,7 +749,7 @@ def _config_bar(ax, bar):
             if bar["length"] < ax_dim:
                 bar_max = (bar["length"] / ax_dim) * ax_range
             else:
-                warnings.warn(f"Provided bar length ({bar["length"]}) is greater than the axis length ({ax_dim}); setting bar length to default (25% of axis length).")
+                warnings.warn(f"Provided bar length ({bar['length']}) is greater than the axis length ({ax_dim}); setting bar length to default (25% of axis length).")
                 bar_max = 0.25 * ax_range
     # If bar["max"] is provided, don't need to go through all of this effort
     else:

matplotlib_map_utils-2.1.0/matplotlib_map_utils/utils/__init__.py

@@ -0,0 +1,3 @@
+from .usa import USA
+
+__all__ = ["USA"]