From 381ff41555d9201dfbe4d9ef686cbec0a212b88b Mon Sep 17 00:00:00 2001 From: echedey-ls <80125792+echedey-ls@users.noreply.github.com> Date: Wed, 27 Nov 2024 23:17:16 +0000 Subject: [PATCH 1/9] Update pvsystem.py --- pvlib/pvsystem.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py index 1fde69216c..3710826a18 100644 --- a/pvlib/pvsystem.py +++ b/pvlib/pvsystem.py @@ -2060,7 +2060,13 @@ def retrieve_sam(name=None, path=None): CEC_Date NaN CEC_Type Utility Interactive Name: AE_Solar_Energy__AE6_0__277V_, dtype: object - """ + + # using the latest CEC Inverter database, via URL + >>> inv_db = pvsystem.retrieve_sam(path="https://raw.githubusercontent.com/NREL/SAM/refs/heads/develop/deploy/libraries/CEC%20Inverters.csv") + >>> inv_db.keys() + Index(['ABB__PVI_3_0_OUTD_S_US_A__208V_', 'ABB__PVI_3_0_OUTD_S_US_A__240V_', ...], + dtype='object', length=...) + """ # noqa: E501 # error: path was previously silently ignored if name was given GH#2018 if name is not None and path is not None: raise ValueError("Please provide either 'name' or 'path', not both.") From c6e4f41f8b653c5c1a6f34daa12d39eaf913b489 Mon Sep 17 00:00:00 2001 From: echedey-ls <80125792+echedey-ls@users.noreply.github.com> Date: Wed, 27 Nov 2024 23:21:57 +0000 Subject: [PATCH 2/9] Update v0.11.2.rst --- docs/sphinx/source/whatsnew/v0.11.2.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/sphinx/source/whatsnew/v0.11.2.rst b/docs/sphinx/source/whatsnew/v0.11.2.rst index 51549dd205..49a1121c17 100644 --- a/docs/sphinx/source/whatsnew/v0.11.2.rst +++ b/docs/sphinx/source/whatsnew/v0.11.2.rst @@ -46,6 +46,8 @@ Documentation - `spectra` and `spectra_components` (:issue:`2150`, :pull:`2264`) +* Added a example to :py:func:`~pvlib.pvsystem.retrieve_sam` docstring to + demonstrate how to retrieve a database from the SAM repo. (:pull:`2313`) Testing ~~~~~~~ From 2170d58b9cd9700f7b1b3ad2005fdb897da3c137 Mon Sep 17 00:00:00 2001 From: echedey-ls <80125792+echedey-ls@users.noreply.github.com> Date: Wed, 27 Nov 2024 23:23:07 +0000 Subject: [PATCH 3/9] Update pvsystem.py --- pvlib/pvsystem.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py index 3710826a18..895a24a7af 100644 --- a/pvlib/pvsystem.py +++ b/pvlib/pvsystem.py @@ -2064,7 +2064,7 @@ def retrieve_sam(name=None, path=None): # using the latest CEC Inverter database, via URL >>> inv_db = pvsystem.retrieve_sam(path="https://raw.githubusercontent.com/NREL/SAM/refs/heads/develop/deploy/libraries/CEC%20Inverters.csv") >>> inv_db.keys() - Index(['ABB__PVI_3_0_OUTD_S_US_A__208V_', 'ABB__PVI_3_0_OUTD_S_US_A__240V_', ...], + Index(['ABB__PVI_3_0_OUTD_S_US_A__208V_', 'ABB__PVI_3_0_OUTD_S_US_A__240V_', ...], dtype='object', length=...) """ # noqa: E501 # error: path was previously silently ignored if name was given GH#2018 From 160f151a4559aa51ebb2a980bed9a3e5708d7f1b Mon Sep 17 00:00:00 2001 From: Echedey Luis <80125792+echedey-ls@users.noreply.github.com> Date: Tue, 3 Dec 2024 19:16:53 +0000 Subject: [PATCH 4/9] review Co-authored-by: Kevin Anderson --- pvlib/pvsystem.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py index 895a24a7af..d5c2e94a70 100644 --- a/pvlib/pvsystem.py +++ b/pvlib/pvsystem.py @@ -2062,7 +2062,8 @@ def retrieve_sam(name=None, path=None): Name: AE_Solar_Energy__AE6_0__277V_, dtype: object # using the latest CEC Inverter database, via URL - >>> inv_db = pvsystem.retrieve_sam(path="https://raw.githubusercontent.com/NREL/SAM/refs/heads/develop/deploy/libraries/CEC%20Inverters.csv") + >>> url = "https://raw.githubusercontent.com/NREL/SAM/refs/heads/develop/deploy/libraries/CEC%20Inverters.csv" + >>> inv_db = pvsystem.retrieve_sam(path=url) >>> inv_db.keys() Index(['ABB__PVI_3_0_OUTD_S_US_A__208V_', 'ABB__PVI_3_0_OUTD_S_US_A__240V_', ...], dtype='object', length=...) From 1701d8bea7cba983a71022bd1ff0c941e08b9783 Mon Sep 17 00:00:00 2001 From: echedey-ls <80125792+echedey-ls@users.noreply.github.com> Date: Tue, 3 Dec 2024 19:20:20 +0000 Subject: [PATCH 5/9] remove returns name rationale: misleading var name --- pvlib/pvsystem.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py index d5c2e94a70..62346b8edf 100644 --- a/pvlib/pvsystem.py +++ b/pvlib/pvsystem.py @@ -2015,7 +2015,7 @@ def retrieve_sam(name=None, path=None): Returns ------- - samfile : DataFrame + DataFrame A DataFrame containing all the elements of the desired database. Each column represents a module or inverter, and a specific dataset can be retrieved by the command From 33d337ece025c305b1d3b869797b23b418ef03ed Mon Sep 17 00:00:00 2001 From: echedey-ls <80125792+echedey-ls@users.noreply.github.com> Date: Tue, 3 Dec 2024 19:21:00 +0000 Subject: [PATCH 6/9] do not format bulleted list into citation block --- pvlib/pvsystem.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py index 62346b8edf..059a5dd8ca 100644 --- a/pvlib/pvsystem.py +++ b/pvlib/pvsystem.py @@ -1986,10 +1986,10 @@ def retrieve_sam(name=None, path=None): This function will retrieve either: - * CEC module database - * Sandia Module database - * CEC Inverter database - * Anton Driesse Inverter database + * CEC module database + * Sandia Module database + * CEC Inverter database + * Anton Driesse Inverter database and return it as a pandas DataFrame. From aaa935310986f20a1325685c08f186b9e671c703 Mon Sep 17 00:00:00 2001 From: echedey-ls <80125792+echedey-ls@users.noreply.github.com> Date: Tue, 3 Dec 2024 19:24:26 +0000 Subject: [PATCH 7/9] Format strings as code --- pvlib/pvsystem.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py index 059a5dd8ca..0e7dd07338 100644 --- a/pvlib/pvsystem.py +++ b/pvlib/pvsystem.py @@ -2002,13 +2002,13 @@ def retrieve_sam(name=None, path=None): Use one of the following strings to retrieve a database bundled with pvlib: - * 'CECMod' - returns the CEC module database - * 'CECInverter' - returns the CEC Inverter database - * 'SandiaInverter' - returns the CEC Inverter database + * ``'CECMod'`` - returns the CEC module database + * ``'CECInverter'`` - returns the CEC Inverter database + * ``'SandiaInverter'`` - returns the CEC Inverter database (CEC is only current inverter db available; tag kept for backwards compatibility) - * 'SandiaMod' - returns the Sandia Module database - * 'ADRInverter' - returns the ADR Inverter database + * ``'SandiaMod'`` - returns the Sandia Module database + * ``'ADRInverter'`` - returns the ADR Inverter database path : string, optional Path to a CSV file or a URL. From 5d9afb60c5e56581e0f8289b5b4a63b3f3db80bc Mon Sep 17 00:00:00 2001 From: echedey-ls <80125792+echedey-ls@users.noreply.github.com> Date: Tue, 3 Dec 2024 19:24:42 +0000 Subject: [PATCH 8/9] Add titles to each example --- pvlib/pvsystem.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py index 0e7dd07338..31c5ad0b2d 100644 --- a/pvlib/pvsystem.py +++ b/pvlib/pvsystem.py @@ -2038,6 +2038,7 @@ def retrieve_sam(name=None, path=None): Examples -------- + Using a database bundled with pvlib: >>> from pvlib import pvsystem >>> invdb = pvsystem.retrieve_sam('CECInverter') @@ -2061,7 +2062,8 @@ def retrieve_sam(name=None, path=None): CEC_Type Utility Interactive Name: AE_Solar_Energy__AE6_0__277V_, dtype: object - # using the latest CEC Inverter database, via URL + Using a remote database, via URL: + >>> url = "https://raw.githubusercontent.com/NREL/SAM/refs/heads/develop/deploy/libraries/CEC%20Inverters.csv" >>> inv_db = pvsystem.retrieve_sam(path=url) >>> inv_db.keys() From 626ab43aba57f2dd98bef9321e3e10df31b80fe7 Mon Sep 17 00:00:00 2001 From: echedey-ls <80125792+echedey-ls@users.noreply.github.com> Date: Tue, 3 Dec 2024 19:25:54 +0000 Subject: [PATCH 9/9] Pass database name as keyword Rationale: be more explicit --- pvlib/pvsystem.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py index 31c5ad0b2d..d0695714d5 100644 --- a/pvlib/pvsystem.py +++ b/pvlib/pvsystem.py @@ -2041,7 +2041,7 @@ def retrieve_sam(name=None, path=None): Using a database bundled with pvlib: >>> from pvlib import pvsystem - >>> invdb = pvsystem.retrieve_sam('CECInverter') + >>> invdb = pvsystem.retrieve_sam(name='CECInverter') >>> inverter = invdb.AE_Solar_Energy__AE6_0__277V_ >>> inverter Vac 277