File Format Specification for Altimetry, GMB, Mass Budget
Note that the format for IMBIE-3(2023) has slightly changed since previous IMBIE inter-comparisons to help identify ambiguous entries which were previously difficult to detect.
We now require strict format and parameter value compliance, which we automatically check when you upload the file. In previous IMBIE submissions there was quite a wide interpretation of the submitted file formats by participants, often including format or value errors which required a large effort by the IMBIE team to manually check and correct many of the submissions. In IMBIE-3(2023) we hope to avoid this by performing stricter initial checks, reduce potential post-processing issues, and focus our efforts on the final mass balance analysis.
Contents
- File Types
- General CSV File Requirements
- Time-series of Mass Change : dM(t)
- Rates of Mass Change : dM/dt
- Basins and Region Sets
File Types
The following file types apply for Altimetry, Gravimetry and Mass Budget submissions:
| Type | Description | Format |
|---|---|---|
| Time-series of Mass Change | Single file containing dM(t), uncertainty, and area stats, including all your chosen submitted regions and basins of AIS and/or GrIS | 10-column CSV |
| Rates of Mass Change | Single file containing dM/dt, uncertainty and area stats, including all your chosen submitted regions and basins of AIS and/or GrIS | 11-column CSV |
You may submit either :
- a mass change time-series file and a mass rate file, or
- just a mass change time-series file, or
- just a mass rates file
If you submit just the mass change time-series file, we will calculate the mass rates file for you. You may prefer that your own method of converting mass change to mass rates and integrating their uncertainties is used. If this is the case please submit the mass rates file.
General CSV File Requirements
IMBIE-3 (2023) file CSV file formats have the following general requirements, some of which are new in IMBIE-3 (2023):
- CSV format file names must end in .csv (we do not accept any other end strings such as .txt).
- CSV files should use UTF-8 character encoding (this is normally the default used by most modern programming languages).
- A single line header is optional, but recommended to label your columns. (ie surname,group,ice_sheet,...). We ignore this line if it is present, but it can be useful if we need to investigate any anomalies in your file.
- CSV format files must contain comma separated values or strings. (ie String,Value,Value,...). No other delimiters are allowed.
- You may leave spaces either side of a string or value, but not in the middle of a string unless a multi-word string is expected. ie spacing such as : String, Value, Value ,... is allowed.
- Comment lines are allowed anywhere in the file. These lines must start with a # character as the first character. We ignore these lines.
- CSV files must not contain additional columns. The number of columns and the column order must exactly match the specification below.
- You must not include commas or any special characters (*/\'"_+) in your values or strings unless explicitly allowed below.
- Positive numerical values should not include the + sign.
- Floating point numbers should be represented by standard (not exponential) numbering. ie 123456.0 and not 1.234560+e05
- Do not include any commas in numerical values. ie use 10000 and not 10,000.
- Empty column entries are not allowed unless explicitly specified in the format description.
- Do not include NaN values.
Time-series of Mass Change : dM(t) File Format
The general CSV requirements described above apply to this file.
File Name
The file name should be of the form: anystring.csv
You can choose your own name for the anystring part, but we suggest you make the file name informative. You must not include space characters in your file name or any special characters other than '_' or '-'. A good example for an Altimetry submission from lead author 'Smith' would be: smith_imbie4_altimetry_mass_change_ts.csv
File Contents
- For each drainage basin or ice sheet region include one row per available measurement time of mass change.
- Only one file can be submitted, so include all your areas for Antarctica and/or Greenland in this file.
- If you provide the time-series over all the basins that make up an ice sheet, please also provide the total mass change timeseries for the corresponding ice sheet in the file. So, for example, if you provide a timeseries (multiple rows) for every Zwally Antarctic basins '1' to '27', also provide a timeseries (multiple rows) for regions 'AIS', and optionally 'EAIS','WAIS','APIS'. If you provide all Zwally or Rignot Greenland basins also provide a timeseries for region 'GRIS'.
Format
The Mass Time Series CSV file is comprised of exactly 10 comma separated columns in the order shown. Do not include an index (column number) column. Note that the number of columns has increased since IMBIE-3 with an additional column inserted.
Example
Here is a shortened conformant example file contents (a real file would have many more rows). Note that values are not real, header(1st line) and comment(#) lines are optional.
surname,group,ice_sheet,basin_type,region_id,area,area_observed,date,mass_change,mass_change_uncert
# Zwally AIS
Shepherd,Altimetry,Antarctica,Zwally,AIS,11892543,10345765,1992.370,993,217
Shepherd,Altimetry,Antarctica,Zwally,AIS,11892543,10341234,1992.454,1023,224
# Rignot EAIS
Shepherd,Altimetry,Antarctica,Rignot,EAIS,9910012,9810012,1999.625,65.506,50.382
Shepherd,Altimetry,Antarctica,Rignot,EAIS,9910012,9802012,2000.354,-74.290,50.356
Column Format Specification
Each data row of the .csv file must contain the following columns:
| Column Number | Column Name | Description | Allowed Values |
|---|---|---|---|
| 1 | surname | Surname of lead author | Single word string with no space characters between words. You may include a hyphen - character, but do not include special characters [* _ /]. Only include the lead author of the data. You can attribute other authors in the submission questions. |
| 2 | group | Experiment group name. | A string containing one of 'Altimetry', 'Gravimetry', or 'Mass Budget'. Do not include the quote marks. Do include the space character between Mass and Budget. These are case sensitive, so 'altimetry' will not be accepted. All column 2 entries in the file must be the same. You can not have more than one group in the file. |
| 3 | ice_sheet | Area of this row is contained within Antarctica or Greenland | A string containing one of 'Antarctica', or 'Greenland'. Do not include the quote marks. Case sensitive. Note that this is a new column in IMBIE-3 (2023). |
| 4 | basin_type | Drainage Region Set employed (Zwally or Rignot) | A string containing one of 'Zwally', or 'Rignot'. Do not include the quote marks. Case sensitive. |
| 5 | region_id | Drainage Region ID | A single string containing one of the strings shown below within the quote marks (do not include the quote marks). Please take care to be exact.
Zwally Antarctic basin numbers: '1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12', '13', '14', '15', '16', '17', '18', '19', '20', '21', '22', '23', '24', '25', '26', '27', or Zwally Antarctic regions: 'AIS', 'EAIS', 'WAIS', 'APIS', or Rignot Antarctic basins: 'H-Hp', 'F-G', 'E-Ep', 'D-Dp', 'Cp-D', 'B-C', 'A-Ap', 'Jpp-K', 'G-H', 'Dp-E', 'Ap-B', 'C-Cp', 'K-A', 'J-Jpp', 'Ipp-J', 'I-Ipp', 'Hp-I', 'Ep-F', or Rignot Antarctic regions: 'AIS', 'EAIS', 'WAIS', 'APIS', or Zwally Greenland basins or regions: '1.1', '1.2', '1.3', '1.4', '2.1', '2.2', '3.1', '3.2', '3.3', '4.1', '4.2', '4.3', '5.0', '6.1', '6.2', '7.1', '7.2', '8.1', '8.2', or Zwally Greenland regions : '1', '2', '3', '4', '5', '6', '7', '8' (now allowed in IMBIE-3),or Zwally Greenland regions : 'GRIS', or Rignot Greenland regions: 'NO', 'NE', 'SE', 'SW', 'CW', 'NW', or Rignot Greenland regions: 'GRIS' Note in particular that the Greenland ice sheet is specified by 'GRIS' only (not GIS,GrIS,etc) These are all case sensitive. Do not zero pad basin strings with numerical values ie '01' instead of '1'. Please take care to get these strings exact. For more information on the drainage basins used please see this link. |
| 6 | area | Drainage Region Area (in square kilometres). This is the full area of the region chosen in column 5. | A numerical value in units of Km2. Float or Integer, ie '11892542' or '11892542.0'. Do not include units, other text or the quote marks. Do not use exponential formats such as : '1.1892542e+06'. Do not use commas in the number such as '11,892,542' |
| 7 | area_observed | Drainage Region Area Observed by your satellite dataset (in square kilometres). This is area of the region chosen in column 5 that is actually observed and may be less than the full area in column 6. | A numerical value in units of Km2. Float or Integer, ie '11892542' or '11892542.0'. Do not include units, other text or the quote marks. Do not use exponential formats such as : 1.1892542e+06.Do not use commas in the number such as '11,892,542' |
| 8 | date | Date for this entry in your time series (in decimal years). | A numerical value in units of years in the format 'YYYY.yy'. Float, ie '1991.23' or '2023.96'. Do not include units, other text or the quote marks. |
| 9 | mass_change | the Relative Mass Change for each entry in your time series (in gigatons). | A numerical value in units of gigatons. Float, ie '-100.45' or '303.76' Do not include units, other text or the quote marks. Do not include the '+' character. |
| 10 | mass_change_uncert | Relative Mass Change Uncertainty for each entry in your time series (in gigatons). | A numerical value in units of gigatons. Float, ie '-100.45' or '303.76' Do not include units, other text or the quote marks. Do not include the '+' character. |
Rates of Mass Change : dM/dt File Format
The general CSV requirements described above apply to this file.
File Name
The file name should be of the form: anystring.csv
You can choose your own name for the anystring part, but we suggest you make the file name informative. You must not include space characters in your file name or any special characters other than '_' or '-'. A good example for an Altimetry submission from lead author 'Smith' would be: smith_imbie4_altimetry_mass_rates.csv
File Contents
- Please provide discrete rates of mass change (no overlapping time intervals) at the finest temporal resolution afforded by your dataset, preferably over annual epochs or finer temporal duration. If you submit annual rates of mass change, please provide summer-centred rates.
- For each drainage basin or ice sheet region include one row per available measurement period of mass rate change.
- Only one file can be submitted, so include all your areas for Antarctica and/or Greenland in this file.
- If you provide the rates of mass change over all the basins that make up an ice sheet, please also provide the rates of total mass change for the corresponding ice sheet. So, for example, if you provide rates of mass change (dM/dt) (multiple rows) for every Zwally Antarctic basins '1' to '27', also provide a rate (dM/dt) (multiple rows) for regions 'AIS', 'EAIS','WAIS','APIS'. If you provide all Zwally or Rignot Greenland basins also provide a rate for region 'GRIS'.
Format
The rate of mass change CSV file is comprised of exactly 11 comma separated columns in the order shown. Do not include an index (column number) column. Note that the number of columns has increased since IMBIE-3 with an additional column inserted.
Example
Here is a shortened conformant example file contents (a real file would have many more rows). Note that values are not real, header(1st line) and comment(#) lines are optional.
surname,group,ice_sheet,basin_type,region_id,area,area_observed,start_date,end_date,mass_rate,mass_rate_uncert
# Zwally AIS
Shepherd,Altimetry,Antarctica,Zwally,AIS,11892543,10345765,1992.0,1993.0,24.0,43.7
Shepherd,Altimetry,Antarctica,Zwally,AIS,11892543,10341234,1993.0,1994.0,34.0,19.7
# Rignot EAIS
Shepherd,Altimetry,Antarctica,Rignot,EAIS,9910012,9810012,1994.0,1995.0,65.506,50.382
Shepherd,Altimetry,Antarctica,Rignot,EAIS,9910012,9802012,1995.0,1996.0,-74.290,50.356
Column Format Specification
Each data row of the .csv file must contain the following columns:
| Column Number | Column Name | Description | Allowed Values |
|---|---|---|---|
| 1 | surname | Surname of lead author | Single word string with no space characters between words. You may include a hyphen - character, but do not include special characters [* _ /]. Only include the lead author of the data. You can attribute other authors in the submission questions. |
| 2 | group | Experiment group name. | A string containing one of 'Altimetry', 'Gravimetry', or 'Mass Budget'. Do not include the quote marks. Do include the space character between Mass and Budget. These are case sensitive, so 'altimetry' will not be accepted. All column 2 entries in the file must be the same. You can not have more than one group in the file. |
| 3 | ice_sheet | Area of this row is contained within Antarctica or Greenland | A string containing one of 'Antarctica', or 'Greenland'. Do not include the quote marks. Case sensitive. Note that this is a new column in IMBIE-3. |
| 4 | basin_type | Drainage Region Set employed (Zwally or Rignot) | A string containing one of 'Zwally', or 'Rignot'. Do not include the quote marks. Case sensitive. |
| 5 | region_id | Drainage Region ID | A single string containing one of the strings shown below within the quote marks:
Zwally Antarctic basin numbers: '1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12', '13', '14', '15', '16', '17', '18', '19', '20', '21', '22', '23', '24', '25', '26', '27', or Zwally Antarctic regions: 'AIS', 'EAIS', 'WAIS', 'APIS', or Rignot Antarctic basins: 'H-Hp', 'F-G', 'E-Ep', 'D-Dp', 'Cp-D', 'B-C', 'A-Ap', 'Jpp-K', 'G-H', 'Dp-E', 'Ap-B', 'C-Cp', 'K-A', 'J-Jpp', 'Ipp-J', 'I-Ipp', 'Hp-I', 'Ep-F', or Rignot Antarctic regions: 'AIS', 'EAIS', 'WAIS', 'APIS', or Zwally Greenland basins or regions: '1.1', '1.2', '1.3', '1.4', '2.1', '2.2', '3.1', '3.2', '3.3', '4.1', '4.2', '4.3', '5.0', '6.1', '6.2', '7.1', '7.2', '8.1', '8.2', or Zwally Greenland regions : '1', '2', '3', '4', '5', '6', '7', '8' (now allowed in IMBIE-3),or Zwally Greenland regions : 'GRIS', or Rignot Greenland regions: 'NO', 'NE', 'SE', 'SW', 'CW', 'NW', or Rignot Greenland regions: 'GRIS' Do not include the quote marks. Case sensitive. Do not zero pad basin strings with numerical values ie '01' instead of '1'. Please take care to get these strings exact. For more information on the drainage basins used please see this link. |
| 6 | area | Drainage Region Area (in square kilometres). This is the full area of the region chosen in column 5. | A numerical value in units of Km2. Float or Integer, ie '11892542' or '11892542.0'. Do not include units, other text or the quote marks. Do not use exponential formats such as : '1.1892542e+06'. Do not use commas in the number such as '11,892,542' |
| 7 | area_observed | Drainage Region Area Observed by your satellite dataset (in square kilometres). This is area of the region chosen in column 5 that is actually observed and may be less than the full area in column 6. | A numerical value in units of Km2. Float or Integer, ie '11892542' or '11892542.0'. Do not include units, other text or the quote marks. Do not use exponential formats such as : 1.1892542e+06.Do not use commas in the number such as '11,892,542' |
| 8 | start_date | Start date for this row's interval in your mass trend time series (in decimal years). | A numerical value in units of years in the format 'YYYY.yy'. Float, ie '1991.23' or '2023.96'. Do not include units, other text or the quote marks. |
| 9 | end_date | End date for this row's interval in your mass trend time series (in decimal years). | A numerical value in units of years in the format 'YYYY.yy'. Float, ie '1991.23' or '2023.96'. Do not include units, other text or the quote marks. |
| 9 | mass_rate | the Rate of Mass Change for each interval in your mass trend time series (in gigatons per year),. | A numerical value in units of gigatons per year. Float, ie '-100.45' or '303.76' Do not include units, other text or the quote marks. Do not include the '+' character. |
| 10 | mass_rate_uncert | the Rate of Mass Uncertainty for each entry in your mass trend time series (in gigatons per year). | A numerical value in units of gigatons per year. Float, ie '-100.45' or '303.76' Do not include units, other text or the quote marks. Do not include the '+' character. |
Basins and Region Sets
This section provides information and links to information on the regions sets and drainage basins used in IMBIE-3 file formats.
Region Sets
IMBIE-3 uses two sets ('Zwally' and 'Rignot') of grounded ice area and drainage basin definitions for Antarctica and Greenland. The first set, mapped by Zwally et al., (2012), were used in IMBIE 2012 and are retained for consistency. The second set, mapped by Rignot et al. (2016), are an updated definition. All participants are required to post their results on both sets of drainage basins.
Drainage Basins
Zwally Basins
The drainage basins were delineated based on ice provenance using surface elevation data derived from ICESat.
Zwally Antarctic Basins
The definitions include 27 basins in Antarctica ('1' to '27' in IMBIE-3 file formats) with the East and West Antarctic Ice Sheets (EAIS and WAIS, respectively) separated approximately along the Trans-Antarctic Mountains, with the EAIS divided into 16 basins, the WAIS into seven and the Antarctic Peninsula into four. The areas cover 12,377,790 km² in total.
Zwally Greenland Basins
In Greenland, 19 basins ('1.1', '1.2', '1.3', '1.4', '2.1', '2.2', '3.1', '3.2','3.3', '4.1', '4.2', '4.3', '5.0', '6.1', '6.2', '7.1', '7.2', '8.1', '8.2' in IMBIE-3 file formats) cover 1.722.572 km² in total.
The 19 basins in Greenland are grouped into eight separate regions ('1'=North, '2'=North-East, '3'=East, '4'=South-East, '5'=South, '6'=South-West, '7'=West, '8'=North-West). These delineations are shown in the figures below.
Zwally Basin Downloads
Drainage basin and ice sheet outlines in lat/lon vector format can be downloaded from the following links:
- Zwally Antarctic Drainage Basins
- Zwally Greenland Drainage Basins
- Zwally Antarctic Ice Sheets
- Zwally Greenland Ice Sheets
If required, further information on these drainage basin definitions may be found at:
https://earth.gsfc.nasa.gov/cryo/data/polar-altimetry/antarctic-and-greenland-drainage-systems
References
Giovinetto, M.B. and H.J. Zwally, 2000. Spatial distribution of net surface accumulation on the Antarctic ice sheet. Annals of Glaciology, 31, 171-178.
Rignot Basins
Rignot Antarctic Basins
Antarctica is separated into WAIS, EAIS and AP based on historical definitions plus information from modern-day DEM and ice velocity data. AP is limited by Ronne to the east and George VI to the west. WAIS and EAIS are divided along the Transantarctic range; WAIS drains into Ronne, EAIS drains into Filchner. The basin boundaries are defined with a posting of ~ 150m. Within these three ice sheet regions, subregions A, B, C, Cp, etc. are defined based on historical nomenclature (Giovinetto and Zwally, 2000) plus modern DEM and ice velocity data, and adjusted to match the drainage boundaries of the major ice shelves. Grounding lines, area, ice fronts of all ice shelves are based on (Rignot et al., 2013). The interior basins rely on an ERS/ICESat DEM in the interior and the 2011 velocity mosaic (flow direction) near the coast. The basins are close to an earlier definition (Rignot et al., 2011a) where no area is left out, and hence can be used for altimetry, gravity and mass-budget alike. Grounding lines are InSAR 2011 (NSIDC). Surrounding glaciers and ice caps are in one separate shape file. Sub-sub-divisions are not included at this stage.
Rignot Greenland Basins
Greenland ice drainage units are based on historical usage (Rignot et al., 2011b). The regions are separated based on glacier regime (marine-terminating dominance versus land-terminating) and SMB (dry vs wet). NW and CW has a clear basin boundary near Rinks. CW to SW marks the transition from tidewater to land-terminating. SE vs NE is at a major transition in SMB with a well-defined divide inland. Our delineation uses the GIMP DEM, and an ice velocity data set (Rignot and Mouginot, 2012). All surrounding ice caps and glaciers are in one shape file “islands”. Ice margin is from GIMP. Sub-sub-divisions are not included.
Rignot Basin Downloads
- Rignot Antarctic Drainage Basins
- Rignot Greenland Drainage Basins
- Rignot Antarctic Ice Sheets
- Rignot Greenland Ice Sheets
References
- Rignot, E., J. Mouginot, and B. Scheuchl, 2011a. Antarctic Grounding Line Mapping from Differential Satellite Radar Interferometry, Geophysical Research Letters, 38, L10504, DOI: 10.1029/2011GL047109
- Rignot, E., Velicogna, I., Van Den Broeke, M. R., Monaghan, A., Lenaerts, J., 2011b. Acceleration of the contribution of the Greenland and Antarctic ice sheets to sea level rise, Geophysical Research Letters, 38 (5), art. no. L05503, DOI: 10.1029/2011GL046583
- Rignot, E., Mouginot, J., 2012. Ice flow in Greenland for the International Polar Year 2008-2009, Geophysical Research Letters, 39 (11), art. no. L11501. DOI: 10.1029/2012GL051634
- Rignot, E., S. Jacobs, J. Mouginot, and B. Scheuchl, 2013. Ice Shelf Melting Around Antarctica. Science, 341(6143): 266-270. DOI: 10.1126/science.1235798