Commit b5288c83 authored by GROUAZEL's avatar GROUAZEL
Browse files

merge docs/index.rst conflict solved using remote

parents e7de75b4 5924936f
......@@ -19,10 +19,12 @@ import os
import argparse
import importlib
from datetime import datetime
import random
import string
from netCDF4 import num2date
from cerbereutils.resampling.resampler import Resampler
from cerinterp.resampler import Resampler
from cerbere.mapper.ncfile import NCFile
from cerbere.mapper.abstractmapper import AbstractMapper, WRITE_NEW
......@@ -36,34 +38,32 @@ def instantiate_features(srcproduct,
targetmodelclass,
srcmapperclass,
targetmapperclass,
srcargs):
srcslices=None,
targetslices=None,
**kwargs):
"""Instantiate source and target feature objects from model, mapper and
file path.
Args:
srcproduct (str): full path to the source product file.
targetproduct (str): full path to the target product file.
srcmodelclass (:class:AbstractFeature): data model class of source
feature.
targetmodelclass (:class:AbstractFeature): data model class of target
feature.
srcmapperclass (:class:AbstractMapper): mapper class for the source
product file.
targetmapperclass (:class:AbstractMapper): mapper class for the target
product file.
srcslices (str, optional): slices for
targetslices (str, optional): full path to the target product file.
srcargs (dict): additional input arguments for source mapper
instantiation.
"""
source = srcmodelclass()
target = targetmodelclass()
srcmapper = srcmapperclass(url=srcproduct,
**srcargs)
**kwargs)
targetmapper = targetmapperclass(url=targetproduct)
# detect if grid file is centered on meridian 180
# TODO: to be improved by using a more flexible interpolator
......@@ -71,8 +71,8 @@ def instantiate_features(srcproduct,
is_centered_on_180(srcmapperclass, srcproduct):
srcmapper.center_on_greenwhich = True
source.load(srcmapper)
target.load(targetmapper)
source.load(srcmapper, view=srcslices)
target.load(targetmapper, view=targetslices)
return source, target
......@@ -116,10 +116,11 @@ def resample(srcfeature,
for k in method.split('/')[1:]}
if method_name == 'closest_neighbour':
if 'radius' in method_kwargs:
radius = method_kwargs['radius']
radius = float(method_kwargs['radius'])
else:
# 1.5 = approx. sqrt(2)
# value is converted from degree to meter
# !!!! TODO: THERE IS INCONSISTENCY HERE BETWEEN RES IN KM OR DEG
radius = srcfeature.get_spatial_resolution() / 2. * 150000
outfeature = Resampler.closest_neighbour(srcfeature,
targetfeature,
......@@ -171,17 +172,19 @@ def resample(srcfeature,
field.set_values(
srcfeature.get_geolocation_field('time').get_values().copy()
)
print srcfeature.get_geolocation_field('time').get_values()
outfeature._geolocation_fields['time'] = field
print outfeature.get_geolocation_field('time').get_values()
# save file
if not os.path.exists(outdir):
os.makedirs(outdir)
if filename is None:
srcname = srcfeature.get_mapper().get_basename()
randomcode = ''.join(random.SystemRandom().choice(
string.ascii_uppercase + string.digits)
for _ in range(6))
fname = os.path.join(outdir,
'-'.join([mintime.strftime('%Y%m%dT%H%M%S'),
'RESAMP',
randomcode,
srcname])
)
else:
......@@ -252,10 +255,31 @@ def get_options():
" data in the remapped file where VALUE is set"
" (slash separated)"
)
parser.add_argument("-s", "--source_subset",
action="store",
dest="source_slices",
help="slices (in cerbere syntax) for the source feature "
"Only the subset defined by this slices will be "
"extracted and resampled.")
parser.add_argument("-S", "--target_subset",
action="store",
dest="target_slices",
help="slices (in cerbere syntax) for the target feature "
"Only the subset defined by this slices will be "
"extracted.")
options = parser.parse_args()
assert options.resampling_method.split('/')[0] in RESAMPLING_METHODS,\
'Unknown resampling method'
if options.resampling_method:
if '/' in options.resampling_method:
methodname = options.resampling_method.split('/')[0]
else:
methodname = options.resampling_method
if methodname not in RESAMPLING_METHODS:
raise Exception("Resampling method must be closest_neighbour or"
"bilinear. You provided a bad expression: %s",
options.resampling_method)
return options
......@@ -266,7 +290,6 @@ def is_centered_on_180(srcmapperclass, srcproduct):
lons = mapper.read_values('lon')
res = False
if lons[0] > lons[-1]:
print "IS CNTERED"
res = True
mapper.close()
return res
......@@ -293,7 +316,10 @@ if __name__ == "__main__":
use_source_time = True
else:
use_source_time = False
method = options.resampling_method
if options.resampling_method:
method = options.resampling_method
else:
method = 'closest_neighbour'
# source mapper
input_args = {}
if not options.source_mapper:
......@@ -370,6 +396,17 @@ if __name__ == "__main__":
'%Y%m%dT%H%M%S')
else:
timestep = None
# slices
if options.source_slices:
value = options.source_slices
source_slices = eval(value)
else:
source_slices = None
if options.target_slices:
value = options.target_slices
target_slices = eval(value)
else:
target_slices = None
# instantiate features
srcfeature, targetfeature = instantiate_features(
......@@ -379,7 +416,9 @@ if __name__ == "__main__":
targetmodelclass=target_datamodel,
srcmapperclass=source_mapper,
targetmapperclass=target_mapper,
srcargs=input_args
srcslices=source_slices,
targetslices=target_slices,
**input_args
)
if not options.target_mask:
mask = None
......@@ -408,6 +447,7 @@ if __name__ == "__main__":
if srcfeature.__class__.__name__ == 'GridTimeSeries':
if timestep is not None:
srcfeature = srcfeature.extract_grid(time=timestep)
resample(srcfeature,
targetfeature,
fields=fieldnames,
......
......@@ -349,7 +349,7 @@ class Resampler(object):
valid_input_index, valid_output_index, index_array, distance_array\
= kd_tree.get_neighbour_info(source_def,
target_def,
radius,
radius_of_influence=float(radius),
reduce_data=False,
neighbours=1
)
......@@ -384,7 +384,7 @@ class Resampler(object):
valid_input_index, valid_output_index, index_array, distance_array\
= Resampler.__get_closest_neighbour_info(source_def,
target_def,
radius)
radius_of_influence=radius)
if not valid_input_index.any():
# return None if no source data can be resampled on the
# target
......
===============================================
`add_tide` : adding tidal currents to a feature
===============================================
The `add_tide` command line creates a new file with the tidal current
components (northward and eastward) at every time and location of a given
feature (e.g. at all pixels of a swath, grid or track).
It is based on the :mod:`~cerbereutils.ancillary.tide` module.
Usage
=====
.. program:: add_tide
::
add_tide [-h] [-o OUTPUT] [-m MAPPER] [-d DATAMODEL] [-t TIDAL_MODEL]
[-k string] source_file
Add the tidal current components at each pixel time and location of the feature
given in input.
.. option:: -h, --help
show this help message and exit.
.. option:: feature_file
full path to the source file that stores the feature on which to compute the
tidal currents.
.. option:: -d, --source-model-class <DATAMODEL>
The name of the datamodel class of the feature (in **cerbere** library).
.. option:: m, --source-mapper-class <MAPPER>
The name of the mapper class of the feature (in **cerbere** library), used
to read the source_file data.
.. option:: t, --tidal-model <TIDAL_MODEL>
The name of the tide model to apply (currently only `fes2012` is available).
.. option:: -k, --mask <VARIABLE>
The processing of the tide values can take a lot of time. It is therefore
recommended to avoid processing over areas which are irrelevant (such as
land or where there are no valid data in the feature). For this, you can
specify a variable in the feature file, which native mask (as in a numpy
MaskedArray) will be used : tidal currents will not be estimated over the
masked areas.
Examples
========
Over a SAR image
----------------
Computing the tide field over a SAR image from Soprano database.
* the datamodel is :class:`~cerbere.datamodel.image.Image`
* the mapper is :class:`~cerbere.mapper.sopranoncfile.SopranoNCFile`
* we prevent from processing the tide over irrelevant areas by using the
mask of the MaskedArray returned by the variable `quality_flag`.
::
$ add_tide -p /home/cerdata/provider/cls/satellite/l2/envisat/asar/soprano-wind/2012/081/ASA_WSM_1PNPDE20120321_101733_000000923113_00008_52608_4735_SAR_wind.nc -m SopranoNCFile -d Image -k quality_flag
This results in two vector components, northward and eastward, for tidal
currents at each valid pixel of the SAR image.:
.. image:: ./images/tide_sar_eastward.png
.. image:: ./images/tide_sar_northward.png
Over a Grid
-----------
Gridding over the GlobCurrent/WaveWatch3 stokes grid::
$ add_tide -p /home/cercache/project/globcurrent/data/workdata/resampled/global_010/model/wind/ww3_ifremer_global_hindcast/20120930210000_RESAMP_ww3.201209_wnd.nc -m NCFile -d Grid -k uuss
Over an altimeter track
-----------------------
Adding tide over a altimeter track::
......@@ -50,13 +50,14 @@ the **closest neighbour** method (`-a closest_neighbour`)
.. Note::
The outfile keeps all important information to trace back to the original
data.
* `lat`, `lon`, and `time` are preserved in the `resampled_lat`,
`resampled_lon`, `resampled_time` fields.
* the indices of the resampled data in the source files are preserved
in the `resampled_x` and `resampled_y` variables
* the `distance_to_pixel` contains the distance from the original pixel
to its reprojected location.
data:
* `lat`, `lon`, and `time` are preserved in the `resampled_lat`,
`resampled_lon`, `resampled_time` fields.
* the indices of the resampled data in the source files are preserved
in the `resampled_x` and `resampled_y` variables
* the `distance_to_pixel` contains the distance from the original pixel
to its reprojected location.
The resampled zonal Stokes drift looks as follow:
......
ancillary package
=================
:mod:`ancillary` Package
------------------------
.. automodule:: cerbereutils.ancillary
:members:
:undoc-members:
:show-inheritance:
:mod:`icemask` Module
---------------------
.. automodule:: cerbereutils.ancillary.icemask
:members:
:undoc-members:
:show-inheritance:
:mod:`landmask` Module
----------------------
.. automodule:: cerbereutils.ancillary.landmask
:members:
:undoc-members:
:show-inheritance:
:mod:`tide` Module
------------------
.. automodule:: cerbereutils.ancillary.tide
:members:
:undoc-members:
:show-inheritance:
plot Package
=============
:mod:`plot` Package
-------------------
.. automodule:: cerbereutils.plot
:members:
:undoc-members:
:show-inheritance:
:mod:`mapping` Module
---------------------
.. automodule:: cerbereutils.plot.mapping
:members:
:undoc-members:
:show-inheritance:
:mod:`palette` Module
---------------------
.. automodule:: cerbereutils.plot.palette
:members:
:undoc-members:
:show-inheritance:
cerbereutils Package
====================
:mod:`resampler` Package
------------------------
.. automodule:: cerbere.resampler
:members:
:undoc-members:
:show-inheritance:
science Package
===============
:mod:`science` Package
----------------------
.. automodule:: cerbereutils.science
:members:
:undoc-members:
:show-inheritance:
:mod:`zenital` Module
---------------------
.. automodule:: cerbereutils.science.zenital
:members:
:undoc-members:
:show-inheritance:
resampling Package
==================
resampler Package
=================
:mod:`resampling` Package
:mod:`resampler` Package
------------------------
.. automodule:: cerbereutils.resampling
:members:
:undoc-members:
:show-inheritance:
:mod:`resampler` Module
-----------------------------
.. automodule:: cerbereutils.resampling.resampler
.. automodule:: cerinterp.resampler
:members:
:undoc-members:
:show-inheritance:
......@@ -20,7 +12,7 @@ resampling Package
:mod:`fastregrid` Module
-------------------------------
.. automodule:: cerbereutils.resampling.fastregrid
.. automodule:: cerinterp.fastregrid
:members:
:undoc-members:
:show-inheritance:
......
cerbereutils Package
====================
cerinterp Package
=================
:mod:`cerbereutils` Package
:mod:`cerinterp` Package
---------------------------
.. automodule:: cerbereutils
.. automodule:: cerinterp
:members:
:undoc-members:
:show-inheritance:
......@@ -14,8 +14,5 @@ Subpackages
.. toctree::
:maxdepth: 4
cerbereutils.ancillary
cerbereutils.plot
cerbereutils.resampling
cerbereutils.science
cerinterp.resampler
.. cerbere documentation master file, created by
sphinx-quickstart on Tue Dec 10 15:47:17 2013.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to cerbere's reference documentation!
=============================================
Contents:
.. toctree::
:maxdepth: 4
cerbere
setup
......@@ -41,7 +41,7 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
project = u'cerbere-utils'
project = u'cerinterp'
copyright = u'2014, Jeff Piolle'
# The version info for the project you're documenting, acts as replacement for
......@@ -168,7 +168,7 @@ html_static_path = ['_static']
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'cerbereutilsdoc'
htmlhelp_basename = 'cerinterpdoc'
# -- Options for LaTeX output --------------------------------------------------
......@@ -187,7 +187,7 @@ latex_elements = {
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'cerbereutils.tex', u'cerbereutils Documentation',
('index', 'cerinterp.tex', u'cerinterp Documentation',
u'Jeff Piolle', 'manual'),
]
......@@ -217,7 +217,7 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'cerbereutils', u'cerbereutils Documentation',
('index', 'cerinterp', u'cerinterp Documentation',
[u'Jeff Piolle'], 1)
]
......@@ -231,8 +231,8 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'cerbere-utils', u'cerbere-utils Documentation',
u'Jeff Piolle', 'cerbere-utils', 'One line description of project.',
('index', 'cerinterp', u'cerinterp Documentation',
u'Jeff Piolle', 'cerinterp', 'One line description of project.',
'Miscellaneous'),
]
......@@ -252,7 +252,7 @@ texinfo_documents = [
# -- Options for Epub output ---------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = u'cerbere-utils'
epub_title = u'cerinterp'
epub_author = u'Jeff Piolle'
epub_publisher = u'Jeff Piolle'
epub_copyright = u'2014, Jeff Piolle'
......@@ -305,3 +305,38 @@ epub_copyright = u'2014, Jeff Piolle'
# If false, no index is generated.
#epub_use_index = True
# to short-cut some libs when reading the doc
class Mock(object):
__all__ = []
def __init__(self, *args, **kwargs):
pass
def __call__(self, *args, **kwargs):
return Mock()
@classmethod
def __getattr__(cls, name):
if name in ('__file__', '__path__'):
return '/dev/null'
elif name[0] == name[0].upper():
mockType = type(name, (), {})
mockType.__module__ = __name__
return mockType
else:
return Mock()
MOCK_MODULES = ['numpy',
'scipy',
'gdal',
'Cython',
'Cython.Distutils',
'Cython.Distutils.build_ext',
'gdalconst'
]
for mod_name in MOCK_MODULES:
sys.modules[mod_name] = Mock()
========
Examples
========
This section provides various examples of resampling of features over other
features, using the ``cerresample`` command line tool.
Swath on Trajectory
===================
Only closest_neighbour resampling method is possible here.
Resampling a scatterometer swath (ASCAT) over a altimeter track (AltiKa)
------------------------------------------------------------------------
.. code-block:: bash
cerresample --source /export/home/sumba/git/naiad/test/data/ascat_a/ascat_20150101_095100_metopa_42560_eps_o_125_2300_ovw.l2.nc --target /export/home/sumba/git/naiad/test/data/saral/SRL_OPRSSHA_2PTS019_0809_20150101_114518_20150101_132355.EUM.nc -d Swath -D Trajectory -m NCFile -M Cryosat2NCFile -o . -a closest_neighbour/radius=25000.
cerresample --source /export/home/sumba/git/naiad/test/data/ascat_a/ascat_20150101_095100_metopa_42560_eps_o_125_2300_ovw.l2.nc --target /export/home/sumba/git/naiad/test/data/saral/SRL_OPRSSHA_2PTS019_0809_20150101_114518_20150101_132355.EUM.nc -d Swath -D Trajectory -m NCFile -M Cryosat2NCFile -o . -a closest_neighbour/radius=25000. -S '{"time": slice(1000, 2000, 1)}'
=======================================
===================================
Welcome to cerinterp documentation!
=======================================
===================================
*cerinterp* is a collection of modules to perform classic operations on
EO data such as:
* resampling a feature on top of another
* adding information such as bathymetry, distance to coast or tide
to data files
*cerinterp* is a complementary package to *cerbere* package to perform
resampling and interpolation operations on EO data.
It provides both modules and handy command-line tools to perform this kind
of operations.
It is based on the *cerbere* python library for the file readers (mapper
It uses the *cerbere* python library for the file readers (mapper
package) and features (datamodel package).
Reference documentation
=======================
.. toctree::
:maxdepth: 2
api/cerinterp
Utilities
=========
.. toctree::
:maxdepth: 2
cerresample
add_tide
examples