Welcome to ECODATA-Animate’s documentation!#

ECODATA-Animate#

ECODATA-Animate is a MATLAB® program for creating customized animated maps of animal movements. The program creates image frames that can be animated using the ECODATA-Prepare Movie Maker App. Define track visualization options and include additional layers from raster files, shapefiles, an elevation model and label lists. See ECODATA-Prepare for additional tools for preparing input data. Development is supported by MathWorks® and the NASA Earth Science Division, Ecological Forecasting Program, as part of the Room to Roam: Y2Y Wildlife Movements project.

Check out the documentation! App documentation Developer guide

Note: ECODATA-Animate is in the early stages of development, and any feedback is welcome! If you have any suggestions or feature requests, enounter any bugs, or come across places where the documentation is unclear, please submit a GitHub issue.

User guide#

User guide#

ECODATA-Animate is a MATLAB® program for creating customized animated maps of animal movements. The program creates image frames that can be animated using the ECODATA-Prepare Movie Maker App.

Tip

This user guide can also be downloaded for offline use! Click here to download the documentation in PDF, Epub, or zipped HTML format.

Installation#

  1. Download the installers for the latest release here, available for Mac and Windows. You can also see all releases (including pre-release versions) here.

  2. A zipped folder containing the installer and the ECODATA-Animate application will be downloaded to your computer. Extract the files (you may also move them to a different folder on your computer).

  3. If this is the first time you have installed the app, open the ECODATA_Animate_Installer application to run the installer, and follow the on-screen prompts. If you have installed a previous version of the app (and therefore have MATLAB runtime installed already), you should be able to simply run the ECODATA_Animate file without needing to run the installer again.

  4. Once the application has been successfully installed, you can open the ECODATA-Animate application. (There may be a short delay (10+ seconds) after launching the ECODATA-Animate application before the program opens. A log file will also be generated in the installer folder.)

Getting started#

Before using this program, prepare data to include in the animation. Inputs to ECODATA-Animate include the following:

  • A file of movement track data in Movebank format (required) that can include additional columns.

  • 1 or 2 static and/or dynamic raster files (maps) in NetCDF-4 format (optional). These can be used as background layers for the animation, with the possibility to display one layer as a colormap and the other with contour lines.

  • Shapefiles with points, lines, or polygons containing other vector data you want to display (optional). For example, you could use this to include water bodies, roads or property lines.

  • A list of points to label on the map in .csv format (optional), with the option to restrict the display of the label to a range of dates.

  • In addition, you can display elevation contours using a stored digital elevation model (DEM) that does not require a user file.

Using the app#

Overview of steps#

  1. Use the tabs at the top of the application to define the contents of the animation. You can work on the tabs in any order.

  1. Create a folder in which to save the results (a large number of .png files).

  2. Click “Set output file” to specify the folder location. The file browser window is sometimes hidden behind other windows.

  3. Click on the ECODATA_Animate icon from the Dock (on Mac) or close other windows to find it.

  4. After providing all input data and configurations, click “Create animation”.

  5. Watch “Status” in the lower right to monitor progress. It may take a minute before a message appears. It should say “Generating animation… Please be patient”. Do not shut down your computer, move or rename the folder, or change settings, while this step is in progress. As frames are created, they will be saved in the specified folder.

  6. After processing is complete, you will see the message “Animation saved to the output directory”. If the processing fails, error messages will be posted here. You can search for and report errors or unexpected results here.

  7. The results consist of a set of .png image files representing each frame for the animation, based on the chosen configuration, which can be viewed or used individually.

  8. Use the ECODATA-Prepare Movie Maker App to compile these images into an animation.

General notes#

  • Expect some trial and error as you define settings and see how they appear in the saved frames.

  • To review results with minimal processing time, you can start by generating just the last frame of the animation (select Generate last frame only under Track visualization options. Or, you can limit the “time range” under “Animal track data”, so that fewer frames are created. Once the settings are as desired, extend the time range to that of the full dataset for final processing.

  • When clicking a button to select a filepath, the browser window might not automatically appear, and may be hidden behind other application windows or displayed on another monitor. Minimizing other windows or clicking on the application icon from the Dock may help to find it. ecodata-animate_dock_icon

  • After selecting a file or setting the output filepath, expect that it may take several seconds before the information loads or updates appear in the status window.

  • Note that if you select an output directory that already has output files in it, these will be overwritten when you create a new animation.

  • For help or to share suggestions, submit a GitHub issue or contact support@movebank.org.

Saving and reloading settings#

  • When an animation is created, the animation settings are saved to the output directory in a file called settings.mat.

  • Settings files can be reloaded into the app. To reload settings from a previous animation, click the Load settings button at the top of the app, and select a settings.mat file. You can then adjust the settings for a new animation.

Animation instructions#

Inputs and settings#

After opening the program, you will see a main window with six tabs, each containing settings for different input data. Settings and instructions for each tab are provided below.

app_gui

Animal track data#

Here you upload a file of animal tracking data to animate. This should follow the format used when accessing data from Movebank, following formats described in the Movebank Attribute Dictionary. This file should contain at least the attributes timestamp, location-long and location-lat. It can be composed of tracking data subsets or combinations from multiple Movebank studies, as well as additional columns such as environmental covariates from Env-DATA or MoveApps, or reference data attributes.

  1. Click on Select track data. Browse to the .csv file containing your tracking data.

  2. After the file is loaded, the filepath will be displayed, and the time range and geographic extent will be automatically populated based on the contents of the file.

  3. Optionally, update the selected individuals, time range, or geographic extent as needed to refine what to include in the animation. Select Update filters to save your selections and calculate a summary of the contents of the filtered dataset.

Track visualization options#

track_visualization_options

Here you define how the tracking data will be displayed in the animation, as well as the time period represented by each frame (in Track frequency).

  • Use the options on the left to define the design of the markers used to show the animals on the map. You can color the tracks by any attribute of the data (by default, the individual_local_identifier, or animal ID, is used).

  • Use Track frequency to define the number of hours to represent in each frame of the animation. The track data are always resampled to this frequency for animation. For example, if it is set to 24 hours, the animation will generate one frame per day. Consider the sampling frequency in your tracking and environmental data, the length of time being animated, and how long you want the animation to be.

  • Use Track memory to define the length of time to continue to show the movement trail, in terms of the track frequency. For example, if the track frequency is set to 24 (hours) and the track memory is set to 20, then a trail of the previous 20 days will be shown.

  • Use Track opacity to define the transparency of the trail, with 0 being fully transparent and 1 being fully opaque.

  • If the Fade tracks button is checked, the Track opacity setting is ignored and instead the trail will fade out with a “comet” effect.

  • To choose your own track color/s, check the Use custom colors box and click on Add color. You can select from a default palette or define colors using RGB, hexadecimal or HSV codes.

standard_color_picker custom_color_picker

Environmental data#

Here you can optionally select 1 or 2 static and/or dynamic raster files in NetCDF-4 format to use as background layers for the animation. One will be displayed as a colormap and the other with contour lines. You can request a variety of environmental raster data using NASA’s AppEEARS service. While the program is designed to handle very large files, for more efficient processing and storage, use raster data only at the resolution needed for the animation. Files can be preprocessed to an appropriate resolution and masked using polygons with the ECODATA-Prepare Gridded Data Explorer App.

  1. Click on Select gridded data and browse to a NetCDF (.nc) file containing raster environmental data to use as a color map in the background of the animation.

  2. The app will attempt to populate the variables that define the time, location coordinates, and the variable to display in the animation. Review the results and click the dropdown boxes to update if needed.

  3. Choose a color map. Current options are green, blue, diverging, and jet. By default, “green” will display lower values in darker colors. Check Invert color map to reverse this scale (for example, to show higher NDVI or EVI values in darker green).

  4. Click on Select contour data and browse to a .nc file containing raster environmental data to display data from a raster file as contour lines in the background of the animation.

  5. The app will attempt to populate the variables that define the time, location coordinates, and the variable to display in the animation. Review the results and click the dropdown boxes to update if needed.

  6. Choose a color and width for the contour lines, and check the box next to Show contour text to display labels.

Shapefiles#

Here you can optionally select shapefiles to display in your animation frames. These layers will appear beneath the animal tracks and above the environmental (raster) data layers. Note that these layers will be drawn in the order that they are entered (i.e. the first layer in the list will be drawn first, so it will be on the bottom).

  1. Click on an Select shapefile button and browse to a shapefile containing a vector data layer to display in the animation.

  2. Available display properties will depend on the type of vector layer:

  • Polygons: Select a color for polygon outlines (Edge color) and fill (Face color), and define the fill transparency (Face opacity, 1 = fully opaque).

  • Lines: Select a line color and width.

  • Points: Select a color, marker style, and marker size.

    You can choose from the default colors in the dropdown box, or enter a custom color using a hexadecimal color value (e.g., “#97d2f0”), which you can choose using a color picker like this one or by identifying the color value in other files using graphics or mapping software.

  1. Repeat steps 1 and 2 to add additional shapefile layers, if desired.

  2. If you want to remove shapefiles you have entered, you can click Clear all shapefiles to remove all of them, or Clear last shapefile to clear just the last one that was entered.

Labeled points#

Here you can optionally define arbitrary points and labels to display in the animation, for example to identify place names or times and locations of relevant events.

  1. Prepare a .csv file containing labels and their placement on the map. This file can be prepared using a spreadsheet (e.g., Excel), as long it is saved as a .csv file. Information to include is as follows (all coordinates in decimal deg):

    • longitude and latitude (required): coordinates for the location of interest, in decimal degrees, WGS84

    • label (required): the text to display

    • start_time and end_time (optional): can be used to restrict the display of the label to the specified range of dates, in format yyyy-mm-dd

    • label_longitude and label_latitude (optional): coordinates where the label text should be placed on the map (left edge of label if the point is to the left of the label, right edge if the point is to the right of the label). This option is used if the label placement needs adjustment.

    • horizontal_alignment (optional): “right” or “left”, indicating the alignment of the point relative to the label (e.g., “left” means that the point will be aligned to the left of the label). Defaults to “left” if not otherwise specified.

    An example will look something like this (this example is displayed in table format for easier reading, but note that the file must be saved in .csv format):

    longitude

    latitude

    label

    start_time

    end_time

    label_longitude

    label_latitude

    horizontal_alignment

    -123

    56

    Test point 1

    2015-07-20

    2015-07-30

    -123.1

    56.1

    -121.5

    54.5

    Test point 2

    right

    In .csv format:

    longitude,latitude,label,start_time,end_time,label_longitude,label_latitude,horizontal_alignment
-123,56,Test point 1,2015-07-20,2015-07-30,-123.1,56.1,
-121.5,54.5,Test point 2,,,,,right

    Note that only the longitude, latutude, and label columns are required, and rows can also be left empty in the optional columns.

  2. Click on Select file and browse to the .csv file with the label information.

  3. Adjust the marker color and size as desired.

Elevation#

animate_elevation

Here you can optionally select to display elevation contours, based on the ETOPO1 1-Arc-Minute Global Relief Model.

  1. Check Include elevation contours to draw these on the map.

  2. If selected, review or update the number of levels and line design to use, and choose whether or not to display labels on the contour lines.

Support#

ECODATA is in the early stages of development, and any feedback is welcome! If you have any suggestions or feature requests, enounter any bugs, or come across places where the documentation is unclear, please submit a Gitub issue!

Developer guide#

Contributing#

Check out this simple guide for using git.

  1. Create a new branch for your contributions.

  2. Commit your changes in this branch.

  3. Open a pull request to merge changes from your branch into the repository’s develop branch.

Documentation#

Documentation for this project is created using Sphinx and is hosted at Read the Docs (https://ecodata-animate.readthedocs.io/). The source files for these pages are located in the docs folder of the repository. To edit the documentation, edit the markdown files in this folder (or sub-folders). Note that the docs/index.md file specifies the contents for the docs site. If a sub-folder has a index.md file, that file specifies the contents for that section of the docs site (e.g. docs/user_guide/index.md). If files are added or removed, the corresponsing index files will also need to be updated.

Building the docs#

After editing the pages, you can look at a build of the pages to see how things will actually look in the docs website. There are two options for this:

  • Option 1: Open a pull request, and Read the Docs will build a preview of the docs pages. A link to the build can be found near the bottom of the page of the PR, in the merge checks section. You may have to click “Show details” next to where it says “All checks have passed”. Once the build is finished, click on “Details” for the docs/readthedocs.org:ecodata-animate item: rtd_status_check

    This will take you to the build for the PR. Once the build is finished, click on the “View docs” link to the right of build info:

    view_rtd_build

    Note that the large green “View docs” button at the top of the page takes you to the current docs page, not the PR build. When viewing the docs build for a PR, you should see a banner at the top of the docs pages that looks like this: rtd_pr_banner

    You can push additional commits to the open PR if you want to change anything after seeing the preview build. Read the docs will build a new preview whenever a new commit is made to the PR.

  • Option 2: Build the docs locally. You will need to have python and the docs requirements installed.

    • To install the doc requirements: pip install sphinx furo sphinxcontrib-matlabdomain myst-parser or install using the conda or pip requirements file (located in the docs directory)

    • Build the docs: sphinx-build -b html docs docs/_build

    • To view the build, open the index.html in the docs/_build directory that was created.

Versions of the docs#

  • Read the Docs builds multiple versions of the documentation (for different branches of the repository). In the bottom corner of the docs pages, there is a box indicating which version you are viewing. You can click on that box to pick a different version.

Setup instructions for the MATLAB code#

Adding datasets#

  • Most of the datasets are too large to be stored in the repository

  • Datasets used in the example scripts can be downloaded here

  • Copy any datasets you want to use to data/user_datasets

Adding topo data for the m_map package#

Required toolboxes#

The mapping toolbox and the MATLAB Compiler need to be installed.

Specifying Movebank login credentials:#

  • Save movebank_credentials_template.txt as movebank_credentials.txt and update it with your username and password.

  • movebank_credentials.txt is in the .gitignore so it won’t be tracked.

Compiling the app#

This process needs to be done on both Mac and Windows, to build installers for both systems.

  • Make sure the topo dataset has been downloaded and added to the m_map folder! (see above)

  • Open apps/animator.mlapp

  • Edit “Sharing Details” (this can be found if “animator” is selected in the component browser):

    • Update the version (major.minor)

    • Update the description with the release tag

  • In the top menu, click Share, then Standalone Desktop App

  • In the compiler window:

    • In the top menu, select Runtime downloaded from web, then change the name in the textbox to ECODATA_Animate_Installer

    • In the version box, edit the version (which was auto-filled with major.minor from the .mlapp file). This needs to be updated to major.minor.bugfix.release_candidate (making sure this corresponds to the release tag on GitHub)

    • Under Files required for your application to run, make sure the functions and m_map folders are both added!

    • Under Additional runtime settings, select the create log file box, and change the name to ecodata_animate_log

    • Click the Packagebutton in the top menu.

    • Make a new folder called Mac_Installer or Windows_Installer.

    • From the output folder created by the compiler, copy the files for_redistribution/ECODATA_Animate_Installer and for_redistribution_files_only/ECODATA_Animate to the new folder.

    • Compress the folder to a .zip. The two .zip folders (for Mac and Windows) are what need to be uploaded as release assets.

Indices and tables#