PyleoTUPS User APIs

The following describes the main classes that make up PyleoTUPS. Most users will primarily interact with the functionalities exposed in these classes.

NOAADataset (pyleotups.core.NOAADataset.NOAADataset)

class pyleotups.core.NOAADataset.NOAADataset[source]

A wrapper class for interacting with the NOAA Studies API.

Manages the retrieval, parsing, and aggregation of NOAA study data, and provides methods to access summaries, publications, sites, and external data files.

BASE_URL

The NOAA API endpoint URL.

Type:: str

studies

A mapping from NOAAStudyId to NOAAStudy instances.

Type:: dict

data_table_index

A mapping from dataTableID to associated study, site, and paleo data.

Type:: dict

get_data(dataTableIDs=None, file_urls=None)[source]

Fetch external data for given dataTableIDs or file URLs, perform validations, and attach study and site metadata.

Parameters:

dataTableIDs (list or str, optional) – One or more NOAA data table IDs.
file_urls (list or str, optional) – One or more file URLs.

Returns:

A list of DataFrames corresponding to the fetched data.

Return type:

list of pandas.DataFrame

Raises:

ValueError – For missing parent study mapping, missing file URL, or proprietary/unsupported file types.
Exception – Propagates any exceptions raised by the parser.

Examples

from pyleotups import NOAADataset
ds=NOAADataset()
df = ds.search_studies(noaa_id=33213)
dfs = ds.get_data(dataTableIDs="45859")
dfs[0].head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&NOAAStudyId=33213&limit=100

	Site	Hole	Core	Type	Section	Section_Depth	Sample_Depth	Age	TEX86H	SST
0	U1446	C	1	H	1	4.5	0.045	0.31	-0.1177	30.55
1	U1446	C	1	H	1	31.5	0.315	0.66	-0.1216	30.28
2	U1446	C	1	H	1	61.5	0.615	1.04	-0.1183	30.51
3	U1446	C	1	H	1	90.5	0.905	1.41	-0.1089	31.15
4	U1446	C	1	H	1	121.5	1.215	1.80	-0.1155	30.70

get_funding()[source]

Get a DataFrame of all funding records across loaded studies.

Returns:: A DataFrame with columns [‘StudyID’, ‘StudyName’, ‘FundingAgency’, ‘FundingGrant’]. Returns an empty DataFrame if no funding is available.
Return type:: pandas.DataFrame

Examples

from pyleotups import NOAADataset
ds=NOAADataset()
dsf = ds.search_studies(noaa_id=33213)
df = ds.get_funding()
df.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&NOAAStudyId=33213&limit=100

	StudyID	StudyName	FundingAgency	FundingGrant
0	33213	Bay of Bengal, Northeast Indian Margin Stable ...	US National Science Foundation	OCE1634774
1	33213	Bay of Bengal, Northeast Indian Margin Stable ...	United States Geological Survey (USGS)	NE/L002493/1
2	33213	Bay of Bengal, Northeast Indian Margin Stable ...	UK Natural Environment Research Council (NERC)	JPMXS05R2900001, 19H05595
3	33213	Bay of Bengal, Northeast Indian Margin Stable ...	Japan Society for the Promotion of Science (JSPS)	JPMXS05R2900001

get_geo()[source]

Get a DataFrame of site-level geospatial metadata and associated data types from all studies loaded into the Dataset.

Returns:: A DataFrame with one row per site and columns: [‘StudyID’, ‘SiteID’, ‘SiteName’, ‘LocationName’, ‘Latitude’, ‘Longitude’, ‘MinElevation’, ‘MaxElevation’, ‘DataType’]
Return type:: pandas.DataFrame

Examples

from pyleotups import NOAADataset
ds=NOAADataset()
dsf = ds.search_studies(noaa_id=33213)
df = ds.get_geo()
df.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&NOAAStudyId=33213&limit=100

	StudyID	DataType	SiteID	SiteName	LocationName	GeoType	GeometryType	MinLatitude	MaxLatitude	MinLongitude	MaxLongitude	MinElevation	MaxElevation
0	33213	PALEOCEANOGRAPHY	58697	IODP U1446	Ocean>Indian Ocean	Feature	POINT	19.083	19.083	85.733	85.733	-1440	-1440

get_publications(save=False, path=None, verbose=False)[source]

Get all publications in both BibTeX and DataFrame formats.

Parameters:

save (bool, default=False) – If True, save the BibTeX to a .bib file.
path (str or None, optional) – Path to save the .bib file. If None and save=True, saves to ‘bibtex_<timestamp>.bib’.
verbose (bool, default=False) – If True, print the BibTeX content to console.

Returns:

BibTeX object and DataFrame of publication details.

Return type:

tuple (pybtex.database.BibliographyData, pandas.DataFrame)

Examples

from pyleotups import NOAADataset
ds=NOAADataset()
dsf = ds.search_studies(noaa_id=33213)
bib, df = ds.get_publications()
df.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&NOAAStudyId=33213&limit=100

	Author	Title	Journal	Year	Volume	Number	Pages	Type	DOI	URL	CitationKey	StudyID	StudyName
0	Clemens, Steven; Yamamoto, Masanobu; Thirumala...	Remote and Local Drivers of Pleistocene South ...	Science Advances	2021	7	23	NaN	publication	10.1126/sciadv.abg3848	http://dx.doi.org/10.1126/sciadv.abg3848	M._Remote_2021_33213	33213	Bay of Bengal, Northeast Indian Margin Stable ...

get_sites()[source]

Get a DataFrame of all sites expanded to paleo data files.

Returns:: A DataFrame with one row per (Site × PaleoData × File).
Return type:: pandas.DataFrame

get_summary()[source]

Get a DataFrame summarizing all loaded studies.

Returns:: A DataFrame with a summary of study metadata and components.
Return type:: pandas.DataFrame

Examples

from pyleotups import NOAADataset
ds=NOAADataset()
df = ds.search_studies(noaa_id=33213)
df.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&NOAAStudyId=33213&limit=100

	StudyID	XMLID	StudyName	DataType	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding
0	33213	74834	Bay of Bengal, Northeast Indian Margin Stable ...	PALEOCEANOGRAPHY	1462580	280	-1460630	1670	(19.083, 19.083, 85.733, 85.733)	Provided Keywords: Indian monsoon, South Asian...	None	Steven Clemens, Masanobu Yamamoto, Kaustubh Th...	[{'Author': 'Clemens, Steven; Yamamoto, Masano...	[[{'DataTableID': '45863', 'DataTableName': 'U...	[{'fundingAgency': 'US National Science Founda...

get_tables()[source]

Get a DataFrame of all sites expanded to paleo data files.

Returns:: A DataFrame with one row per (Site × PaleoData × File).
Return type:: pandas.DataFrame

Examples

from pyleotups import NOAADataset
ds=NOAADataset()
dsf = ds.search_studies(noaa_id=33213)
df = ds.get_tables()
df.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&NOAAStudyId=33213&limit=100

	DataTableID	DataTableName	TimeUnit	FileURL	Variables	FileDescription	SiteID	SiteName	LocationName	GeoType	GeometryType	MinLatitude	MaxLatitude	MinLongitude	MaxLongitude	MinElevation	MaxElevation	StudyID	StudyName
0	45863	U1446 Rb/Ca Clemens2021	cal yr BP	https://www.ncei.noaa.gov/pub/data/paleo/contr...	[Site, Rb/Ca, Rb_normalized, Ca_normalized, Ag...	NOAA Template File	58697	IODP U1446	Ocean>Indian Ocean	Feature	POINT	19.083	19.083	85.733	85.733	-1440	-1440	33213	Bay of Bengal, Northeast Indian Margin Stable ...
1	45862	U1446 Mg/Ca Clemens2021	cal yr BP	https://www.ncei.noaa.gov/pub/data/paleo/contr...	[Mg/Ca_SST, Mg/Ca, Age, Sample_Depth, Section_...	NOAA Template File	58697	IODP U1446	Ocean>Indian Ocean	Feature	POINT	19.083	19.083	85.733	85.733	-1440	-1440	33213	Bay of Bengal, Northeast Indian Margin Stable ...
2	45861	U1446 LeafWax CarbonIsotope Clemens2021	cal yr BP	https://www.ncei.noaa.gov/pub/data/paleo/contr...	[d13C_Ave, d13C_C32, d13C_C30, d13C_C28, d13C_...	NOAA Template File	58697	IODP U1446	Ocean>Indian Ocean	Feature	POINT	19.083	19.083	85.733	85.733	-1440	-1440	33213	Bay of Bengal, Northeast Indian Margin Stable ...
3	45860	U1446 d18Osw Clemens2021	cal yr BP	https://www.ncei.noaa.gov/pub/data/paleo/contr...	[d18Osw_out_Mg/Ca, Mg/Ca, d18Osw_out_Shakun, S...	NOAA Template File	58697	IODP U1446	Ocean>Indian Ocean	Feature	POINT	19.083	19.083	85.733	85.733	-1440	-1440	33213	Bay of Bengal, Northeast Indian Margin Stable ...
4	45859	U1446 TEX86H_SST Clemens2021	cal yr BP	https://www.ncei.noaa.gov/pub/data/paleo/contr...	[SST, TEX86H, Age, Sample_Depth, Section_Depth...	NOAA Template File	58697	IODP U1446	Ocean>Indian Ocean	Feature	POINT	19.083	19.083	85.733	85.733	-1440	-1440	33213	Bay of Bengal, Northeast Indian Margin Stable ...

get_variables(dataTableIDs)[source]

Retrieve variable metadata for specified dataTableIDs.

Parameters:: dataTableIDs (list or str) – One or more NOAA dataTableIDs.
Returns:: A DataFrame indexed by DataTableID with one row per (file × variable). Includes full variable metadata such as cvShortName, cvUnit, etc.
Return type:: pandas.DataFrame

Examples

from pyleotups import NOAADataset
ds=NOAADataset()
dsf = ds.search_studies(noaa_id=33213)
df_var = ds.get_variables(dataTableIDs="45859")
df_var.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&NOAAStudyId=33213&limit=100

	StudyID	SiteID	FileURL	VariableName	cvDataType	cvWhat	cvMaterial	cvError	cvUnit	cvSeasonality	cvDetail	cvMethod	cvAdditionalInfo	cvFormat	cvShortName
DataTableID
45859	33213	58697	https://www.ncei.noaa.gov/pub/data/paleo/contr...	SST	CLIMATE RECONSTRUCTIONS\|PALEOCEANOGRAPHY	earth system variable>temperature variable>tem...	reconstruction material>organic compound index...	None	temperature unit>degree Celsius	None	None	NaN	index of Kim et al. 2010	Numeric	SST
45859	33213	58697	https://www.ncei.noaa.gov/pub/data/paleo/contr...	TEX86H	PALEOCEANOGRAPHY	chemical composition>compound>organic compound...	NaN	None	dimensionless	None	None	laboratory method>chromatography>liquid chroma...	index of Schouten et al. 2002; extracted lipids	Numeric	TEX86H
45859	33213	58697	https://www.ncei.noaa.gov/pub/data/paleo/contr...	Age	CLIMATE RECONSTRUCTIONS\|PALEOCEANOGRAPHY	age variable>age	NaN	None	time unit>age unit>calendar kiloyear before pr...	None	None	NaN	NaN	Numeric	Age
45859	33213	58697	https://www.ncei.noaa.gov/pub/data/paleo/contr...	Sample_Depth	CLIMATE RECONSTRUCTIONS\|PALEOCEANOGRAPHY	depth variable>depth	NaN	None	length unit>meter	None	None	NaN	Spliced core composite depth below sea floor ...	Numeric	Sample_Depth
45859	33213	58697	https://www.ncei.noaa.gov/pub/data/paleo/contr...	Section_Depth	PALEOCEANOGRAPHY	sampling metadata>sample identification	NaN	None	length unit>centimeter	None	None	NaN	Mid-depth of sample within section	Numeric	Section_Depth

Search for NOAA studies using the specified parameters.

At least one parameter must be provided to perform a search. This method interfaces with the NOAA NCEI Paleo Study Search API. Use it to filter studies based on location, investigators, time range, keywords, and more.

Parameters:

xml_id (str, optional) – Specify the internal XML document ID. Must be an exact match (e.g., ‘1840’).
noaa_id (str, optional) – Provide the unique NOAA Study ID as a number (e.g., ‘13156’).
search_text (str, optional) – General text search across study content. Supports wildcards (%) and logical operators (AND, OR). Examples: ‘younger dryas’, ‘loess AND stratigraphy’
data_publisher (str, default "NOAA") – Choose from: ‘NOAA’, ‘NEOTOMA’, or ‘PANGAEA’. Example: ‘NOAA’
data_type_id (str, optional) – Filter by data type. Use one or more type IDs separated by ‘|’. Available IDs. 1. BOREHOLE, 2. CLIMATE FORCING, 3. CLIMATE RECONSTRUCTIONS, 4. CORALS AND SCLEROSPONGES, 6. HISTORICAL, 7. ICE CORES, 8. INSECT, 9. LAKE LEVELS, 10. LOESS, 11. PALEOCLIMATIC MODELING, 12. FIRE HISTORY, 13. PALEOLIMNOLOGY, 14. PALEOCEANOGRAPHY, 15. PLANT MACROFOSSILS, 16. POLLEN, 17. SPELEOTHEMS, 18. TREE RING, 19. OTHER COLLECTIONS, 20. INSTRUMENTAL, 59. SOFTWARE, 60. REPOSITORY Example: ‘4’, ‘4|18’
investigators (str or list[str], optional) – Investigator(s) in the form "LastName, Initials". Lists are joined with |.
investigators_and_or ({"and","or"}, default "or") – Logical combiner when multiple investigators are supplied. Only sent when 2+ items.
locations (str or list[str], optional) – Location(s) as hierarchical strings using > (e.g., "Continent>Africa>Kenya"). Lists joined with |.
locations_and_or ({"and","or"}, default "or") – Logical combiner for multiple locations. Only sent when 2+ items.
keywords (str or list[str], optional) – Controlled keyword(s); hierarchies with >. Lists joined with |.
keywords_and_or ({"and","or"}, default "or") – Logical combiner for multiple keywords. Only sent when 2+ items.
species (str or list[str], optional) – Four-letter tree species codes (uppercase enforced). Lists joined with |.
species_and_or ({"and","or"}, default "or") – Logical combiner for multiple species. Only sent when 2+ items.
variable_name (str or list[str], optional) – Refers to PaST “cvWhats” terms (hierarchies with >). Lists joined with |.
variable_name_and_or ({"and","or"}, default "or") – Logical combiner for multiple cvWhats/variable_name. Only sent when 2+ items.
cv_materials (str or list[str], optional) – PaST “Material” terms (hierarchies with >). Lists joined with |.
cv_materials_and_or ({"and","or"}, default "or") – Logical combiner for multiple cv_materials. Only sent when 2+ items.
cv_seasonalities (str or list[str], optional) – PaST “Seasonality” terms (e.g., "annual" or "3-month>Aug-Oct"). Lists joined with |.
cv_seasonalities_and_or ({"and","or"}, default "or") – Logical combiner for multiple cv_seasonalities. Only sent when 2+ items.
min_lat (int, optional) – Latitude bounds in whole degrees (–90..90).
max_lat (int, optional) – Latitude bounds in whole degrees (–90..90).
min_lon (int, optional) – Longitude bounds in whole degrees (–180..180).
max_lon (int, optional) – Longitude bounds in whole degrees (–180..180).
min_elevation (int, optional) – Elevation bounds in meters (integers; negative allowed).
max_elevation (int, optional) – Elevation bounds in meters (integers; negative allowed).
earliest_year (int, optional) – Year bounds (integers; negative allowed). If provided without time settings, time_format defaults to 'CE'.
latest_year (int, optional) – Year bounds (integers; negative allowed). If provided without time settings, time_format defaults to 'CE'.
time_format ({"CE","BP"}, optional) – Interpretation of years. If omitted with a time window, defaults to 'CE'.
time_method ({"overAny","entireOver","overEntire"}, optional, default = None) – How to apply the time window (overlap, envelop, or within). NOAA internally defaults to “overAny” if a time window is provided without a method.
reconstruction (bool or str, optional) – Accepts True/False or strings (case-insensitive) like "true"|"yes"|"y"|"1" → 'Y' and "false"|"no"|"n"|"0" → 'N'. None omits the filter.
recent (bool, default False) – If True, restrict to studies from the last ~2 years (newest first).
limit (int, default 100) – Number of studies to return (PyleoTUPS default).
skip (int, optional) – Number of studies to skip (for pagination). Use with limit to page through results. Example: limit=10, skip=10 returns items 11–20.

Returns:

Response DataFrame. Fills the internal studies attribute with structured NOAA study data.

Return type:

pandas.DataFrame

Raises:

ValueError – If no inputs are passed.
requests.HTTPError – If the HTTP request returned an unsuccessful status code.

Notes

User Guide.

Multi-value fields. For investigators, locations, keywords, species, variable_name (cvWhats), cv_materials, cv_seasonalities: - Accept a string (already |-separated) or a Python list of strings. - Lists are joined with |. The corresponding *_and_or flag is included only when 2+ items. - Species are validated to four uppercase letters.

Identifiers short-circuit. If xml_id or noaa_id is set, the request includes only that id (plus publisher), ignoring other filters.

Time window defaults. If either earliest_year or latest_year is provided and neither time_format nor time_method is supplied, time_format defaults to 'CE' (a note is recorded).

Unsupported parameters. headersOnly is not supported by PyleoTUPS and ignored if passed.

Boolean normalization. Parameters expected as 'Y'/'N' accept: True/False, or strings like "true"|"yes"|"y"|"1" → 'Y' and "false"|"no"|"n"|"0" → 'N'.

Examples

Quick start (identifiers)

import pyleotups as pt
ds = pt.NOAADataset()
df_noaa = ds.search_studies(noaa_id=13156)
df_xml = ds.search_studies(xml_id=1840)
df_noaa.head()
df_xml.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&NOAAStudyId=13156&limit=100

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&xmlId=1840&limit=100

	StudyID	XMLID	StudyName	DataType	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding
0	5589	1840	Southern Ocean Midlatitude 160KYr Alkenone SST...	PALEOCEANOGRAPHY	156360	1951	-154410	-1	(-45.53, -40.37, 174.93, 177.98)	None	[Sea Surface Temperature Reconstruction]	Katharina Pahnke, Julian Sachs	[{'Author': 'Pahnke, K. and J.P. Sachs', 'Titl...	[[{'DataTableID': '7966', 'DataTableName': 'M9...	[]

Full-text search (Oracle syntax)

### Single phrase
df_singlephrase = ds.search_studies(search_text="younger dryas", limit=20)
df_singlephrase.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&limit=20&searchText=younger+dryas

	StudyID	XMLID	StudyName	DataType	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding
0	5898	2709	Aharon 2003 Gulf of Mexico Deglacial Stable Is...	PALEOCEANOGRAPHY	18000.0	1000.0	-16050.0	950.0	(27.76, 27.76, -92.59, -92.59)	NaN	None	Paul Aharon	[{'Author': 'Aharon, P.', 'Title': 'Meltwater ...	[[{'DataTableID': '33150', 'DataTableName': 'A...	[]
1	40939	82023	Alaskan Lake Stable Isotope and Geochemistry D...	PALEOLIMNOLOGY	15126.0	-68.0	-13176.0	2018.0	(61.489946, 64.311005, -150.00032, -146.666764)	Provided Keywords: Paleohydrology, effective m...	[Atmospheric and Oceanic Circulation Patterns ...	Lesleigh Anderson, Bruce Finney, W. Brad Baxter	[{'Author': 'Anderson, L., Finney, B.P., Baxte...	[[{'DataTableID': '55473', 'DataTableName': 'A...	[{'fundingAgency': 'United States Geological S...
2	25670	63714	Alkenone SST reconstructions from the eastern ...	PALEOCEANOGRAPHY	29840.0	790.0	-27890.0	1160.0	(-3.38, -0.47, -89.68, -82.07)	Provided Keywords: Eastern Equatorial Pacific,...	[Sea Surface Temperature Reconstruction]	Athanasios Koutavas, Julian Sachs	[{'Author': 'Koutavas, A., and J.P. Sachs', 'T...	[[{'DataTableID': '37533', 'DataTableName': 'V...	[{'fundingAgency': 'US National Science Founda...
3	5919	2962	Andrews et al. 1999 Holocene High-Res Labrador...	PALEOCEANOGRAPHY	12000.0	0.0	-10050.0	1950.0	(54.6165, 54.7952, -56.1766, -56.0583)	NaN	None	Anne Jennings, John Andrews, Lloyd Keigwin, Fr...	[{'Author': 'Andrews, J. T., Keigwin, L., Hall...	[[{'DataTableID': '33128', 'DataTableName': 'A...	[]
4	11207	9643	Angola-Benguela Front ODP1078C 25KYr Alkenone ...	PALEOCEANOGRAPHY	24740.0	20.0	-22790.0	1930.0	(-11.92, -11.92, 13.4, 13.4)	Alkenone sea-surface temperature (SST) estimat...	[Sea Surface Temperature Reconstruction]	Jung-Hyun Kim, Ralph Schneider, Stefan Mulitza...	[{'Author': 'Kim, J.-H., R.R. Schneider, S. Mu...	[[{'DataTableID': '19810', 'DataTableName': 'O...	[{'fundingAgency': 'Bundesministerium für Bild...

### Logical operator (AND)
df_logop = ds.search_studies(search_text="loess AND stratigraphy", limit=20)
df_logop.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&limit=20&searchText=loess+AND+stratigraphy

	StudyID	XMLID	StudyName	DataType	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding
0	5599	2466	Ding et al. 1999 Lingtai Loess Stratigraphy Data	LOESS AND PALEOSOL	7000000	0	-6998050	1950	(35.0667, 35.0667, 107.65, 107.65)	None	None	Zhongli Ding	[{'Author': 'Ding, Z.L., S.F. Xiong, J.M. Sun,...	[[{'DataTableID': '32592', 'DataTableName': 'L...	[]

### Wildcards: '_' (single char), '%' (multi-char)
df_wc_1 = ds.search_studies(search_text="f_re", limit=20)
df_wc_2 = ds.search_studies(search_text="pol%", limit=20)
df_wc_1.head(), df_wc_2.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&limit=20&searchText=f_re

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&limit=20&searchText=pol%25

(  StudyID  XMLID                                          StudyName  \
  5473    652  A High-Resolution Record of Climatic Change in...   
 18435  16119  Aishihik Basin, Yukon 12,000 Year Multiproxy L...   
 22113  20095  Allen - Lake Riveaux/Abrotonella Rise - ATSE -...   
  1926   5011  Anderson fire data from Swamp Lake - IMPD USSW...   
 29752  71613  Andreu-Hayles - Ice Cut Dalton Highway - ALCR ...   
 
          DataType  EarliestYearBP  MostRecentYearBP  EarliestYearCE  \
PALEOLIMNOLOGY            1500               -32             450   
PALEOLIMNOLOGY           12906               -57          -10956   
     TREE RING             538               -59            1412   
  FIRE HISTORY           15819               -10          -13869   
     TREE RING              30               -60            1920   
 
    MostRecentYearCE                       Coverage [S, N, W, E]  \
            1982  (45.86694, 45.86694, -95.80361, -95.80361)   
            2007    (61.2447, 61.2447, -136.9264, -136.9264)   
            2009        (-43.183, -43.183, 146.595, 146.595)   
            1960            (37.95, 37.95, -119.82, -119.82)   
            2010                (69.0, 69.0, -148.8, -148.8)   
 
                                           StudyNotes  \
Geochemical and paleontological data sets for ...   
Multiproxy sediment data from Lake WA01, Aishi...   
Post-1930 disturbanes at this site, including ...   
                                              NaN   
North Slope, Alaska, 2010 shrub ring-width dat...   
 
                                      ScienceKeywords  \
                                             None   
                                             None   
[ATSE, King Billy pine, Athrotaxis selaginoide...   
                                             None   
[Alnus viridis var. crispa (Ait.) Turrill, Ame...   
 
                                        Investigators  \
                      Roger Anderson, Walter Dean   
               Rebecca Rainville, Konrad Gajewski   
                                    Kathryn Allen   
                                R. Scott Anderson   
Laia Andreu-Hayles, Kevin Anchukaitis, Javi Ma...   
 
                                         Publications  \
[{'Author': 'Walter E. Dean, J.P. Bradbury, R....   
[{'Author': 'Rebecca A. Rainville and Konrad G...   
[{'Author': 'K.J. Allen,  J. Ogden, B.M. Buckl...   
                                               []   
[{'Author': 'Laia Andreu-Hayles, Benjamin V. G...   
 
                                                Sites  \
[[{'DataTableID': '8031', 'DataTableName': 'El...   
[[{'DataTableID': '28800', 'DataTableName': 'W...   
[[{'DataTableID': '33245', 'DataTableName': 'A...   
[[{'DataTableID': '2062', 'DataTableName': 'US...   
[[{'DataTableID': '42277', 'DataTableName': 'A...   
 
                                              Funding  
                                               []  
[{'fundingAgency': 'Natural Sciences and Engin...  
[{'fundingAgency': 'Australian Research Counci...  
                                               []  
[{'fundingAgency': 'US National Science Founda...  ,
   StudyID  XMLID                                          StudyName  \
 10437   9101  1,000 Year Ensemble Reconstructions of Tempera...   
 36253  77512  10Be Chronology of Khoton Nuur Glacial Landfor...   
 22315  20388        2000 Year Tropical Rainfall Reconstructions   
 12894  10958  9400 Year Cosmogenic Isotope Data and Solar Ac...   
 19281  16968  A global planktic foraminifer census data set ...   
 
                   DataType  EarliestYearBP  MostRecentYearBP  EarliestYearCE  \
CLIMATE RECONSTRUCTIONS           950.0             -45.0          1000.0   
CLIMATE RECONSTRUCTIONS         35000.0           16000.0        -33050.0   
CLIMATE RECONSTRUCTIONS          2000.0             -50.0           -50.0   
        CLIMATE FORCING          9389.0             -27.0         -7439.0   
       PALEOCEANOGRAPHY       6181000.0         1603000.0      -6179050.0   
 
    MostRecentYearCE                        Coverage [S, N, W, E]  \
          1995.0                   (0.0, 90.0, -180.0, 180.0)   
        -14050.0  (48.613232, 48.97233, 88.078977, 88.430928)   
          2000.0                 (-30.0, 30.0, -180.0, 180.0)   
          1977.0                 (-90.0, 90.0, -180.0, 180.0)   
      -1601050.0                         (nan, nan, nan, nan)   
 
                                           StudyNotes  \
Calibration ensemble reconstructions of existi...   
                                              NaN   
Composite reconstruction of low latitude rainf...   
Records of common production rate of cosmogeni...   
Data Compilers: Foley, Kevin; Robinson, Marci;...   
 
                                      ScienceKeywords  \
[carbon cycle, sensitivity, Air Temperature Re...   
                                             None   
                   [Precipitation Reconstruction]   
                   [Solar Forcing Reconstruction]   
                                             None   
 
                                        Investigators  \
David Frank, Jan Esper, Christoph Raible, Ulf ...   
Peter Strand, Aaron Putnam, Oyungerel Sambuu, ...   
Franziska Lechleitner, Sebastian Breitenbach, ...   
Friedhelm Steinhilber, Jose Abreu, Jürg Beer, ...   
Kevin Foley, Marci Robinson, Harry Dowsett, Ri...   
 
                                         Publications  \
[{'Author': 'Frank, D.C., J. Esper, C.C. Raibl...   
[{'Author': 'Strand, Peter D., Aaron E. Putnam...   
[{'Author': 'Franziska A. Lechleitner, Sebasti...   
[{'Author': 'Steinhilber, F., J.A. Abreu, J. B...   
[{'Author': 'Dowsett, H., M. Robinson, A. Hayw...   
 
                                                Sites  \
[[{'DataTableID': '19235', 'DataTableName': 'F...   
[[{'DataTableID': '48957', 'DataTableName': 'K...   
[[{'DataTableID': '33444', 'DataTableName': 'L...   
[[{'DataTableID': '21230', 'DataTableName': 'T...   
[[{'DataTableID': '29818', 'DataTableName': 'R...   
 
                                              Funding  
[{'fundingAgency': 'Swiss National Science Fou...  
[{'fundingAgency': 'US National Science Founda...  
[{'fundingAgency': 'European Union', 'fundingG...  
[{'fundingAgency': 'Swiss National Science Fou...  
                                               []  )

### Escaping special characters (use backslashes)
df_specchar = ds.search_studies(search_text=r"noaa\-tree\-19260", limit=20)
df_specchar.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&limit=20&searchText=noaa%5C-tree%5C-19260

	StudyID	XMLID	StudyName	DataType	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding
0	19260	16927	Samonil - Zofinsky prales - ABAL - ITRDB CZEC003	TREE RING	363	-60	1587	2010	(48.6667, 48.6667, 14.7, 14.7)	NOAA Template Chronology file added 2018-12-1...	[ABAL, silver fir, Abies alba Mill., European ...	Pavel Šamonil, Petra Doleželová, Ivana Vašíčko...	[{'Author': 'Pavel Šamonil, Petra Doleželová, ...	[[{'DataTableID': '29759', 'DataTableName': 'C...	[]

Investigators, keywords, locations

### Multiple investigators (OR by default)
df_multinv_default = ds.search_studies(investigators=["Wahl, E.R.", "Vose, R.S."])
df_multinv_default.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&limit=100&investigators=Wahl%2C+E.R.%7CVose%2C+R.S.&investigatorsAndOr=or

	StudyID	XMLID	StudyName	DataType	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding
0	8405	2665	Ammann and Wahl 2007 N. Hemisphere Temperature...	CLIMATE RECONSTRUCTIONS	950	-30	1000	1980	(0.0, 80.0, -180.0, 180.0)	Northern hemisphere multiproxy average annual ...	[Air Temperature Reconstruction]	Caspar Ammann, Eugene Wahl	[{'Author': 'Ammann, C.M. and E.R. Wahl', 'Tit...	[[{'DataTableID': '19446', 'DataTableName': 'P...	[{'fundingAgency': 'US National Center for Atm...
1	18295	15997	California and Western Nevada Precipitation Re...	CLIMATE RECONSTRUCTIONS	379	-27	1571	1977	(32.5, 42.0, -124.4, -116.5)	Water year (October through following Septembe...	[drought, Precipitation Reconstruction]	Henry Diaz, Eugene Wahl	[{'Author': 'Henry F. Diaz and Eugene R. Wahl'...	[[{'DataTableID': '28654', 'DataTableName': 'C...	[]
2	19600	17329	European Mean and Spatial Summer Temperature R...	CLIMATE RECONSTRUCTIONS	2088	-53	-138	2003	(35.0, 70.0, -25.0, 40.0)	Spatial (5x5 degree grid) reconstructions of E...	[Air Temperature Reconstruction, PAGES Euro-Me...	Jürg Luterbacher, Johannes Werner, Jason Smerd...	[{'Author': 'J. Luterbacher, J. P. Werner, J. ...	[[{'DataTableID': '30218', 'DataTableName': 'L...	[{'fundingAgency': 'US National Science Founda...
3	20465	18279	Hawaiian Islands 500 Year Winter Rainfall and ...	CLIMATE RECONSTRUCTIONS	450	-62	1500	2012	(18.72, 23.95, -166.74, -156.15)	Reconstructions of Hawaii winter (Dec-Feb) pre...	[Other Reconstruction, pressure, Precipitation...	Henry Diaz, Eugene Wahl, Eduardo Zorita, Thoma...	[{'Author': 'Henry F. Diaz, Eugene R. Wahl, Ed...	[[{'DataTableID': '31159', 'DataTableName': 'H...	[]
4	22454	20650	Living Blended Drought Atlas (LBDA) Version 2 ...	CLIMATE RECONSTRUCTIONS	1950	-75	0	2025	(24.0, 50.0, -124.0, -68.0)	The half-degree gridded June-August Palmer Mod...	[drought, Palmer Drought Index Reconstruction]	Edward Gille, Carrie Morrill, Eugene Wahl, Rus...	[{'Author': 'Cook, E.R., Seager, R., Heim, R.R...	[[{'DataTableID': '33588', 'DataTableName': 'C...	[{'fundingAgency': 'US National Oceanic and At...

### Multiple investigators (AND by default)
df_multinv_and = ds.search_studies(investigators=["Wahl, E.R.", "Vose, R.S."], investigators_and_or="and")
df_multinv_and.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&limit=100&investigators=Wahl%2C+E.R.%7CVose%2C+R.S.&investigatorsAndOr=and

	StudyID	XMLID	StudyName	DataType	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding
0	22454	20650	Living Blended Drought Atlas (LBDA) Version 2 ...	CLIMATE RECONSTRUCTIONS	1950	-75	0	2025	(24.0, 50.0, -124.0, -68.0)	The half-degree gridded June-August Palmer Mod...	[drought, Palmer Drought Index Reconstruction]	Edward Gille, Carrie Morrill, Eugene Wahl, Rus...	[{'Author': 'Cook, E.R., Seager, R., Heim, R.R...	[[{'DataTableID': '33588', 'DataTableName': 'C...	[{'fundingAgency': 'US National Oceanic and At...
1	21793	19750	Wahl, et al., 2017, precipitation reconstructi...	CLIMATE RECONSTRUCTIONS	379	-27	1571	1977	(32.5, 42.0, -124.5, -114.0)	The reconstructions are derived from streamflo...	[Precipitation Reconstruction]	Eugene Wahl, Henry Diaz, Russell Vose, Wendy G...	[{'Author': 'Eugene. R. Wahl, Henry F. Diaz, R...	[[{'DataTableID': '32809', 'DataTableName': 'w...	[]

### Keywords: hierarchy with '>' and multiple via '|'
df_keywords = ds.search_studies(keywords="earth science>paleoclimate>paleocean>biomarkers")
df_keywords.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&limit=100&keywords=earth+science%3Epaleoclimate%3Epaleocean%3Ebiomarkers

	StudyID	XMLID	StudyName	DataType	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding
0	22588	20773	2.8 million years of alkenone and TEX86 data a...	PALEOCEANOGRAPHY	2785481.0	257.0	-2783531.0	1693.0	(18.836, 18.836, 116.566, 116.566)	Surface and subsurface temperature difference ...	[Sea Surface Temperature Reconstruction]	Dawei Li, Meixun Zhao, Jun Tian	[{'Author': 'Li, D., M. Zhao, and J. Tian', 'T...	[[{'DataTableID': '33711', 'DataTableName': 'O...	[]
1	34232	75912	Adélie Drift, East Antarctic Fatty Acid Carbon...	PALEOCEANOGRAPHY	363.0	-48.0	1587.0	1998.0	(-66.408333, -66.408333, 140.4405, 140.4405)	Provided Keywords: Paleoceanography, Sea Ice R...	None	Kate Ashley, James Bendle, Xavier Crosta, Joha...	[{'Author': 'Ashley, Kate, James Bendle, Xavie...	[[{'DataTableID': '47058', 'DataTableName': 'D...	[{'fundingAgency': 'European Commission Sevent...
2	33472	75092	Agulhas Plateau Biomarker Data and SST Reconst...	PALEOCEANOGRAPHY	1400000.0	339800.0	-1398050.0	-337850.0	(-41.2561, -41.2561, 25.1564, 25.1564)	A new biomarker records of upper water column ...	[Sea Surface Temperature Reconstruction]	Alejandra Cartagena-Sierra, Melissa Berke, Reb...	[{'Author': 'Cartagena-Sierra, A., Berke, M.A....	[[{'DataTableID': '46117', 'DataTableName': 'I...	[{'fundingAgency': 'US National Science Founda...
3	25670	63714	Alkenone SST reconstructions from the eastern ...	PALEOCEANOGRAPHY	29840.0	790.0	-27890.0	1160.0	(-3.38, -0.47, -89.68, -82.07)	Provided Keywords: Eastern Equatorial Pacific,...	[Sea Surface Temperature Reconstruction]	Athanasios Koutavas, Julian Sachs	[{'Author': 'Koutavas, A., and J.P. Sachs', 'T...	[[{'DataTableID': '37533', 'DataTableName': 'V...	[{'fundingAgency': 'US National Science Founda...
4	22400	20534	Alkenone paleotemperature estimates, d18O seaw...	PALEOCEANOGRAPHY	18170.0	400.0	-16220.0	1550.0	(56.96, 57.872382, -137.10446, -136.43)	Source reference for EW0408-66JC and EW0408-26...	[Sea Surface Temperature Reconstruction]	Summer Praetorius, Alan Mix, Britta Jensen, Du...	[{'Author': 'Praetorius, S.K, A.C. Mix, B. Jen...	[[{'DataTableID': '33517', 'DataTableName': 'E...	[{'fundingAgency': 'US National Science Founda...

### Location hierarchy
df_loc = ds.search_studies(locations="Continent>Africa>Eastern Africa>Zambia")
df_loc.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&limit=100&locations=Continent%3EAfrica%3EEastern+Africa%3EZambia

	StudyID	XMLID	StudyName	DataType	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding
0	1000537	1000160	Global Database of Borehole Temperatures and C...	BOREHOLE	450	-22	1500	1972	(-13.92, -13.92, 29.2, 29.2)	This project has as its goal the design, asse...	[Air Temperature Reconstruction, temperature]	Shaopeng Huang, Henry Pollack, Po Yu Shen	[{'Author': 'Huang, S., Pollack, H.N., and She...	[[{'DataTableID': '1000631', 'DataTableName': ...	[{'fundingAgency': 'US National Science Founda...
1	1000538	1000161	Global Database of Borehole Temperatures and C...	BOREHOLE	450	-22	1500	1972	(-13.92, -13.92, 29.2, 29.2)	This project has as its goal the design, asse...	[temperature, Air Temperature Reconstruction]	Shaopeng Huang, Henry Pollack, Po Yu Shen	[{'Author': 'Huang, S., Pollack, H.N., and She...	[[{'DataTableID': '1000632', 'DataTableName': ...	[{'fundingAgency': 'US National Science Founda...
2	1000540	1000163	Global Database of Borehole Temperatures and C...	BOREHOLE	450	-24	1500	1974	(-15.82, -15.82, 27.92, 27.92)	This project has as its goal the design, asse...	[temperature, Air Temperature Reconstruction]	Shaopeng Huang, Henry Pollack, Po Yu Shen	[{'Author': 'Huang, S., Pollack, H.N., and She...	[[{'DataTableID': '1000634', 'DataTableName': ...	[{'fundingAgency': 'US National Science Founda...
3	1000541	1000164	Global Database of Borehole Temperatures and C...	BOREHOLE	450	-24	1500	1974	(-13.08, -13.08, 28.05, 28.05)	This project has as its goal the design, asse...	[temperature, Air Temperature Reconstruction]	Shaopeng Huang, Henry Pollack, Po Yu Shen	[{'Author': 'Huang, S., Pollack, H.N., and She...	[[{'DataTableID': '1000635', 'DataTableName': ...	[{'fundingAgency': 'US National Science Founda...
4	1000539	1000162	Global Database of Borehole Temperatures and C...	BOREHOLE	450	-38	1500	1988	(-12.58, -12.58, 31.65, 31.65)	This project has as its goal the design, asse...	[temperature, Air Temperature Reconstruction]	Shaopeng Huang, Henry Pollack, Po Yu Shen	[{'Author': 'Huang, S., Pollack, H.N., and She...	[[{'DataTableID': '1000633', 'DataTableName': ...	[{'fundingAgency': 'US National Science Founda...

Species and types

### Species: four-letter codes (uppercase enforced)
df_species = ds.search_studies(species=["ABAL", "PIPO"])
df_species.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&limit=100&species=ABAL%7CPIPO&speciesAndOr=or

	StudyID	XMLID	StudyName	DataType	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding
0	26070	64380	Azpeleta Tarancón fire data from Mistletoe Can...	FIRE HISTORY	418	-64	1532	2014	(33.215925, 33.215925, -105.608842, -105.608842)	This site was sampled to assess the spatiotemp...	[eastern white pine, Pseudotsuga menziesii (Mi...	Alicia Azpeleta Tarancón, Peter Fulé, Andrew S...	[{'Author': 'Azpeleta Tarancon, A., Fulé, P.Z....	[[{'DataTableID': '37993', 'DataTableName': 'U...	[{'fundingAgency': 'US Department of Agricultu...
1	26071	64375	Azpeleta Tarancón fire data from Potato Patch ...	FIRE HISTORY	271	-65	1679	2015	(33.043863, 33.043863, -105.724789, -105.724789)	This site was sampled to assess the spatiotemp...	[eastern white pine, Pinus ponderosa Douglas e...	Alicia Azpeleta Tarancón, Peter Fulé, Andrew S...	[{'Author': 'Azpeleta Tarancon, A., Fulé, P.Z....	[[{'DataTableID': '37994', 'DataTableName': 'U...	[{'fundingAgency': 'USDA National Institute of...
2	26073	64376	Azpeleta Tarancón fire data from Snow Canyon, ...	FIRE HISTORY	578	-14	1372	1964	(33.240746, 33.240746, -105.638039, -105.638039)	This site was sampled to assess the spatiotemp...	[PIST, Weymouth pine, PIPO, Pinus ponderosa Do...	Alicia Azpeleta Tarancón, Peter Fulé, Andrew S...	[{'Author': 'Azpeleta Tarancon, A., Fulé, P.Z....	[[{'DataTableID': '37996', 'DataTableName': 'U...	[]
3	26072	64374	Azpeleta Tarancón fire data from Solon, south ...	FIRE HISTORY	351	-62	1599	2012	(33.051347, 33.051347, -105.556574, -105.556574)	Tarancón fire data from Solon, south central N...	[Weymouth pine, ponderosa pine, Pinus strobus ...	Alicia Azpeleta Tarancón, Peter Fulé, Andrew S...	[{'Author': 'Azpeleta Tarancon, A., Fulé, P.Z....	[[{'DataTableID': '37995', 'DataTableName': 'U...	[{'fundingAgency': 'USDA National Institute of...
4	26074	64381	Azpeleta Tarancón fire data from Turkey Canyon...	FIRE HISTORY	343	-53	1607	2003	(33.099762, 33.099762, -105.549527, -105.549527)	This site was sampled to assess the spatiotemp...	[PIPO, western yellow pine, Pinus ponderosa Do...	Alicia Azpeleta Tarancón, Peter Fulé, Andrew S...	[{'Author': 'Azpeleta Tarancon, A., Fulé, P.Z....	[[{'DataTableID': '37997', 'DataTableName': 'U...	[{'fundingAgency': 'USDA National Institute of...

### Data types: one or more IDs separated by '|'
df_muldatatypes = ds.search_studies(data_type_id="4|18")
df_muldatatypes.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataTypeId=4%7C18&dataPublisher=NOAA&limit=100

	StudyID	XMLID	StudyName	DataType	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding
0	11194	9632	1,100 Year El Niño/Southern Oscillation (ENSO)...	CLIMATE RECONSTRUCTIONS	1050	-52	900	2002	(-20.0, 20.0, 145.0, -80.0)	An index of canonical ENSO variability for the...	[Atmospheric and Oceanic Circulation Patterns ...	Jinbao Li, Shang-Ping Xie, Edward Cook, Gang H...	[{'Author': 'Li, J., S.-P. Xie, E.R. Cook, G. ...	[[{'DataTableID': '19791', 'DataTableName': 'e...	[{'fundingAgency': 'US National Science Founda...
1	22315	20388	2000 Year Tropical Rainfall Reconstructions	CLIMATE RECONSTRUCTIONS	2000	-50	-50	2000	(-30.0, 30.0, -180.0, 180.0)	Composite reconstruction of low latitude rainf...	[Precipitation Reconstruction]	Franziska Lechleitner, Sebastian Breitenbach, ...	[{'Author': 'Franziska A. Lechleitner, Sebasti...	[[{'DataTableID': '33444', 'DataTableName': 'L...	[{'fundingAgency': 'European Union', 'fundingG...
2	33872	75532	2017 Florida Bay Sr/Ca and d18O Data during Hu...	CORALS AND SCLEROSPONGES	-67	-67	2017	2017	(24.9621, 24.9621, -80.801467, -80.801467)	Seawater Sr/Ca and oxygen isotopes to complem...	None	K. Halimeda Kilbourne, Johan Schijf, Hunter Hu...	[{'Author': 'Khare, Agraj, Hunter P. Hughes, K...	[[{'DataTableID': '46662', 'DataTableName': 'O...	[{'fundingAgency': 'US National Science Founda...
3	14632	12613	700 Year El Niño/Southern Oscillation (ENSO) N...	CLIMATE RECONSTRUCTIONS	649	-55	1301	2005	(-5.0, 5.0, -170.0, -120.0)	An index of canonical El Niño/Southern Oscilla...	[ENSO, Atmospheric and Oceanic Circulation Pat...	Jinbao Li, Shang-Ping Xie, Edward Cook, Marian...	[{'Author': 'Li, J., S.-P. Xie, E.R. Cook, G. ...	[[{'DataTableID': '24679', 'DataTableName': 'L...	[{'fundingAgency': 'US National Science Founda...
4	36696	77955	A 641-year Regional Summer Soil Moisture Recon...	CLIMATE RECONSTRUCTIONS	590	-50	1360	2000	(45.0, 55.0, -10.0, 10.0)	Summer (June-July-August) soil moisture recons...	None	Lu Wang, Hongyan Liu, Deliang Chen, Peng Zhang...	[{'Author': 'Wang, Lu, Hongyan Liu, Deliang Ch...	[[{'DataTableID': '49385', 'DataTableName': 'W...	[{'fundingAgency': 'Swedish Formas Project', '...

Geography and elevation

df_latlong = ds.search_studies(min_lat=68, max_lat=69, min_lon=30, max_lon=40)
df_latlong.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&limit=100&minLat=68&maxLat=69&minLon=30&maxLon=40

	StudyID	XMLID	StudyName	DataType	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding
0	10437	9101	1,000 Year Ensemble Reconstructions of Tempera...	CLIMATE RECONSTRUCTIONS	950.0	-45.0	1000.0	1995.0	(0.0, 90.0, -180.0, 180.0)	Calibration ensemble reconstructions of existi...	[carbon cycle, sensitivity, Air Temperature Re...	David Frank, Jan Esper, Christoph Raible, Ulf ...	[{'Author': 'Frank, D.C., J. Esper, C.C. Raibl...	[[{'DataTableID': '19235', 'DataTableName': 'F...	[{'fundingAgency': 'Swiss National Science Fou...
1	42679	83754	1006-year reconstruction of Rossby wavenumber-5	CLIMATE RECONSTRUCTIONS	950.0	-55.0	1000.0	2005.0	(0.0, 90.0, -180.0, 180.0)	NaN	[Atmospheric and Oceanic Circulation Patterns ...	Ellie Broadman, Valerie Trouet, Kai Kornhuber	[{'Author': 'Broadman, Ellie, Kai Kornhuber, I...	[[{'DataTableID': '56946', 'DataTableName': 'W...	[{'fundingAgency': 'US National Science Founda...
2	12203	10267	2000 Year Precipitation-Based Southern Oscilla...	CLIMATE RECONSTRUCTIONS	1900.0	-5.0	50.0	1955.0	(-90.0, 90.0, -180.0, 180.0)	Reconstruction of a precipitation-based Southe...	[Atmospheric and Oceanic Circulation Patterns ...	Hong Yan, Liguang Sun, Yuhong Wang, Wen Huang,...	[{'Author': 'Yan, H., L. Sun, Y. Wang, W. Huan...	[[{'DataTableID': '20526', 'DataTableName': 'S...	[{'fundingAgency': 'National Natural Science F...
3	14190	12191	600 Year Ensemble Climate Reconstructions and ...	CLIMATE RECONSTRUCTIONS	550.0	-61.0	1400.0	2011.0	(45.0, 85.0, -180.0, 180.0)	Ensemble Climate Reconstructions, input data f...	[Air Temperature Reconstruction]	Martin Tingley, Peter Huybers	[{'Author': 'Tingley, M.P. and P. Huybers', 'T...	[[{'DataTableID': '24136', 'DataTableName': 'T...	[{'fundingAgency': 'US National Science Founda...
4	12894	10958	9400 Year Cosmogenic Isotope Data and Solar Ac...	CLIMATE FORCING	9389.0	-27.0	-7439.0	1977.0	(-90.0, 90.0, -180.0, 180.0)	Records of common production rate of cosmogeni...	[Solar Forcing Reconstruction]	Friedhelm Steinhilber, Jose Abreu, Jürg Beer, ...	[{'Author': 'Steinhilber, F., J.A. Abreu, J. B...	[[{'DataTableID': '21230', 'DataTableName': 'T...	[{'fundingAgency': 'Swiss National Science Fou...

df_elv = ds.search_studies(min_elevation=100, max_elevation=110)
df_elv.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&limit=100&minElev=100&maxElev=110

	StudyID	XMLID	StudyName	DataType	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding
0	40170	81293	Abissal Cave, Rainha Cave Geochemical Data fro...	SPELEOTHEMS	25694.0	4044.0	-23744.0	-2094.0	(-5.5782, -5.5642, -37.6659, -37.6432)	Data contributed as part of SISAL v3 Global Sp...	None	Francisco Cruz, Mathias Vuille, Stephen Burns,...	[{'Author': 'Cruz, Francisco W.; Mathias Vuill...	[[{'DataTableID': '53529', 'DataTableName': 'A...	[]
1	40477	81622	Adenesky-Filho - Blumenau - SC - CEFI - ITRDB ...	TREE RING	13.0	-61.0	1937.0	2011.0	(-26.904761, -26.904761, -49.114204, -49.114204)	Tropical Tree Ring Network SiteID = CEFIS_BRA_07	[CEFI, Cedrela fissilis Vell., Cedro rosa]	Eduardo Adenesky-Filho, Karin Esemann-Quadros,...	[{'Author': 'Unknown Author', 'Title': 'Unknow...	[[{'DataTableID': '54044', 'DataTableName': 'B...	[]
2	40939	82023	Alaskan Lake Stable Isotope and Geochemistry D...	PALEOLIMNOLOGY	15126.0	-68.0	-13176.0	2018.0	(61.489946, 64.311005, -150.00032, -146.666764)	Provided Keywords: Paleohydrology, effective m...	[Atmospheric and Oceanic Circulation Patterns ...	Lesleigh Anderson, Bruce Finney, W. Brad Baxter	[{'Author': 'Anderson, L., Finney, B.P., Baxte...	[[{'DataTableID': '55473', 'DataTableName': 'A...	[{'fundingAgency': 'United States Geological S...
3	31418	73106	Allen - Tiwi Islands - CAIN - ITRDB AUSL060	TREE RING	73.0	-57.0	1877.0	2007.0	(-11.71, -11.71, 130.83, 130.83)	Callitris intratropica ring-width data used fo...	[CAIN, cypress pine, Callitris intratropica R....	Kathryn Allen, Jonathan Palmer, Patrick Baker	[{'Author': 'K.J. Allen, M.B. Freund, J.G. Pal...	[[{'DataTableID': '43922', 'DataTableName': 'A...	[{'fundingAgency': 'Australian Research Counci...
4	28315	68766	Arnold - Codnor Castle - QUSP - ITRDB BRIT078	TREE RING	569.0	391.0	1381.0	1559.0	(53.044355, 53.044355, -1.354599, -1.354599)	NOAA Template Raw Measurements file added 2020...	[Quercus spp. L., oak, QUSP]	Alison Arnold, Robert Howard	[]	[[{'DataTableID': '40602', 'DataTableName': 'B...	[{'fundingAgency': 'Historic England', 'fundin...

Time window (defaults to CE if no time settings)

### Explicit BP with method
df_timew = ds.search_studies(earliest_year=12000, time_format="BP", time_method="overAny")
df_timew.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&limit=100&earliestYear=12000&timeFormat=BP&timeMethod=overAny

	StudyID	XMLID	StudyName	DataType	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding
0	10437	9101	1,000 Year Ensemble Reconstructions of Tempera...	CLIMATE RECONSTRUCTIONS	950	-45	1000	1995	(0.0, 90.0, -180.0, 180.0)	Calibration ensemble reconstructions of existi...	[carbon cycle, sensitivity, Air Temperature Re...	David Frank, Jan Esper, Christoph Raible, Ulf ...	[{'Author': 'Frank, D.C., J. Esper, C.C. Raibl...	[[{'DataTableID': '19235', 'DataTableName': 'F...	[{'fundingAgency': 'Swiss National Science Fou...
1	11194	9632	1,100 Year El Niño/Southern Oscillation (ENSO)...	CLIMATE RECONSTRUCTIONS	1050	-52	900	2002	(-20.0, 20.0, 145.0, -80.0)	An index of canonical ENSO variability for the...	[Atmospheric and Oceanic Circulation Patterns ...	Jinbao Li, Shang-Ping Xie, Edward Cook, Gang H...	[{'Author': 'Li, J., S.-P. Xie, E.R. Cook, G. ...	[[{'DataTableID': '19791', 'DataTableName': 'e...	[{'fundingAgency': 'US National Science Founda...
2	14193	12194	1000 Year Composite Sea Surface Temperature Re...	PALEOCEANOGRAPHY	950	-46	1000	1996	(56.66667, 69.48333, -18.1957, 18.36667)	A set of reconstructions of sea surface temper...	None	Laura Cunningham, William Austin, Karen-Luise ...	[{'Author': 'Cunningham, L.K., Austin, W.E.N.,...	[[{'DataTableID': '24146', 'DataTableName': 'P...	[{'fundingAgency': 'European Commission', 'fun...
3	42679	83754	1006-year reconstruction of Rossby wavenumber-5	CLIMATE RECONSTRUCTIONS	950	-55	1000	2005	(0.0, 90.0, -180.0, 180.0)	NaN	[Atmospheric and Oceanic Circulation Patterns ...	Ellie Broadman, Valerie Trouet, Kai Kornhuber	[{'Author': 'Broadman, Ellie, Kai Kornhuber, I...	[[{'DataTableID': '56946', 'DataTableName': 'W...	[{'fundingAgency': 'US National Science Founda...
4	22031	20009	1200 Year Atlantic Multidecadal Variability an...	CLIMATE RECONSTRUCTIONS	1150	-60	800	2010	(0.0, 70.0, -80.0, 0.0)	Summer (May-September) Atlantic Multidecadal V...	[Atmospheric and Oceanic Circulation Patterns ...	Jianglin Wang, Bao Yang, Fredrik Ljungqvist, J...	[{'Author': 'Jianglin Wang, Bao Yang, Fredrik ...	[[{'DataTableID': '33108', 'DataTableName': 'W...	[{'fundingAgency': 'National Natural Science F...

### No time_format/time_method → defaults to CE
df_time_defualt = ds.search_studies(earliest_year=1500, latest_year=0)
df_time_defualt.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&limit=100&earliestYear=1500&latestYear=0&timeFormat=CE

	StudyID	XMLID	StudyName	DataType	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding
0	22588	20773	2.8 million years of alkenone and TEX86 data a...	PALEOCEANOGRAPHY	2785481	257	-2783531	1693	(18.836, 18.836, 116.566, 116.566)	Surface and subsurface temperature difference ...	[Sea Surface Temperature Reconstruction]	Dawei Li, Meixun Zhao, Jun Tian	[{'Author': 'Li, D., M. Zhao, and J. Tian', 'T...	[[{'DataTableID': '33711', 'DataTableName': 'O...	[]
1	22315	20388	2000 Year Tropical Rainfall Reconstructions	CLIMATE RECONSTRUCTIONS	2000	-50	-50	2000	(-30.0, 30.0, -180.0, 180.0)	Composite reconstruction of low latitude rainf...	[Precipitation Reconstruction]	Franziska Lechleitner, Sebastian Breitenbach, ...	[{'Author': 'Franziska A. Lechleitner, Sebasti...	[[{'DataTableID': '33444', 'DataTableName': 'L...	[{'fundingAgency': 'European Union', 'fundingG...
2	22390	20667	860,000 Years of foraminifera-bound nitrogen i...	PALEOCEANOGRAPHY	860000	0	-858050	1950	(12.68, 12.68, 119.45, 119.45)	A 860,000-year nitrogen isotope record from So...	None	Haojia Ren, Daniel Sigman, Alfredo Martínez-Ga...	[{'Author': 'Ren, H.; Sigman, D.M.; Martinez-G...	[[{'DataTableID': '33610', 'DataTableName': 'M...	[]
3	12894	10958	9400 Year Cosmogenic Isotope Data and Solar Ac...	CLIMATE FORCING	9389	-27	-7439	1977	(-90.0, 90.0, -180.0, 180.0)	Records of common production rate of cosmogeni...	[Solar Forcing Reconstruction]	Friedhelm Steinhilber, Jose Abreu, Jürg Beer, ...	[{'Author': 'Steinhilber, F., J.A. Abreu, J. B...	[[{'DataTableID': '21230', 'DataTableName': 'T...	[{'fundingAgency': 'Swiss National Science Fou...
4	15090	12950	A 2000 year long seasonal record of floods in ...	PALEOLIMNOLOGY	2067	-48	-117	1998	(45.876667, 45.876667, 10.750556, 10.750556)	This dataset contains ages and thicknesses of ...	[Seasonal Resolution (SR), Little Ice Age (LIA...	Stefanie Wirth, Adrian Gilli, Anaëlle Simonnea...	[{'Author': 'Wirth, S. B., A. Gilli, A. Simonn...	[[{'DataTableID': '25120', 'DataTableName': 'T...	[{'fundingAgency': 'Swiss National Science Fou...

Reconstructions and recency

df_recon = ds.search_studies(reconstruction=True)
df_recon.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&limit=100&reconstructionsOnly=Y

	StudyID	XMLID	StudyName	DataType	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding
0	10437	9101	1,000 Year Ensemble Reconstructions of Tempera...	CLIMATE RECONSTRUCTIONS	950.0	-45.0	1000.0	1995.0	(0.0, 90.0, -180.0, 180.0)	Calibration ensemble reconstructions of existi...	[carbon cycle, sensitivity, Air Temperature Re...	David Frank, Jan Esper, Christoph Raible, Ulf ...	[{'Author': 'Frank, D.C., J. Esper, C.C. Raibl...	[[{'DataTableID': '19235', 'DataTableName': 'F...	[{'fundingAgency': 'Swiss National Science Fou...
1	11194	9632	1,100 Year El Niño/Southern Oscillation (ENSO)...	CLIMATE RECONSTRUCTIONS	1050.0	-52.0	900.0	2002.0	(-20.0, 20.0, 145.0, -80.0)	An index of canonical ENSO variability for the...	[Atmospheric and Oceanic Circulation Patterns ...	Jinbao Li, Shang-Ping Xie, Edward Cook, Gang H...	[{'Author': 'Li, J., S.-P. Xie, E.R. Cook, G. ...	[[{'DataTableID': '19791', 'DataTableName': 'e...	[{'fundingAgency': 'US National Science Founda...
2	14193	12194	1000 Year Composite Sea Surface Temperature Re...	PALEOCEANOGRAPHY	950.0	-46.0	1000.0	1996.0	(56.66667, 69.48333, -18.1957, 18.36667)	A set of reconstructions of sea surface temper...	None	Laura Cunningham, William Austin, Karen-Luise ...	[{'Author': 'Cunningham, L.K., Austin, W.E.N.,...	[[{'DataTableID': '24146', 'DataTableName': 'P...	[{'fundingAgency': 'European Commission', 'fun...
3	42679	83754	1006-year reconstruction of Rossby wavenumber-5	CLIMATE RECONSTRUCTIONS	950.0	-55.0	1000.0	2005.0	(0.0, 90.0, -180.0, 180.0)	NaN	[Atmospheric and Oceanic Circulation Patterns ...	Ellie Broadman, Valerie Trouet, Kai Kornhuber	[{'Author': 'Broadman, Ellie, Kai Kornhuber, I...	[[{'DataTableID': '56946', 'DataTableName': 'W...	[{'fundingAgency': 'US National Science Founda...
4	36253	77512	10Be Chronology of Khoton Nuur Glacial Landfor...	CLIMATE RECONSTRUCTIONS	35000.0	16000.0	-33050.0	-14050.0	(48.613232, 48.97233, 88.078977, 88.430928)	NaN	None	Peter Strand, Aaron Putnam, Oyungerel Sambuu, ...	[{'Author': 'Strand, Peter D., Aaron E. Putnam...	[[{'DataTableID': '48957', 'DataTableName': 'K...	[{'fundingAgency': 'US National Science Founda...

df_recent = ds.search_studies(recent=True, limit=25)
df_recent.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&limit=25&recent=true

	StudyID	XMLID	StudyName	DataType	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding
0	44782	85275	Allen - Buckleys Chance - LAFR - ITRDB AUS128	TREE RING	771	-62	1179	2012	(-42.27, -42.27, 145.87, 145.87)	NaN	[Lagarostrobos franklinii (Hook. f.) Quinn, LG...	Kathryn Allen	[{'Author': 'Allen, K J; E R Cook; R Evans; R ...	[[{'DataTableID': '59583', 'DataTableName': 'A...	[{'fundingAgency': 'Australian Research Counci...
1	44781	85278	Allen - Southwest Tasmania Composite - PHAS - ...	TREE RING	425	-62	1525	2012	(-42.5, -42.5, 146.45, 146.45)	Site bounding box: -42.2 to -42.78 S, 146.3 to...	[Phyllocladus aspleniifolius (Labill.) Hook. f...	Kathryn Allen	[]	[[{'DataTableID': '59582', 'DataTableName': 'A...	[{'fundingAgency': 'Australian Research Counci...
2	44780	85276	Allen - Swift Creek - Florentine - PHAS - ITRD...	TREE RING	524	-62	1426	2012	(-42.5, -42.5, 145.51, 145.51)	Site bounding box: -42.2 to -42.78 S, 145.45 t...	[celery top pine, Phyllocladus aspleniifolius ...	Kathryn Allen	[{'Author': 'Allen, K J; E R Cook; R Evans; R ...	[[{'DataTableID': '59581', 'DataTableName': 'A...	[{'fundingAgency': 'Australian Research Counci...
3	44761	85255	Lucas - Esteros Farrapos e Islas del Rio Urugu...	TREE RING	-20	-74	1970	2024	(-32.738, -32.738, -58.132, -58.132)	NaN	[Gleditsia triacanthos L., GLTR, honey locust]	Christine Lucas, Serrana Ambite, Melina J. Ara...	[{'Author': 'Christine Lucas, Serrana Ambite, ...	[[{'DataTableID': '59562', 'DataTableName': 'U...	[{'fundingAgency': 'Agencia Nacional de Invest...
4	44760	85236	Prom - Platteville Mound Ash - FRSP - ITRDB WI071	TREE RING	7	-69	1943	2019	(42.7653, 42.7653, -90.4044, -90.4044)	Prom, K. Platte Mound Ash. TREES Lab contribut...	[Fraxinus spp. L., FRSP, ash]	Kiersten Prom, James Riser, Evan Larson	[]	[[{'DataTableID': '59561', 'DataTableName': 'W...	[]

Limit and Skipping (for pagination)

### Limit up to first 10 results
df_limit = ds.search_studies(earliest_year=12000, time_format="BP", time_method="overAny", limit=10)
df_limit.head()

### Skip the first 10 results (i.e., get results 11-20)
df_skip = ds.search_studies(earliest_year=12000, time_format="BP", time_method="overAny", limit=10, skip=10)
df_skip.head()

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&limit=10&earliestYear=12000&timeFormat=BP&timeMethod=overAny

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&limit=10&skip=10&earliestYear=12000&timeFormat=BP&timeMethod=overAny

	StudyID	XMLID	StudyName	DataType	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding
0	9896	8788	200KYr Midge Temperature, Diatom pH, and C/N Data	PALEOLIMNOLOGY	200000	907	-198050	1043	(70.558, 70.558, -68.95, -68.95)	Multiproxy sediment data from Lake CF8, Baffin...	[Arctic, Air Temperature Reconstruction]	Yarrow Axford, Jason Briner, Colin Cooke, Donn...	[{'Author': 'Axford, Y., J.P. Briner, C.A. Coo...	[[{'DataTableID': '18746', 'DataTableName': 'C...	[{'fundingAgency': 'US National Science Founda...
1	33872	75532	2017 Florida Bay Sr/Ca and d18O Data during Hu...	CORALS AND SCLEROSPONGES	-67	-67	2017	2017	(24.9621, 24.9621, -80.801467, -80.801467)	Seawater Sr/Ca and oxygen isotopes to complem...	None	K. Halimeda Kilbourne, Johan Schijf, Hunter Hu...	[{'Author': 'Khare, Agraj, Hunter P. Hughes, K...	[[{'DataTableID': '46662', 'DataTableName': 'O...	[{'fundingAgency': 'US National Science Founda...
2	2605	1676	340 KYr SW Pacific d18O Data and Mg/Ca-based S...	PALEOCEANOGRAPHY	340830	1951	-338880	-1	(-45.53, -45.53, 174.93, 174.93)		[Sea Surface Temperature Reconstruction]	Katharina Pahnke, Rainer Zahn, Henry Elderfiel...	[{'Author': 'Pahnke, K., R. Zahn, H. Elderfiel...	[[{'DataTableID': '4289', 'DataTableName': 'MD...	[]
3	2614	1685	350 KYr Sea Level Reconstruction and Foraminif...	PALEOCEANOGRAPHY	361500	1000	-359550	950	(2.25, 2.25, -90.95, -90.95)		[Sea Level Reconstruction]	David Lea, Pamela Martin, Dorothy Pak, Howard ...	[{'Author': 'Lea, D.W., P.A. Martin, D.K. Pak,...	[[{'DataTableID': '4301', 'DataTableName': 'TR...	[]
4	14190	12191	600 Year Ensemble Climate Reconstructions and ...	CLIMATE RECONSTRUCTIONS	550	-61	1400	2011	(45.0, 85.0, -180.0, 180.0)	Ensemble Climate Reconstructions, input data f...	[Air Temperature Reconstruction]	Martin Tingley, Peter Huybers	[{'Author': 'Tingley, M.P. and P. Huybers', 'T...	[[{'DataTableID': '24136', 'DataTableName': 'T...	[{'fundingAgency': 'US National Science Founda...

PangaeaDataset (pyleotups.core.PangaeaDataset.PangaeaDataset)

class pyleotups.core.PangaeaDataset.PangaeaDataset(cache_dir: str | None = None, auth_token: str | None = None)[source]

PangaeaDataset: lightweight provider that mirrors pyleotups.core.Dataset responses.

Notes: - search_studies(kwargs) registers studies in self.studies (StudyID -> {‘panobj’: PanDataSet|None, ‘summary’: normalized_dict}) - get_summary() returns a pandas.DataFrame exactly matching NOAA Dataset.to_dict() column names. - get_publications(), get_geo(), get_funding() return DataFrames with the same column names as the original Dataset methods. Missing data produces empty DataFrames / NaNs. - get_data(identifier) returns a pandas.DataFrame (parsed table) and sets df.attrs[“source”].

This file intentionally mirrors the structure used in NOAADataset.py and NOAAStudy.py

convert_tups_to_pangaea(tups_query: Dict[str, Any]) → Dict[str, Any][source]: Stub for TUPS -> PANGAEA query translation.

get_data(study_id: int) → DataFrame[source]

Retrieve dataset for a specific study.

If the study is a collection, a warning is logged suggesting access to its collection members.

If the study is not registered but exists as a collection member of a registered study, it will be automatically loaded and registered.

Parameters:: study_id (int, str, or list) – One or more StudyIDs.
Returns:: If single ID → DataFrame. If multiple IDs → dict of {StudyID: DataFrame}.
Return type:: pandas.DataFrame or dict

get_funding() → DataFrame[source]

Retrieve funding information for all registered studies.

Returns:: Combined funding DataFrame across studies. If no funding is available, returns empty DataFrame with standardized columns.
Return type:: pandas.DataFrame

get_geo() → DataFrame[source]

Retrieve geographic information for all studies.

Returns:: Combined geographic metadata. [‘StudyID’,’SiteID’,’SiteName’,’LocationName’,’Latitude’,’Longitude’,’MinElevation’,’MaxElevation’,’DataType’] If PANGAEA lacks site-level metadata, returns an empty DataFrame.
Return type:: pandas.DataFrame

get_publications(save: bool = False, path: str | None = None, verbose: bool = False)[source]

Retrieve publication information for all registered PANGAEA studies.

This method aggregates publication metadata across all studies currently registered in the dataset. It returns both a structured pandas DataFrame and a BibTeX-compatible pybtex.database.BibliographyData object.

Publication extraction is performed at the study level via the internal PangaeaStudy._extract_publications() method, and results are combined across studies.

get_summary() → DataFrame[source]

Retrieve summary metadata for all registered studies.

Returns:: Return a DataFrame summarizing all loaded/registered PANGAEA datasets. [“StudyID”,”StudyName”,”EarliestYearBP”,”MostRecentYearBP”, “EarliestYearCE”,”MostRecentYearCE”,”Coverage [S, N, W, E]”, “StudyNotes”,”ScienceKeywords”,”Investigators”, “Publications”,”Sites”,”Funding”]
Return type:: pandas.DataFrame

get_variables(study_ids=None) → DataFrame[source]

Retrieve variable metadata for specified studies.

Parameters:: study_ids (int, str, list, or None) – One or more StudyIDs. Can be numeric or DOI string. If None, variables for all registered studies are returned.
Returns:: One row per (study × variable).
Return type:: pandas.DataFrame
Raises:: KeyError – If a requested StudyID is not registered and not found among collection members.

Search PANGAEA and register results in self.studies.

Behavior: - Populates self.studies (StudyID -> {‘panobj’: None|’PanDataSet’, ‘summary’: minimal}) - Does NOT return the DataFrame by default (returns None). - If display=True, returns the full normalized summary DataFrame from self.get_summary().

Search for PANGAEA datasets using unified PyleoTUPS query parameters.

This method translates user-friendly query parameters into a PANGAEA-compatible search query and registers the resulting datasets internally.

Parameters:

study_ids (int, str, or list, optional) – One or more PANGAEA dataset identifiers (numeric ID or DOI string). If provided, performs direct lookup and ignores other filters.
topic (str, optional) – Filter datasets by PANGAEA topic classification. Must be one of the predefined topics: - “all” (default) - “Agriculture” - “Atmosphere” - “Biological Classification” - “Biosphere” - “Chemistry” - “Cryosphere” - “Ecology” - “Fisheries” - “Geophysics” - “Human Dimensions” - “Lakes & Rivers” - “Land Surface” - “Lithosphere” - “Oceans” - “Paleontology” If set to “all” or omitted, no topic filtering is applied. If multiple values are provided, they are combined using a logical operator controlled by topic_and_or.
search_text (str, optional) – Free-text search query applied across dataset metadata. Maps to PANGAEA full-text search parameter ‘q’. Example: ‘stable carbon and oxygen isotopes’.
investigators (str or list[str], optional) – Author names. Mapped internally to PANGAEA query syntax: author:<name>
variable_name (str or list[str], optional) – Name of parameters/variables (columns) present in dataset tables. Internally mapped to PANGAEA query term: parameter:<variable_name>
min_lat (float, optional) – Latitude bounds (–90..90).
max_lat (float, optional) – Latitude bounds (–90..90).
min_lon (float, optional) – Longitude bounds (–180..180)
max_lon (float, optional) – Longitude bounds (–180..180)
limit (int, default 100, maximum 500) – Maximum number of results returned.
skip (int, default 0) – Number of results to skip (pagination). Maps to PANGAEA ‘offset’
topic_and_or ({"and", "or"}, optional, default="or") – Logical operator used to combine multiple topic values. - "or" (default): Matches datasets containing any of the provided topics. - "and": Matches datasets containing all provided topics.
investigators_and_or ({"and", "or"}, optional, default="or") – Logical operator used to combine multiple investigator names. - "or" (default): Matches datasets authored by any of the investigators. - "and": Matches datasets authored by all listed investigators.
variable_name_and_or ({"and", "or"}, optional, default="or") – Logical operator used to combine multiple variable names.

Returns:

DataFrame summarizing matched datasets. Also populates internal registry.

Return type:

pandas.DataFrame

Raises:

ValueError – If no valid search parameters are provided.

Notes

PANGAEA search is text-based and less structured than NOAA filters. Results may vary depending on metadata completeness.

Unified query interface. PyleoTUPS uses consistent parameter names across datasets:

variable_name → mapped to parameter: in PANGAEA
investigators → mapped to author:

Query construction. If q is not provided, a query string is constructed by combining: - search_text - investigators - variable_name - keywords

Geospatial filtering. Bounding box requires all four parameters: min_lat, max_lat, min_lon, max_lon. Partial inputs are ignored. Elevation parameters are not currently exposed through the PangaeaPy object or the PANGAEA advanced search endpoint. Hence, geographical queries are presently limited to 2D horizontal coordinates (lat/lon)

Identifier priority. If study_ids is provided, all other filters are ignored.

Multi-value parameters. When multiple values are provided (e.g., for variable_name, investigators, or topic), they are combined using a configurable logical operator (*_and_or). By default, PyleoTUPS uses OR semantics (union of matches), even though PANGAEA interprets space-separated terms as AND.

Examples

Quick Start - Identifier Based search

import pyleotups as pt
ds = pt.PangaeaDataset()

### Can use either DOI strings or numeric IDs (extracted from DOIs)
df = ds.search_studies(
    study_ids=["10.1594/PANGAEA.830587", "10.1594/PANGAEA.830588"]
)
df.head()

df = ds.search_studies(
    study_ids=[830587, 830588]
)
df.head()

	StudyID	StudyName	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding	CollectionMembers
0	830587	(Table 2) Age determination of sediment core M...	98.0	1950.0	0.0	1852.0	(1.4, 1.4, 119.08, 119.08)	None	[]	Khider, D, Stott, Lowell D, Emile-Geay, J, Thu...	Khider, D; Stott, Lowell D; Emile-Geay, J; Thu...	[MD98-2177]	[]	None
1	830588	(Table 3) Lead 214 and Lead 210 concentration ...	NaN	NaN	NaN	NaN	(1.4, 1.4, 119.08, 119.08)	None	[]	Khider, D, Stott, Lowell D, Emile-Geay, J, Thu...	Khider, D; Stott, Lowell D; Emile-Geay, J; Thu...	[MD98-2177]	[]	None

Basic search

df = ds.search_studies(search_text="Stable oxygen and carbon isotopes", limit = 5)
df.head()

{'q': 'Stable oxygen and carbon isotopes', 'bbox': None, 'limit': 5, 'offset': 0}

	StudyID	StudyName	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding	CollectionMembers
0	930941	Benthic stable carbon and oxygen isotopes of C...	4040447.0	2947.0	-4038497.0	-997.0	(0.3185, 0.3185, 159.361, 159.361)	ODP Leg 130 - Site 806B benthic stable carbon ...	[benthic d13C, benthic d18O, equatorial Pacifi...	Bickert, Torsten	Bickert, Torsten (2026): Benthic stable carbon...	[130-806B]	[{'name': 'Integrated Ocean Drilling Program /...	None
1	936448	Oxygen and carbon stable isotopes of Neogloboq...	243000.0	7620.0	-241050.0	-5670.0	(65.4155, 65.4155, -28.3305, -28.3305)	Stable isotope data on the near-surface polar ...	[Depth/age, Snorri Drift, stabe isotopes]	Andrews, John T	Andrews, John T (2021): Oxygen and carbon stab...	[MD99-2323]	[]	None
2	906181	Carbon and oxygen stable isotopes measured on ...	849790.0	14930.0	-847840.0	-12980.0	(57.556356666667, 57.556655, -175.817125, -175...	High latitude deep water upwelling has the pot...	[Bering Sea, CO2, Glacial, Sea ice, subarctic,...	Worne, Savannah	Worne, Savannah (2019): Carbon and oxygen stab...	[323-U1343A, 323-U1343C, 323-U1343E]	[{'name': 'Integrated Ocean Drilling Program /...	None
3	759625	Stable oxygen and carbon isotopes from ODP sit...	NaN	NaN	NaN	NaN	(-65.161, -58.441, 1.2049, 82.7878)	Paleogene stable oxygen and carbon isotopes we...	[]	Mackensen, Andreas, Ehrmann, Werner	Mackensen, Andreas; Ehrmann, Werner (1992): St...	[113-689B, 113-690B, 119-738B, 119-744A, 119-7...	[{'name': 'Ocean Drilling Program', 'url': 'ht...	[759603, 759604, 759615, 759618, 759619, 75962...
4	946916	Stable oxygen and carbon isotopes of planktic ...	NaN	NaN	NaN	NaN	None	Stable oxygen and carbon isotopes were measure...	[Benthic and planktonic foraminifera, Greece, ...	Titschack, Jürgen, Joseph, Nina, Freiwald, André	Titschack, Jürgen; Joseph, Nina; Freiwald, And...	[]	[]	[946585, 946586, 946588, 946589]

Variable-based search

df = ds.search_studies(variable_name=["Pulleniatina obliquiloculata δ13C", "Pulleniatina obliquiloculata δ18O"], limit = 5)
df.head()

{'q': '(parameter:Pulleniatina obliquiloculata δ13C OR parameter:Pulleniatina obliquiloculata δ18O)', 'bbox': None, 'limit': 5, 'offset': 0}

	StudyID	StudyName	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding	CollectionMembers
0	358901	(Table 2) Age model and stable isotope ratios ...	None	None	None	None	(-0.007, -0.007, 161.975, 161.975)	None	[]	Wu, Guoping, Berger, Wolfgang H	Wu, Guoping; Berger, Wolfgang H (1989): (Table...	[ERDC-129BX]	[]	None
1	52361	(Table 2) Stable isotope ratios measured on P....	None	None	None	None	(2.362, 2.362, 163.707, 163.707)	None	[]	Wu, Guoping, Berger, Wolfgang H	Wu, Guoping; Berger, Wolfgang H (1989): (Table...	[ERDC-141BX]	[]	None
2	358905	(Table 2) Age model and stable isotope ratios ...	None	None	None	None	(1.362, 1.362, 162.393, 162.393)	None	[]	Wu, Guoping, Berger, Wolfgang H	Wu, Guoping; Berger, Wolfgang H (1989): (Table...	[ERDC-139BX]	[]	None
3	358899	(Table 2) Age model and stable isotope ratios ...	None	None	None	None	(4.85, 4.85, 156.058, 156.058)	None	[]	Wu, Guoping, Berger, Wolfgang H	Wu, Guoping; Berger, Wolfgang H (1989): (Table...	[ERDC-077BX]	[]	None
4	358902	(Table 2) Age model and stable isotope ratios ...	None	None	None	None	(-0.027, -0.027, 162.702, 162.702)	None	[]	Wu, Guoping, Berger, Wolfgang H	Wu, Guoping; Berger, Wolfgang H (1989): (Table...	[ERDC-131BX]	[]	None

Investigator/Author-based search

df = ds.search_studies(investigators=["Khider, D"], limit = 5)
df.head()

{'q': 'author:Khider, D', 'bbox': None, 'limit': 5, 'offset': 0}

	StudyID	StudyName	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding	CollectionMembers
0	830589	Stable isotope record of sediment core MD98-2177	NaN	NaN	NaN	NaN	(1.4, 1.4, 119.08, 119.08)	We present a reconstruction of El Niño Souther...	[]	Khider, D, Stott, Lowell D, Emile-Geay, J, Thu...	Khider, D; Stott, Lowell D; Emile-Geay, J; Thu...	[MD98-2177]	[]	[830586, 830587, 830588]
1	897517	Globigerinoides ruber sediment trap data in th...	NaN	NaN	NaN	NaN	None	We present results here from a high-resolution...	[]	Richey, Julie N, Thirumalai, Kaustubh, Khider,...	Richey, Julie N; Thirumalai, Kaustubh; Khider,...	[]	[]	[897509, 897512, 897513, 897514, 897515, 897516]
2	830588	(Table 3) Lead 214 and Lead 210 concentration ...	NaN	NaN	NaN	NaN	(1.4, 1.4, 119.08, 119.08)	NaN	[]	Khider, D, Stott, Lowell D, Emile-Geay, J, Thu...	Khider, D; Stott, Lowell D; Emile-Geay, J; Thu...	[MD98-2177]	[]	None
3	897512	Globigerinoides ruber flux analysis from a lon...	NaN	NaN	NaN	NaN	(27.5, 27.5, -90.3, -90.3)	NaN	[]	Richey, Julie N, Thirumalai, Kaustubh, Khider,...	Richey, Julie N; Thirumalai, Kaustubh; Khider,...	[GMT_Gulf_of_Mexico]	[]	None
4	830586	(Table S1) Stable carbon and oxygen isotope ra...	1231.0	103.0	704.0	1851.0	(1.4, 1.4, 119.08, 119.08)	NaN	[]	Khider, D, Stott, Lowell D, Emile-Geay, J, Thu...	Khider, D; Stott, Lowell D; Emile-Geay, J; Thu...	[MD98-2177]	[]	None

Combined filters

df = ds.search_studies(
    search_text="Stable oxygen and carbon isotopes",
    variable_name=["Pulleniatina obliquiloculata δ13C", "Pulleniatina obliquiloculata δ18O"],
    investigators="Khider, D",
    limit = 5
)
df.head()

{'q': 'Stable oxygen and carbon isotopes author:Khider, D (parameter:Pulleniatina obliquiloculata δ13C OR parameter:Pulleniatina obliquiloculata δ18O)', 'bbox': None, 'limit': 5, 'offset': 0}

	StudyID	StudyName	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding	CollectionMembers
0	830586	(Table S1) Stable carbon and oxygen isotope ra...	1231	103	704	1851	(1.4, 1.4, 119.08, 119.08)	None	[]	Khider, D, Stott, Lowell D, Emile-Geay, J, Thu...	Khider, D; Stott, Lowell D; Emile-Geay, J; Thu...	[MD98-2177]	[]	None

Geographic filtering

df = ds.search_studies(
    min_lat=-10, max_lat=10,
    min_lon=120, max_lon=160
)
df.head()

{'q': '', 'bbox': (120, -10, 160, 10), 'limit': 100, 'offset': 0}

	StudyID	StudyName	EarliestYearBP	MostRecentYearBP	EarliestYearCE	MostRecentYearCE	Coverage [S, N, W, E]	StudyNotes	ScienceKeywords	Investigators	Publications	Sites	Funding	CollectionMembers
0	954692	Oxygen isotope ratios of planktonic and benthi...	NaN	NaN	NaN	NaN	None	A precise age model of marine sediment core is...	[Foraminifera, G. ruber, oxygen isotope, Sedim...	Kubota, Kaoru, Yokoyama, Yusuke, Ishikawa, Tsu...	Kubota, Kaoru; Yokoyama, Yusuke; Ishikawa, Tsu...	[]	[]	[954630, 954649, 954661, 954686]
1	971539	Age model, carbonate mass accumulation rates a...	NaN	NaN	NaN	NaN	None	The Biogenic Bloom is a paleoceanographic phen...	[Benthic foraminifera, Biogenic bloom, Early P...	Gastaldello, Maria Elena, Agnini, Claudia, Wes...	Gastaldello, Maria Elena; Agnini, Claudia; Wes...	[]	[]	[971528, 971532, 971534, 971535, 971536, 971538]
2	933340	Mg/Ca, Sr/Ca, Mn/Ca ratios measured in plankto...	NaN	NaN	NaN	NaN	None	This dataset contains Mg/Ca, Sr/Ca and Mn/Ca d...	[Clumped isotopes, Mg/Ca ratios, Planktonic fo...	Meinicke, Niklas, Reimi, Maria A, Ravelo, Ana ...	Meinicke, Niklas; Reimi, Maria A; Ravelo, Ana ...	[]	[{'name': 'Integrated Ocean Drilling Program /...	[933338, 933339]
3	983391	Arid Central Asian Data Base (ACADB) for surfa...	NaN	NaN	NaN	NaN	None	The dataset combine lipid biomarkers from surf...	[Arid Central Asia, Aridity, Biomarkers, brGDG...	Dugerdil, Lucas, Joannin, Sébastien, Peyron, O...	Dugerdil, Lucas; Joannin, Sébastien; Peyron, O...	[]	[]	[983366, 983367, 983386]
4	887764	Stable oxygen isotopes and Mg/Ca in planktic f...	NaN	NaN	NaN	NaN	None	Mg/Ca and stable oxygen isotope compositions (...	[]	Hollstein, Martina, Mohtadi, Mahyar, Rosenthal...	Hollstein, Martina; Mohtadi, Mahyar; Rosenthal...	[]	[{'name': 'Center for Marine Environmental Sci...	[887736, 887755, 887759]