FetchClimate Overview
Contents
1. day FetchClimateYearly splits the years interval with a step specified in dyear paramerer FetchClimateSeasonly splits subinterval of days within each year into several subintervals with a step of dday FetchClimateHourly splits subinterval of hours within each day into several subintrervals with a step of dhours If the interval to split is not multiple of a step the later bound of last subinterval can be trimmed not to exceed the later bound public static double FetchClimateYearly ClimateParameter p double latmin double latmax double lonmin double lonmax int hourmin int hourmax 24 int daymin 1 int daymax 11 FetchClimate overview version 1 2 2011 Microsoft Corporation GlobalConsts DefaultValue int yearmin 1961 int yearmax 1990 int dyear 1 EnvironmentalDataSource dataSource EnvironmentalDataSource ANY public static double FetchClimateSeasonly ClimateParameter p double latmin double latmax double lonmin double lonmax int hourmin int hourmax 24 int daymin 1 int daymax GlobalConsts DefaultValue int yearmin 1961 int yearmax 1990 int dday 1 EnvironmentalDataSource dataSource EnvironmentalDataSource ANY public static double FetchClimateHourly ClimateParameter p double latmin double latmax double lonmin double lonmax int hourmin int hourmax 24 int daymin 1 int daymax GlobalConsts DefaultValue int yearmin 1961 int yearmax 1990 int dhour 1 Envi2. int hourmin int hourmax int daymin int daymax int yearmin int yearmax double dhour Other functions bool is_missing value double value Functions parameters description Paramenter Description Allowed values p An integer setting up what climate FC_TEMPERATURE FC_PRECIPITATION parameter needs to be fetched It is FC LAND_AIR_TEMPERATURE FC_OCEAN_AIR_TEMPERATURE FC_ELEVATION FC_LAND_ELEVATION FC_OCEAN DEPTH FC_SOIL_MOISTURE FC_RELATIVE_HUMIDITY FC_LAND_AIR_RELATIVE_HUMIDITY EC LAND WIND SPEED usually set up with one of the predefined enum values 5 FetchClimate overview version 1 2 2011 Microsoft Corporation Paramenter Description Allowed values Latmin The bottom bound value in degrees 90 90 inclusive of requested spatial rectangle for calculating mean climate parameter value Lonmin The left bound value in degrees of 180 180 or 0 360 requested spatial rectangle for Lonmin and Lonmax must follow the same calculating mean climate parameter notation You must use either 180 180 or 0 360 value notation in both Lonmin and Lonmax dot a step of latitude splitting that willbe more than 0 used to produce grid The first dimension of the output grid that corresponds to latitude will have a length equal to latmax latmin dlat Latmax value will be corrected to keep latmax latmin dlat as integer value FetchClimate overview version 1 2 2011 Micro
3. of August the result will be generated using mean temperature of June July and August with corresponding weights 0 7 1 and 0 32 Weight of June requested days in June total days in June 21 30 0 7 Weight of July requested days in July total days in July 31 31 1 Weight of August requested days in August total days in August 10 31 0 32 The resulting mean value will be the following JuneTemp 0 7 JulyTemp 1 AugustTemp 0 32 0 7 1 0 32 13 FetchClimate overview version 1 2 2011 Microsoft Corporation Time aggregated observations GHCN GHCN Data source uses only those stations to get a result for the request that contain continuous timeseries e g all requested months for all requested years are present in the data If at least one of the requested months of any of the requested years is absent for some station in the requested spatial region the station data will be ignored Major effect for precision calculation for GHCN data source is caused by station density in a region So it is likely that GHCN data source will only be used in the high station density regions e g USA or if other data sources fail their calculations for the particular request 14
4. static double FetchClimate ClimateParameter parameter double latmin double latmax double lonmin double lonmax int starthour null int stophour null int startday null int stopday null int startyear null int stopyear null EnvironmentalDataSource dataSource EnvironmentalDataSource ANY Fetch estimated uncertainties in a batch request public static double FetchClimateUncertainty ClimateParameter parameter double latmin double latmax double lonmin double lonmax int starthour null int stophour 10 FetchClimate overview version 1 2 2011 Microsoft Corporation null int startday null int stopday null int startyear null int stopyear null EnvironmentalDataSource dataSource EnvironmentalDataSource ANY Fetch data sources in a batch request public static string FetchClimateProvenance ClimateParameter parameter double latmin double latmax double lonmin double lonmax int starthour null int stophour null int startday null int stopday null int startyear null int stopyear null EnvironmentalDataSource dataSource EnvironmentalDataSource ANY Grid requests With a grid request it is possible to fetch mean values of some environmental variable for the cells of a grid specified Each value of the resulting array is a mean value for corresponding grid cell The Grid is defined by its spatial bounds by a s
5. FetchClimate Overview version 1 2 FetchClimate is a combination of cloud based service and a programmatic cloud that fetches necessary environmental data from multiple publicly available data sources FetchClimate can be accessed from anywhere either through a simple web interface or via a few lines of code inside any net program e any geographical region at any grid resolution from global through continental to a few kilometres e any range of years 1900 2010 days within the year and or hours within the day e wide range of environmental variables for both land and ocean e automatic selection of the most appropriate source data e uncertainty and provenance returned along with the climate information e entire query can be shared as a single URL enabling others to retrieve the identical data e retrieval times vary but are always orders of magnitude faster than doing this kind of thing the hard way This document covets what s necessary to run FetchClimate from your program or from OS command prompt Contents Getting Started EE CommMarnid Prompt QUEM e E E 3 etehielimmate from CF Fasusi A R 3 Fetch climate from C Visual Basic F and other NET languages ENEE 4 FetchClimate E KINN ssssssssisessssssesstsstaesizerseastiessesstitseavesasedesatusavesetsadbaradeavassadestosaisvedesvissednsndonssavadesvessedavsevadiavavessidsavasdieadearaieaasseies 4 EE eege eeh 4 ER ninaa araia NANA eas iavaeasnaeanasanieaberasaarnsaanasab A
6. REE 5 EE EE 5 Eeer 5 Functions PAAMEtSLS ESCH HON E 5 Climate variables descriptoniccidncidindidiiidaidhalinaadinsdhabdnnaianhdin adie dauidusinnel ately 8 COMENS sde 9 FetchClimate C API Procedural sssoscososessonnono n n asiaa ieir EENS FetchClimate overview version 1 2 2011 Microsoft Corporation SINGLE aloi AEE 10 Batch eege eet 10 ER E 11 EE EE 11 Missin ovale rer 12 Command BO General NOES annn ninnan NEEE EREEREER REEE EEE EEEE REEE Gridded interpolated station data data sources WorldClim CRU CL 2Uh NENNEN 13 Time aggregated observations GHCN ees 14 FetchClimate overview version 1 2 2011 Microsoft Corporation Getting started FetchClimate runs on any Microsoft Windows computer which is connected to Internet and has Microsoft NET Framework 4 0 installed You will need only one file fetchclimate exe to run FetchClimate queries The fetchclimate h file simplifies the use of the library in C code This introductory section assumes you have Microsoft Visual Studio or Microsoft Visual Studio Express installed on your computer Command prompt queries The following command gets interpolated mean annual temperature at latitude 52 2 longitude 0 1 Cambridge UK for 30 years since 1961 gt fetchclimate t 52 2 0 1 Fetching FC_TEMPERATURE for 1 regions for whole days for whole years for years f rom 1961 till 1990 Progress 0 100 0 FetchClimate client version 1 2 1193 0 FetchC
7. e latmax double lonmin double lonmax int hourmin int hourmax int daymin int daymax int yearmin int yearmax double dlat double dlon double FetchClimateGridEx int p double latmin double latmax double lonmin double lonmax int hourmin int hourmax int daymin int daymax int yearmin int yearmax double dlat double dlon TimeSeries requests void FetchClimateYearly double result int result_len int p double latmin double latmax double lonmin double lonmax int hourmin int hourmax int daymin int daymax int yearmin yearmax double dyear void FetchClimateSeasonly double result int result_len int p double latmin double latmax double lonmin double lonmax int hourmin int hourmax int daymin int daymax int yearmin int yearmax double dday void FetchClimateHourly double result int result_len int p double latmin double latmax double lonmin double lonmax int hourmin int hourmax int daymin int daymax int yearmin int yearmax double dhour double FetchClimateYearlyEx int p double latmin double latmax double lonmin double lonmax int hourmin int hourmax int daymin int daymax int yearmin yearmax double dyear double FetchClimateSeasonlyEx p double latmin double latmax double lonmin double lonmax int hourmin int hourmax int daymin int daymax int yearmin int yearmax double dday double FetchClimateHourlyEx p double latmin double latmax double lonmin double lonmax
8. etching uncertainties and provenance are described below Single region Fetching a mean value of specified environmental variable for one region public static double FetchClimate ClimateParameter parameter double latmin double latmax double lonmin double lonmax int starthour 0 int stophour 24 int startday 1 int stopday GlobalConsts DefaultValue int startyear 1961 int stopyear 1990 EnvironmentalDataSource dataSource EnvironmentalDataSource ANY Fetching an estimated uncertainty for single region request public static double FetchClimateUncertainty ClimateParameter parameter double latmin double latmax double lonmin double lonmax int starthour int stophour 24 int startday 1 int stopday GlobalConsts DefaultValue int startyear 1961 int stopyear 1990 EnvironmentalDataSource dataSource EnvironmentalDataSource ANY Fetching a result provenance for single region request public static string FetchClimateProvenance ClimateParameter parameter double latmin double latmax double lonmin double lonmax int starthour int stophour 24 int startday 1 int stopday GlobalConsts DefaultValue int startyear 1961 int stopyear 1990 EnvironmentalDataSource dataSource EnvironmentalDataSource ANY Batch request Perform a batch request fetch mean values of an environmental variable for several regions specifying time intervals for each particular region public
9. her NET languages Reference fetchclimate exe assembly in your Microsoft Visual Studio project The API is in Microsoft Research Science Data namespace As an example a CH program that prints interpolated mean annual temperature at latitude 52 2 longitude 0 1 Cambridge UK for 30 years since 1961 may look like this using System using Microsoft Research Science Data namespace CS Sample static void Main string args double t ClimateService FetchClimate ClimateParameter FC_TEMPERATURE 52 2 52 2 1 0 1 Console WriteLine t Below is an equivalent F script r FetchClimate exe open Microsoft Research Science Data printf f n ClimateService FetchClimate ClimateParameter FC_TEMPERATURE 52 2 52 2 0 1 0 1 999 999 999 999 1961 1990 EnvironmentalDataSource ANY FetchClimate C API Single value double fetch_climate int p double latmin double latmax double lonmin double lonmax int hourmin int hourmax int daymin int daymax int yearmin int yearmax Batch request double FetchClimateN int p double latmin double latmax double lonmin double lonmax int hourmin int hourmax int daymin int daymax int yearmin int yearmax int N FetchClimate overview version 1 2 2011 Microsoft Corporation Grid requests void FetchClimateGrid double grid int grid_dim1 int grid_dim2 int p double latmin doubl
10. limate service version 1 2 875 0 Region 1 point 52 2 0 1 9 717 0 527 C To get this result he program passes parameters to FetchClimate service which does all the work Invoke fetchclimate without parameters to learn how to ask for specific climate data Fetch climate from C You will need Microsoft Visual C compiler to run FetchClimate queries Below is a minimum C program that prints interpolated mean annual temperature at latitude 52 2 longitude 0 1 Cambridge UK for 30 years since 1961 include lt stdio h gt include fetchclimate h int main int argc char argv double t fetch_climate FC_TEMPERATURE 52 2 52 2 0 1 9 1 FC_NOVALUE FC_NOVALUE FC_NOVALUE FC_NOVALUE 1961 1990 printf 1f t return The number being printed is 9 716667 FetchClimate overview version 1 2 2011 Microsoft Corporation You have to enable compiler Common Language Runtime support clr option and ensure that fetchclimate exe file is available both during compile and at run time At compile time you may place fetchclimate exe in current directory There are also several other options Look into Visual C documentation for fusing directive At runtime the fetchclimate exe file must be at the same directory as the executable program itself or it can be in any directory list in PATH environmental variable Fetch climate from C Visual Basic F and ot
11. n in month FC_LAND_SUN_PERCENTAGE Sunshine percentage of L Percentage maximum possible sunshine during a day Comments If pair hourmin hourmax is set to C_NOVALUE FC_NOVALUE or 0 24 then the data for whole day will be used in calculation If pair daymin daymax is set to FC_NOVALUE FC_NOVALUE then the whole year will be used in calculation FetchClimate C API Procedural To use FetchClimate CH API we need to create NET 4 0 project and add a reference to FetchClimate exe assembly Procedural API consists of static methods of ClimateService class of Microsoft Research Science Data namespace FetchClimate overview version 1 2 2011 Microsoft Corporation All methods require only climate variable specification and region specification as mandatory parameters Time interval specification is optional If not specified it is considered to be a continuous period from 1961 to 1990 Time interval can be refined by modifying default values of the following parameters starthour stophour startday stopday startyear stopyeat As well as time interval we can specify a data source to use for calculation through an optional dataSource parameters The default parameter value is EnvironmentalDataSource ANY means that most accurate data source should be chosen automatically With a FetchClimate C procedural API it is possible to fetch uncertainties and provenance of the mean values as well as mean values themselves Methods for f
12. o annotated CSV readable by SDS as a dataset The below command line syntax is printed if you invoke FetchClimate exe without parameters FetchClimate clearcache FetchClimate lt parameter gt lt TimeSpec gt lt RegionSpec gt lt RegionSpec gt export plain annotated FILENAME dsv lt RegionSpec gt lt PointSpec gt lt RectSpec gt lt GridSpec gt lt PointSpec gt lt lat gt lt lon gt lt RectSpec gt lt latMin gt lt latMax gt lt lonmMin gt lt lonMax gt lt GridSpec gt lt latMin gt lt latStep gt lt latMax gt lt lonMin gt lt lonStep gt lt lonMax gt 12 FetchClimate overview version 1 2 2011 Microsoft Corporation lt TimeSpec gt years lt yearmin gt lt yearmax gt days lt daymin gt lt daymax gt hou rs lt hourmin gt lt hourmax gt lt TimeSeriesSpec gt lt TimeSeriesSpec gt ty lt YearStep gt ts lt DayStep gt th lt HourStep gt lt parameter gt t FC_TEMPERATURE p FC_PRECIPITATION 1t FC_LAND_AIR_TEMPERATU RE ot FC_OCEAN_AIR_TEMPERATURE e FC_ELEVATION 1e FC_LAND_ELEVATION od FC_OCEAN_D EPTH sm FC_SOIL_MOISTURE rh FC_RELATIVE_HUMIDITY 1rh FC_LAND_AIR_RELATIVE_HUMIDI TY lwnd FC_LAND_WIND_SPEED 1dtr FC_LAND_DIURNAL_TEMPERATURE_RANGE 1fdf FC_LAND_F ROST_DAY_FREQUENCY 1wdf FC_LAND_WET_DAY_FREQUENCY 1sp FC_LAND_SUN_PERCENTAGE clearecache clear client side cache ty lt YearStep gt perform yearly timeseries req
13. ronmentalDataSource dataSource EnvironmentalDataSource ANY Get corresponing uncertatinty and provenance values the following methods can be used For yearly timeseries FetchClimateYearlyUncertainty FetchClimateYearlyProvenance For seasonly timeseries FetchClimateSeasonlyUncertatinty FetchClimateSeasonlyProvenance For hourly timeseries FetchClimateHourlyUncertainty FetchClimateHourlyProvenance Missing value handling Missing value is supposed to appear in case of fetching coverage specific i e only land without an ocean parameter for area with different coverage For instance fetching over land air temperature for ocean area will return missing value In C API the values returned by the service should be checked by is_missing_value function In CH API the values containing missing values equal to double NAN Command line interface FetchClimate exe can also be used from a command prompt or a batch file Command line parameters specify which data to fetch and where the result will go At a minimum you have to specify climate variable and one geographical region Default time interval is set to continuous years from 1961 to 1990 and can be overridden When several spatial regions are specified on a command line one climate variable and time interval are applied to all requested spatial regions By default FetchClimate exe prints the formatted result to standard output The result can also be exported either to plain CSV file or t
14. soft Corporation Paramenter Description Allowed values Hourmin A lower inclusive bound of time 0 24 or FC_NOVALUE in C interval in a day that will be used for calculation It can be set to FC_NOVALUE that will be treated as Daymin A number of the day in the year that 1 365 366 or FC_NOVALUE in C will be the first day within each year if query covers a single year the maximum value of the requested time period Itcan of Daymin can be 365 if the year is not leap or 366 be set to FC_NOVALUE that will if the year is leap be treated as the 1th of January If query covers several years it is assumed that all years are not leap and maximum value of Daymin must be less or equal to 365 yearmin The number of year that willbe the 1 9999 first year in the requested period grid A pointer to the preallocated array where the result data will be put in the grid request functions grid_dim1 The length of the first dimension of preallocated array where the result FetchClimate overview version 1 2 2011 Microsoft Corporation Paramenter Description Allowed values will be put in the grid request functions result_Len The length of the preallocated array where the result will be put in the time series request functions dyear A value that divides yearmin yearmax interval into periods of dyear length to form output grid A value that divides hourmin hourmax in
15. tep along latitude and by a step along longitude Fetching mean values of a climate variable public static double FetchClimateGrid ClimateParameter parameter double latmin double latmax double lonmin double lonmax double dlat double dlon int hourmin int hourmax 24 int daymin 1 int daymax GlobalConsts DefaultValue int yearmin 1961 int yearmax 1998 EnvironmentalDataSource dataSource EnvironmentalDataSource ANY Fetching an uncertainties array for grid request values public static double FetchUncertaintyGrid ClimateParameter parameter double latmin double latmax double lonmin double lonmax double dlat double dlon int hourmin int hourmax 24 int daymin 1 int daymax GlobalConsts DefaultValue int yearmin 1961 int yearmax 1998 EnvironmentalDataSource dataSource EnvironmentalDataSource ANY Fetching a provenance array for grid request values public static string FetchProvenanceGrid ClimateParameter parameter double latmin double latmax double lonmin double lonmax double dlat double dlon int hourmin int hourmax 24 int daymin 1 int daymax GlobalConsts DefaultValue int yearmin 1961 int yearmax 1998 EnvironmentalDataSource dataSource EnvironmentalDataSource ANY Time series requests Time series requests give an ability to split single request into several requests either along years or along days within year or along hours within
16. terval into periods of dhour length to form output grid Climate variables description FetchClimate supports different coverage types e Only land area in the requested spatial region L e Only ocean area in the requested spatial region O e Both land and ocean W The following table describes the mapping of FetchClimate API parameter to corresponding climate parameter and coverage type Fetch Climate API Parameter Climate parameter Coverage Default units type FC LAND AIR TEMPERATURE Near surface air L Degrees Celsius temperature 8 FetchClimate overview version 1 2 2011 Microsoft Corporation Fetch Climate API Parameter Climate parameter Coverage Default units type FC_OCEAN_AIR_TEMPERATURE Near surfaceair 1 Degrees Celsius temperature FC_PRECIPITATION Near surface precipitation W mm month tate FC_SOIL_MOISTURE Soil moisture upper soil L mm m layers FC_ELEVATION Earth surface elevation W meters land and ocean FC_LAND_ELEVATION Land elevation above sea L meters level FC_OCEAN_DEPTH Bathymetry O meters FC_LAND_AIR_RELATIVE_HUMIDITY Air related humidity near L percentage surface FC_LAND_WIND_SPEED Wind speed near surface L Meters second FC_LAND_DIURNAL_TEMPERATURE_RANGE Diurnal temperature L Degrees Celsius range FC_LAND_FROST_DAY_FREQUENCY Number of days with L Days per month ground frost in month FC_LAND_WET_DAY_FREQUENCY Number of days with L Days per month precipitatio
17. uest by dividing specified years into lt YearStep gt long subintervals ts lt DayStep gt perform seasonly timeseries request by dividing specifie d days into lt DaysStep gt long subintervals th lt HourStep gt perform hourly timeseries request by dividing specified hours into lt HourStep gt long subintervals and add an additional region to fetch If lt TimeSpec gt is omitted the mean value for whole years from 1961 to 1990 is fetched General notes Service works with 8 data sources They are NCEP Reanalysis 1 CRU CL 2 0 WorldClim 30s GHCN v2 CPC Soil Moisture GTOPO30 and ETOPO1 All time is now interpreted as UTC time If you specify morning hours in your request while requesting a wide spatial area the result that will be returned won t correspond to average morning time for this area It will contain an average for specified UTC hours across whole region Gridded interpolated station data data sources WorldClim CRU CL 2 0 Data sources with Gridded interpolated station data like WorldClim or CRU will not calculate a mean value for a region containing missing value e g water area some other less accurate data source will be used to get a value for this type of regions If the requested days of year do not fit month bound monthly average values will be weighted according to the length of submonth period For example in the case of requesting mean temperature for days from the 10 of June to the 10
Download Pdf Manuals
Related Search